Yoshi Yamaguchi

メトリクスSDK

この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/otel/metrics/sdk/

翻訳元: open-telemetry/opentelemetry-specification v1.60.0（コミット 29ae8c7）

ステータス: Mixed

OpenTelemetryの利用者には、OpenTelemetry APIとの計装のやり取りが実際にテレメトリーを生成するための手段が必要です。OpenTelemetry SDK（以下、単にSDKと呼びます）は、この機能を利用者に提供するOpenTelemetry APIの実装です。

OpenTelemetryのすべての言語実装は、SDKをMUST提供するものとします。

MeterProvider

ステータス: Stable

MeterProviderは、Resourceを指定できる手段をMUST提供するものとします。Resourceが指定された場合、そのMeterProviderから取得されるすべてのMeterが生成するメトリクスに関連付けられるべきです（SHOULD）。トレーシングSDK仕様は、これを効率的に実装する方法についていくつかの提案を示しています。

MeterProviderの作成

SDKは、複数の独立したMeterProviderの作成を許容すべきです（SHOULD）。

Meterの作成

Meterインスタンスの作成は、MeterProviderを通じてのみ可能であるべきです（SHOULD）（APIを参照）。

MeterProviderは、Meterの取得APIをMUST実装するものとします。

利用者から提供された入力は、作成されるMeterに格納されるInstrumentationScopeインスタンスの作成にMUST使用されるものとします。

無効なname（nullまたは空文字列）が指定された場合、nullを返したり例外を発生させたりするのではなく、フォールバックとして動作するMeterをMUST返すものとし、そのnameは元の無効な値を保持すべきであり（SHOULD）、指定された値が無効であることを報告するメッセージがログにSHOULD記録されるものとします。

ステータス: Development - MeterProviderは、設定されたMeterConfiguratorを使って関連するMeterConfigをMUST計算するものとし、そのMeterConfigに準拠する振る舞いをするMeterをMUST作成するものとします。

設定

設定（すなわちMetricExporters、MetricReaders、Views、および（Development）MeterConfigurator）は、MeterProviderにMUST所有されるものとします。設定は、適切であればMeterProvider作成時に適用されてもかまいません（MAY）。

MeterProviderは、設定を更新する方法を提供してもかまいません（MAY）。設定が更新された場合（例えばMetricReaderの追加）、更新された設定はすでに返されているすべてのMeterにもMUST適用されるものとします（すなわち、Meterが設定変更の前後どちらにMeterProviderから取得されたかはMUST NOT問題にならないものとします）。注: 実装上、これはMeterインスタンスが自身のMeterProviderへの参照を持ち、この参照を介してのみ設定にアクセスすることを意味する場合があります。

MeterConfigurator

ステータス: Development

MeterConfiguratorは、MeterのMeterConfigを計算する関数です。

この関数は以下のパラメータをMUST受け付けるものとします。

この関数は、関連するMeterConfig、またはデフォルトのMeterConfigを使うべきであることを示す何らかの信号をMUST返すものとします。この信号は、言語にとってイディオマティックな方法に応じて、nil、null、空、あるいはデフォルトMeterConfigのインスタンスであってもかまいません（MAY）。

この関数は、Meterが最初に作成されたときと、MeterProviderのMeterConfiguratorが更新されたとき（更新がサポートされている場合）に、現存するすべてのMeterについて呼び出されます。したがって、この関数がすぐに値を返すことが重要です。

MeterConfiguratorは柔軟性を最大化するために関数としてモデル化されています。しかし、実装は一般的な使用例に対応するため、簡略化された関数やヘルパー関数を提供してもかまいません（MAY）。

  • 名前で1つ以上のMeterを、完全一致またはパターンマッチングによって選択する。
  • 1つ以上の特定のMeterを無効にする。
  • すべてのMeterを無効にし、1つ以上の特定のMeterを選択的に有効にする。

Shutdown

このメソッドは、プロバイダーが必要なクリーンアップを行うための手段を提供します。

Shutdownは、MeterProviderインスタンスごとにMUST一度だけ呼び出されるものとします。Shutdownの呼び出し後、Meterを取得しようとするその後の試みは許可されません。SDKは、可能であればこれらの呼び出しに対して有効なno-op Meterを返すべきです（SHOULD）。

Shutdownは、呼び出し元に成功、失敗、タイムアウトのいずれであったかを知らせる手段をSHOULD提供するものとします。

Shutdownは、何らかのタイムアウト内に完了または中断すべきです（SHOULD）。Shutdownは、ブロッキングAPIとして実装されても、コールバックやイベントを通じて呼び出し元に通知する非同期APIとして実装されてもかまいません（MAY）。OpenTelemetry SDKの作者は、シャットダウンのタイムアウトを設定可能にするかどうかを決めてもかまいません（MAY）。

Shutdownは、登録されているすべてのMetricReaderとMetricExporterインスタンスに対してShutdownを呼び出すことによって、少なくともMUST実装されるものとします。

ForceFlush

このメソッドは、プロバイダーが、対応するPush Metric Exporterを持つ登録済みのMetricReaderインスタンスに通知し、メトリクスの収集と送信のためにできる限りのことを行わせる手段を提供します。注: Pull Metric Exporterは、スクレイパーから要求されたときにのみデータを送信できるため、ForceFlushはほとんど意味を持ちません。

ForceFlushは、ForceFlushを実装している登録済みのMetricReaderインスタンスすべてに対してForceFlushをMUST呼び出すものとします。

ForceFlushは、呼び出し元に成功、失敗、タイムアウトのいずれであったかを知らせる手段をSHOULD提供するものとします。ForceFlushは、エラー状態がある場合は何らかのERRORステータスを返すべきであり（SHOULD）、エラー状態がない場合は何らかのNO ERRORステータスを返すべきです（SHOULD）。言語実装は、ERRORとNO ERRORをどのようにモデル化するかを決めてもかまいません（MAY）。

ForceFlushは、何らかのタイムアウト内に完了または中断すべきです（SHOULD）。ForceFlushは、ブロッキングAPIとして実装されても、コールバックやイベントを通じて呼び出し元に通知する非同期APIとして実装されてもかまいません（MAY）。OpenTelemetry SDKの作者は、フラッシュのタイムアウトを設定可能にするかどうかを決めてもかまいません（MAY）。

View

Viewは、SDKによって出力されるメトリクスをカスタマイズする柔軟性をSDKの利用者に提供します。Viewが必要となる例をいくつか示します。

  • どのInstrumentを処理・無視するかをカスタマイズする。例えば、計装対象ライブラリが温度と湿度の両方を提供できるとしても、アプリケーション開発者が温度だけを必要としている場合があります。
  • 集約をカスタマイズする。Instrumentに関連付けられたデフォルトの集約が利用者の要求を満たさない場合です。例えば、HTTPクライアントライブラリはデフォルトでHTTPクライアントのリクエスト所要時間をHistogramとして公開しますが、アプリケーション開発者が発信リクエストの総数だけを必要としている場合があります。
  • メトリクスに報告される属性をカスタマイズする。例えば、HTTPサーバーライブラリはHTTPの動詞（GET、POSTなど）とHTTPステータスコード（200、301、404など）を公開しますが、アプリケーション開発者はHTTPステータスコードだけを気にかけている場合があります（例えばHTTPステータスコードごとのHTTPリクエストの総数を報告する）。アプリケーション開発者がいかなる属性も必要としない極端な場合もあり得ます（例えば、受信したすべてのリクエストの総数だけを取得する）。

SDKは、利用者がMeterProviderに対するViewを作成できる機能をMUST提供するものとします。この機能は、入力としてInstrumentの選択基準と、その結果得られるストリーム設定をMUST受け付けるものとします。

SDKは、MeterProviderにViewを登録する手段をMUST提供するものとします。

Instrumentの選択基準

Instrumentの選択基準とは、あるViewをInstrumentに適用するかどうかを決定する述語です。

基準は加算的に扱われるべきです（SHOULD）。これは、Viewが適用されるためにはInstrumentが提供されたすべての基準に一致する必要があることを意味します。例えば、基準が_instrument name == “Foobar”と_instrument type is Histogram_である場合、これは(instrument name == “Foobar”) AND (instrument type is Histogram)_として扱われます。

SDKは以下の基準をMUST受け付けるものとします。

  • name: 一致させるInstrumentの名前。このnameは、以下の方法でInstrumentに一致するよう評価されます。

    1. nameの値が*である場合、この基準はすべてのInstrumentに一致します。
    2. nameの値がInstrumentとまったく同じである場合、この基準はそのInstrumentに一致します。

    さらに、SDKは以下の文字を使ったname基準のワイルドカードパターンマッチングをサポートしてもかまいません（MAY）。

    • 疑問符（?）: 任意の1文字に一致します
    • アスタリスク（*）: 何もない場合を含む任意の数の任意の文字に一致します

    ワイルドカードパターンマッチングがサポートされている場合、name基準は、そのワイルドカードパターンがInstrumentの名前に一致すると評価されれば一致します。

    SDKが一般にワイルドカードをサポートしていない場合でも、特別な単一のアスタリスク（*）文字がすべてのInstrumentに一致することはMUST認識するものとします。

    利用者はnameを提供できますが、それは利用者の裁量に委ねられます。したがって、Instrument選択基準のパラメータはnameを受け付ける形で構造化する必要がありますが、利用者にそれを提供することをMUST NOT義務付けるものとします。

  • type: 一致させるInstrumentの種別。typeの値がInstrumentの種別と同じである場合、この基準はそのInstrumentに一致します。

    利用者はtypeを提供できますが、それは利用者の裁量に委ねられます。したがって、Instrument選択基準のパラメータはtypeを受け付ける形で構造化する必要がありますが、利用者にそれを提供することをMUST NOT義務付けるものとします。

  • unit: unitの値がInstrumentの単位と同じである場合、この基準はそのInstrumentに一致します。

    利用者はunitを提供できますが、それは利用者の裁量に委ねられます。したがって、Instrument選択基準のパラメータはunitを受け付ける形で構造化する必要がありますが、利用者にそれを提供することをMUST NOT義務付けるものとします。

  • meter_name: meter_nameの値がInstrumentを作成したMeterと同じである場合、この基準はそのInstrumentに一致します。

    利用者はmeter_nameを提供できますが、それは利用者の裁量に委ねられます。したがって、Instrument選択基準のパラメータはmeter_nameを受け付ける形で構造化する必要がありますが、利用者にそれを提供することをMUST NOT義務付けるものとします。

  • meter_version: meter_versionの値がInstrumentを作成したMeterと同じバージョンである場合、この基準はそのInstrumentに一致します。

    利用者はmeter_versionを提供できますが、それは利用者の裁量に委ねられます。したがって、Instrument選択基準のパラメータはmeter_versionを受け付ける形で構造化する必要がありますが、利用者にそれを提供することをMUST NOT義務付けるものとします。

  • meter_schema_url: meter_schema_urlの値がInstrumentを作成したMeterと同じスキーマURLである場合、この基準はそのInstrumentに一致します。

    利用者はmeter_schema_urlを提供できますが、それは利用者の裁量に委ねられます。したがって、Instrument選択基準のパラメータはmeter_schema_urlを受け付ける形で構造化する必要がありますが、利用者にそれを提供することをMUST NOT義務付けるものとします。

SDKは追加の基準を受け付けてもかまいません（MAY）。例えば、強い型付けを持つ言語では、点の型に関する基準をサポートしてもかまいません（例えば、基底の数値が整数か有理数かに基づいてInstrumentを選択できるようにする）。利用者はSDKが受け付けるこうした追加の基準を提供できますが、それは利用者の裁量に委ねられます。したがって、Instrument選択基準は、これらの基準を受け付ける形で構造化してかまいませんが、利用者にそれらの提供をMUST NOT義務付けるものとします。

ストリーム設定

ストリーム設定とは、MeterProviderがテレメトリーパイプラインを定義するために使うメトリックストリームを定義するパラメータです。

SDKは以下のストリーム設定パラメータをMUST受け付けるものとします。

  • name: 使用すべきメトリックストリーム名。

    競合を避けるため、nameが提供される場合、そのViewは最大1個のInstrumentを選択するInstrumentセレクターを持つべきです（SHOULD）。ストリーム設定nameパラメータを持つViewのInstrument選択基準が複数のInstrumentを選択できる場合（すなわちワイルドカード）、SDKは初期化時のエラー処理の原則に従って早期に失敗してもかまいません（MAY）。

    利用者はnameを提供できますが、それは利用者の裁量に委ねられます。したがって、ストリーム設定のパラメータはnameを受け付ける形で構造化する必要がありますが、利用者にそれを提供することをMUST NOT義務付けるものとします。利用者がnameの値を提供しない場合、デフォルトでそのViewが一致するInstrumentの名前がMUST使用されるものとします。

    ストリーム設定を介して提供されるnameは、Instrument名の構文に準拠することはREQUIREDではなく、SDKはこの構文に対してそれを検証することをMUST NOT行うものとします。

  • description: 使用すべきメトリックストリームの説明。

    利用者はdescriptionを提供できますが、それは利用者の裁量に委ねられます。したがって、ストリーム設定のパラメータはdescriptionを受け付ける形で構造化する必要がありますが、利用者にそれを提供することをMUST NOT義務付けるものとします。利用者がdescriptionの値を提供しない場合、デフォルトでそのViewが一致するInstrumentの説明がMUST使用されるものとします。

  • attribute_keys: これは、少なくとも、メトリックストリームで捕捉される測定値に対する属性キーの許可リストです。この許可リストには、保持しなければならない属性を識別する属性キーが含まれ、他のすべての属性はMUST無視されるものとします。

    実装は、このパラメータに対して追加の属性フィルタリング機能を受け付けてもかまいません（MAY）。

    利用者はattribute_keysを提供できますが、それは利用者の裁量に委ねられます。したがって、ストリーム設定のパラメータはattribute_keysを受け付ける形で構造化する必要がありますが、利用者にそれらを提供することをMUST NOT義務付けるものとします。利用者が値を提供しない場合、SDKは代わりにInstrumentに設定されたAttributes advisoryパラメータをSHOULD使用するものとします。Attributes advisoryパラメータが存在しない場合、すべての属性がMUST保持されるものとします。

    さらに、実装は属性キーの除外リストの設定をSHOULDサポートするものとします。この除外リストには、除外しなければならない属性を識別する属性キーが含まれ、他のすべての属性はMUST保持されるものとします。属性キーが許可リストと除外リストの両方に含まれる場合、SDKは初期化時のエラー処理の原則に従って早期に失敗してもかまいません（MAY）。

    [!NOTE] View設定によってメトリックストリームから除去された属性キー（例えば機密データを含む属性を除去するため）は、フィルタリングされた属性としてExemplarに引き続きエクスポートされる場合があります。これが望ましくない場合、AlwaysOff ExemplarFilterを設定してExemplarを無効にすることも、カスタムのExemplarFilterやExemplarReservoirを設定してExemplarとしてサンプリングされる測定値を制御することもできます。

    SDKのドキュメントは、View設定によってメトリックストリームから除外された属性がフィルタリングされた属性としてExemplarに引き続きエクスポートされる場合があることを利用者にSHOULD伝えるものとし、Exemplarサンプリングを無効化・設定する方法を記述すべきです（SHOULD）。

  • aggregation: メトリックストリームのデータを集約する際に使う集約関数の名前。

    利用者はaggregationを提供できますが、それは利用者の裁量に委ねられます。したがって、ストリーム設定のパラメータはaggregationを受け付ける形で構造化する必要がありますが、利用者にそれを提供することをMUST NOT義務付けるものとします。利用者がaggregationの値を提供しない場合、MeterProviderは、MetricReaderインスタンスに応じてInstrument種別に基づいて設定可能なデフォルト集約をMUST適用するものとします。

  • exemplar_reservoir: MeterProviderがexemplarを格納する際に使うexemplarレザバーを生成する関数型。この関数型は、集約によって異なるレザバーを選択できるようにする、集約選択機能に類似したファクトリまたはコールバックである必要があります。

    利用者はexemplar_reservoirを提供できますが、それは利用者の裁量に委ねられます。したがって、ストリーム設定のパラメータはexemplar_reservoirを受け付ける形で構造化する必要がありますが、利用者にそれを提供することをMUST NOT義務付けるものとします。利用者がexemplar_reservoirの値を提供しない場合、MeterProviderはデフォルトのexemplarレザバーをMUST適用するものとします。

  • aggregation_cardinality_limit: 単一のInstrumentによって1回の収集サイクルで出力できるデータポイントの最大数を定義する正の整数値。以下のカーディナリティ制限を参照してください。

    利用者はaggregation_cardinality_limitを提供できますが、それは利用者の裁量に委ねられます。したがって、ストリーム設定のパラメータはaggregation_cardinality_limitを受け付ける形で構造化する必要がありますが、利用者にそれを提供することをMUST NOT義務付けるものとします。利用者がaggregation_cardinality_limitの値を提供しない場合、MeterProviderは、MetricReaderに設定されたデフォルトの集約カーディナリティ制限をMUST適用するものとします。

Measurementの処理

SDKは、Instrumentで行われたMeasurementをどのように処理するかを決定するために、以下の論理をSHOULD使用するものとします。

  • そのInstrumentを「所有」するMeterProviderを特定する。
  • MeterProviderに登録されたViewがない場合、そのInstrumentを取り、MetricReaderインスタンスのaggregationプロパティに応じてInstrument種別に基づくデフォルトのAggregationを適用する。Instrument advisoryパラメータがあれば、それはMUST尊重されるものとする。
  • MeterProviderに1つ以上のViewが登録されている場合。
    • Instrumentが選択基準に一致する可能性がある場合、それぞれのViewについて。
      • 同じ一致するInstrumentに登録されている他のViewとは独立に、そのViewのストリーム設定を適用しようとする（すなわちViewはマージされない）。これにより、ストリーム設定が重複しないプロパティを指定していても（例えば、あるViewがaggregationを設定し、別のViewがattribute_keysを設定し、両方がストリームnameをInstrumentが設定するデフォルトのままにしている場合）、メトリックIDが衝突する可能性があります。Viewの適用がメトリックIDの衝突を招く場合、実装はそのViewを適用して警告を発すべきです（SHOULD）。セマンティックエラーを生じさせずにViewを適用することができない場合（例えば、Viewが非同期InstrumentにExplicit bucket histogram aggregationを使うように設定する場合）、実装は警告を発し、そのViewが適用されなかったかのように処理を続けるべきです（SHOULD）。ViewとInstrument advisoryパラメータの両方がストリーム設定の同じ側面を指定している場合、Viewで定義された設定はadvisoryパラメータよりMUST優先されるものとします。
    • Instrumentが登録されているどのViewにも一致しない場合、SDKはデフォルトの集約とtemporalityを使ってそのInstrumentを有効化すべきです（SHOULD）。利用者は、Drop aggregationを使ったすべてに一致するViewを設定することで、デフォルトでInstrumentを無効化できます。

Viewの例

MeterProviderに対してViewを作成するSDKの機能の例を示します。

# Python
'''
+------------------+
| MeterProvider    |
|   Meter A        |
|     Counter X    |
|     Histogram Y  |
|   Meter B        |
|     Gauge Z      |
+------------------+
'''

# metrics from X and Y (reported as Foo and Bar) will be exported
meter_provider
    .add_view("X")
    .add_view("Foo", instrument_name="Y")
    .add_view(
        "Bar",
        instrument_name="Y",
        aggregation=HistogramAggregation(buckets=[5.0, 10.0, 25.0, 50.0, 100.0]))
    .add_metric_reader(PeriodicExportingMetricReader(ConsoleExporter()))

# all the metrics will be exported using the default configuration
meter_provider.add_metric_reader(PeriodicExportingMetricReader(ConsoleExporter()))

# all the metrics will be exported using the default configuration
meter_provider
    .add_view("*") # a wildcard view that matches everything
    .add_metric_reader(PeriodicExportingMetricReader(ConsoleExporter()))

# Counter X will be exported as cumulative sum
meter_provider
    .add_view("X", aggregation=SumAggregation())
    .add_metric_reader(PeriodicExportingMetricReader(ConsoleExporter()))

# Counter X will be exported as a delta sum and the default attributes
# Counter X, Histogram Y, and Gauge Z will be exported with 2 attributes (a and b)
# A warning will be emitted for conflicting metric identities on Counter X (as two Views matching that Instrument
# are configured with the same default name X) and streams from both views will be exported
meter_provider
    .add_view("X", aggregation=SumAggregation())
    .add_view("*", attribute_keys=["a", "b"]) # wildcard view matches everything, including X
    .add_metric_reader(PeriodicExportingMetricReader(ConsoleExporter()),
              temporality=lambda kind: Delta if kind in [Counter, AsyncCounter, Histogram] else Cumulative)

# Only Counter X will be exported, with the default configuration (match-all drop aggregation does not result in
# conflicting metric identities)
meter_provider
    .add_view("X")
    .add_view("*", aggregation=DropAggregation()) # a wildcard view to disable all instruments
    .add_metric_reader(PeriodicExportingMetricReader(ConsoleExporter()))

Aggregation

Aggregationは、Viewを通じて設定され、Instrumentから得られるMeasurementから集約されたメトリクスを計算する方法と手段をSDKに伝えます。

注: 「aggregation」という用語は「aggregator」の代わりに使われています。実装者は将来SDKがカスタム集約実装を許容するようになった際のために、「aggregator」という用語を予約しておくことがRECOMMENDEDです。

Aggregationは、操作（すなわちSum、Histogram、Min、Maxのような分解可能な集約関数）と、任意の設定パラメータのオーバーライドを指定します。任意の設定パラメータのオーバーライドで上書きされない限り、その操作のデフォルトの設定パラメータ値が使われます。

注: 実装者は、Aggregationとその任意の設定パラメータの意味を表すために、自分の言語にとって最良のイディオマティックな方法を選んでもかまいません（MAY）。

例: Viewは文字列名（すなわち"ExplicitBucketHistogram"）でAggregationを指定します。

# Use Histogram with custom boundaries
meter_provider
  .add_view(
    "X",
    aggregation="ExplicitBucketHistogram",
    aggregation_params={"Boundaries": [0, 10, 100]}
    )

例: Viewはクラスや型のインスタンスでAggregationを指定します。

// Use Histogram with custom boundaries
meterProviderBuilder
  .AddView(
    instrumentName: "X",
    aggregation: new ExplicitBucketHistogramAggregation(
      boundaries: new double[] { 0.0, 10.0, 100.0 }
    )
  );

SDKは、メトリクスデータモデルのメトリックポイントをサポートするため、以下のAggregationをMUST提供するものとします。

SDKは、以下のAggregationをSHOULD提供するものとします。

Drop Aggregation

Drop Aggregationは、このAggregationに対するすべてのInstrument Measurementを無視・破棄するようSDKに伝えます。

このAggregationには設定パラメータがありません。

Default Aggregation

Default Aggregationは、Instrumentのkindを使って集約を選択し、advisoryパラメータを使って集約の設定パラメータに影響を与えるようSDKに伝えます（「選択される集約」の列に記載の通りです）。

Instrumentの種別選択される集約
CounterSum Aggregation
非同期CounterSum Aggregation
UpDownCounterSum Aggregation
非同期UpDownCounterSum Aggregation
GaugeLast Value Aggregation
非同期GaugeLast Value Aggregation
HistogramExplicit Bucket Histogram Aggregation。提供されている場合はExplicitBucketBoundaries advisoryパラメータを伴います

このAggregationには設定パラメータがありません。

Sum Aggregation

Sum Aggregationは、Sum Metric Pointのデータを収集するようSDKに伝えます。

集約の単調性はInstrumentの種別によって決まります。

Instrumentの種別SumType
CounterMonotonic
UpDownCounterNon-Monotonic
HistogramMonotonic
GaugeNon-Monotonic
非同期GaugeNon-Monotonic
非同期CounterMonotonic
非同期UpDownCounterNon-Monotonic

このAggregationには設定パラメータがありません。

このAggregationは、SDKに以下を収集するよう伝えます。

  • Measurement値の算術和。

Last Value Aggregation

Last Value Aggregationは、Gauge Metric Pointのデータを収集するようSDKに伝えます。

このAggregationには設定パラメータがありません。

このAggregationは、SDKに以下を収集するよう伝えます。

  • 最後のMeasurement。
  • 最後のMeasurementのタイムスタンプ。

Histogram Aggregations

すべてのhistogram Aggregationは、SDKに以下を収集するよう伝えます。

  • 母集団におけるMeasurement値の数。
  • 母集団におけるMeasurement値の算術和。これは、負の測定値を記録するInstrument（例えばUpDownCounterやObservableGauge）とともに使われる場合はSHOULD NOT収集されるものとします。
  • 母集団における（任意の）最小Measurement値。
  • 母集団における（任意の）最大Measurement値。
Explicit Bucket Histogram Aggregation

Explicit Bucket Histogram Aggregationは、明示的な境界値の集合をヒストグラムのバケット分けに使って、Histogram Metric Pointのデータを収集するようSDKに伝えます。

このAggregationは以下の設定パラメータに従います。

キー値デフォルト値説明
Boundariesdouble[][ 0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000 ]増加する値の配列で、明示的なバケット境界値を表します。

デフォルト値は以下のバケットを表します（Prometheusクライアント、例えばJavaやGoのデフォルトバケットに大きく影響を受けています）：
(-∞, 0], (0, 5.0], (5.0, 10.0], (10.0, 25.0], (25.0, 50.0], (50.0, 75.0], (75.0, 100.0], (100.0, 250.0], (250.0, 500.0], (500.0, 750.0], (750.0, 1000.0], (1000.0, 2500.0], (2500.0, 5000.0], (5000.0, 7500.0], (7500.0, 10000.0], (10000.0, +∞)。SDKは、境界が明示的に提供されない場合、異なるものを使う十分な理由がない限り（例えば安定版SDKリリースにおける後方互換性の理由から）、デフォルト値をSHOULD使用するものとします。
RecordMinMaxtrue, falsetrue最小値と最大値を記録するかどうか。

明示的なバケットは、その上限境界によって示されます。バケットは下限境界を含まず、上限境界を含みます（正の無限大の場合を除く）。測定値は、その値以上の境界を持つ最大番号のバケットに含まれると定義されます。

Base2 Exponential Bucket Histogram Aggregation

Base2 Exponential Histogram Aggregationは、底が2の指数関数式を使ってバケット境界を決定し、解像度を制御する整数のscaleパラメータを使うExponential Histogram Metric Pointのデータを収集するようSDKに伝えます。実装は、データに応じて必要なだけscaleを調整します。

このAggregationは以下の設定パラメータに従います。

キー値デフォルト値説明
MaxSizeinteger160特別なゼロバケットを数えない、正・負それぞれの範囲におけるバケットの最大数。
MaxScaleinteger20最大のscale係数。
RecordMinMaxtrue, falsetrue最小値と最大値を記録するかどうか。

160バケットというデフォルト値は、1msから100sまでのロングテールなレイテンシー分布を5%未満の相対誤差でカバーできる高解像度ヒストグラムのデフォルトサポートを確立するために選ばれています。160は10 * 2**Kに因数分解できるため、スケールKにおける最大のコントラストは比較的単純に導出できます。

スケール10 * 2**K バケットでの最大データコントラスト
K+25.657 (2**(10/4))
K+132 (2**(10/2))
K1024 (2**10)
K-11048576 (2**20)

以下の表は、160バケットに対する理想的なスケールが入力範囲の関数としてどのように計算されるかを示しています。

入力範囲コントラスト理想スケール底相対誤差
1ms - 4ms461.0108890.542%
1ms - 20ms2051.0218971.083%
1ms - 1s10**341.0442742.166%
1ms - 100s10**531.0905084.329%
1μs - 10s10**721.1892078.643%

相対誤差は、バケット幅の半分をバケットの中点で割ったものとして計算されることに注意してください。これはすべてのバケットで同じです。[1, base)のバケットを使うと、(bucketWidth / 2) / bucketMidpoint = ((base - 1) / 2) / ((base + 1) / 2) = (base - 1) / (base + 1)となります。

このAggregationは「理想」スケールという概念を使います。理想スケールは以下のいずれかです。

  1. MaxScale（設定パラメータを参照）。一般に、スケールが他に制約されない単一値のヒストグラムAggregationで使われます。
  2. 正または負の範囲のいずれかで入力データの全範囲を表現するために必要なバケット数が最大数を超えない、最大のスケール値。
すべての正規値の処理

実装は、IEEE浮動小数点数値の正規範囲全体（すなわち+Inf、-Inf、NaN値を除くすべての値）を受け付けることがREQUIREDです。

実装は、非正規の値（すなわち+Inf、-Inf、NaN）をsum、min、maxフィールドに組み込むべきではありません（SHOULD NOT）。これらの値は有効なバケットに対応しないためです。

実装は、非正規化数をゼロから離れる方向に最も近い正規値へ丸めてもかまいません（MAY）。

最小・最大スケールのサポート

実装は、自動スケールパラメータが超えることのない、妥当な最小・最大スケールパラメータをMUST維持するものとします。最大スケールはMaxScale設定パラメータによって定義されます。

単一の測定値に対する最大スケールの使用

ヒストグラムが正または負の範囲のいずれかに1つ以下の値しか含まない場合、実装は最大スケールをSHOULD使用するものとします。

理想スケールの維持

実装は、最大サイズ（バケットの最大数）という制約の中で可能な限り最良の解像度を維持するために、必要に応じてヒストグラムのスケールをSHOULD調整するものとします。最良の解像度（最高のスケール）は、正または負の範囲のバケット数が最大サイズの半分を超え、スケールを1増やすことがサイズの制約上不可能になる場合に達成されます。

非同期コールバック内での観測

コールバック関数は、実行中のコールバックによって行われる、あるいは生成される観測が、収集を実行している特定のMetricReaderにのみ適用されるように、そのMetricReaderのためにMUST呼び出されるものとします。

実装は、登録されたコールバックの外部での非同期Instrument APIの使用をSHOULD無視するものとします。

実装は、コールバックの無期限の実行を防ぐためにタイムアウトをSHOULD使用するものとします。

実装は、次の収集ラウンドを開始する前に、あるInstrumentに対するすべてのコールバックの実行をMUST完了するものとします。

実装は、成功したコールバックの中で観測されなかった、以前に観測された属性の集合について集約されたメトリックデータをSHOULD NOT生成するものとします。連続する収集にわたるメトリクスの永続性についての詳細はMetricReaderを参照してください。

開始タイムスタンプ

ステータス: Development

タイムシリーズの開始タイムスタンプは、このタイムシリーズに対する測定値が記録され得た最初の瞬間を最もよく表すタイムスタンプです。

delta集約の場合、開始タイムスタンプは前回の収集インターバルのタイムスタンプと等しくなるか、そのInstrumentにとってこれが最初の収集インターバルである場合はInstrumentの作成時刻と等しくなるMUSTものとします。これは、あるInstrumentに対するdelta temporality集約を持つすべてのデータポイントが同じ開始タイムスタンプをMUST共有することを意味します。

累積タイムシリーズは、すべての収集インターバルに対して一貫した開始タイムスタンプをMUST使用するものとします。同期Instrumentについて、開始タイムスタンプはそのシリーズの最初の測定値の時刻であるべきです（SHOULD）。非同期Instrumentについて、開始タイムスタンプは以下であるべきです（SHOULD）。

  • 最初のシリーズの測定値が最初の収集インターバルで発生した場合は、そのInstrumentの作成時刻。
  • そうでない場合は、最初のシリーズの測定値より前の収集インターバルのタイムスタンプ。

Cardinality limits

ステータス: Stable

SDKは、カーディナリティ制限を設定できることをSHOULDサポートするものとします。属性の一意な組み合わせの数はカーディナリティと呼ばれます。あるメトリクスについて、カーディナリティ制限は、1回の収集サイクルで収集できるメトリックポイントの数に対するハードリミットです。カーディナリティ制限の適用は、属性フィルタリングがある場合はその_後_にSHOULD行われるものとします。これにより、利用者はViewを使って不要な属性をフィルタリングし、カーディナリティ制限に達することを防げます。

設定

あるAggregationのカーディナリティ制限は、以下の3つの方法のいずれかで定義されます。

  1. Aggregationが作成される対象のInstrumentに一致する基準を持つViewが、そのストリームに対してaggregation_cardinality_limitの値を定義している場合、その値をSHOULD使用するものとします。
  2. 一致するViewがないが、MetricReaderがAggregationの作成対象のInstrumentに基づいたデフォルトのカーディナリティ制限値を定義している場合、その値をSHOULD使用するものとします。
  3. 前述のいずれの値も定義されていない場合、デフォルト値の2000をSHOULD使用するものとします。

Overflow attribute

オーバーフロー属性の集合が定義されており、これはotel.metric.overflowという単一の属性を含み、その（ブーリアン）値はtrueです。これは、制限のために独立して集約できなかったMeasurementの合成集約を報告するために使われます。

SDKは、カーディナリティ制限に達する前にオーバーフロー属性の集合を持つAggregatorをMUST作成するものとし、正しいAggregatorを作成できなかったMeasurementを集約するためにそれをMUST使用するものとします。SDKは、非オーバーフローの一意な属性集合の最大数が制限以下である場合にオーバーフローが発生しないことをMUST保証するものとします。

同期Instrumentのカーディナリティ制限

累積temporalityを持つ同期Instrumentに対するAggregatorは、オーバーフローの開始前に観測されたすべての属性集合をエクスポートし続けることをMUST行うものとします。オーバーフロー前に観測されなかった属性集合に対応するMeasurementは、（オーバーフロー属性のみによって記述される）単一のデータポイントに反映されます。

delta集約temporalityを持つ同期Instrumentに対するAggregatorは、規定されたカーディナリティ制限を維持するために、出力する属性集合の任意の部分集合を選んでもかまいません（MAY）。

集約temporalityにかかわらず、SDKは、すべてのMeasurementが、正しい属性集合に関連付けられたAggregatorか、オーバーフロー属性集合に関連付けられたAggregatorのいずれか、ちょうど1つのAggregatorに反映されることをMUST保証するものとします。

Measurementは、オーバーフロー中に二重にカウントされたり、破棄されたりすることはMUST NOTあるものとします。

非同期Instrumentのカーディナリティ制限

非同期Instrumentに対するAggregatorは、temporalityにかかわらず、カーディナリティを制限する際にコールバック内で最初に観測された属性をSHOULD優先するものとします。

Meter

異なるMeterは、Instrumentの重複登録を検知する目的において、別個の名前空間としてMUST扱われるものとします。

ステータス: Development - Meterは、Meterの作成の際に計算されたMeterConfigに従ってMUST振る舞うものとします。MeterProviderがMeterConfiguratorの更新をサポートする場合、更新時にMeterは新しいMeterConfigに従って振る舞うようMUST更新されるものとします。

MeterConfig

ステータス: Development

MeterConfigは、Meterの振る舞いのさまざまな設定可能な側面を定義します。これは以下のパラメータから構成されます。

  • enabled: Meterが有効かどうかを示すブーリアン値。

    明示的に設定されていない場合、enabledパラメータはデフォルトでtrueであるべきです（SHOULD）（すなわちMeterはデフォルトで有効です）。

    Meterが無効化されている場合、それはNo-op Meterと同等にMUST振る舞うものとします。

    enabledの値は、InstrumentがEnabledであるかどうかを解決するためにMUST使用されるものとします。詳細はInstrument enabledを参照してください。

実装が、これらのパラメータへの変更をEnabledの呼び出し元に即座に反映させることを保証する必要はありません。しかし、変更は最終的にMUST反映されるものとします。

Duplicate instrument registration

_重複したInstrumentの登録_は、同じMeterProviderの同一のMeterに対して、同じnameを持つ複数のInstrumentが作成されるが、識別に関わるフィールドが異なる場合に発生します。

これが発生した場合でも、利用者は重複したInstrumentで測定を行える必要があります。これは、たとえデータモデルにおけるセマンティックエラーを引き起こすことになっても、Meterが機能するInstrumentをMUST返すものとし、そのInstrumentはデータをエクスポートできることが期待されることを意味します。

さらに、利用者はこのエラーについて知らされる必要があります。したがって、重複したInstrumentの登録が発生し、それがViewで修正されない場合、警告がSHOULD発せられるものとします。発せられる警告は、可能であれば競合を解決する方法についての情報をSHOULD含むものとします。

  1. 潜在的な競合が複数のdescriptionプロパティに関わる場合、設定されたViewを通じてdescriptionを設定することで警告をSHOULD回避できるものとします。
  2. 潜在的な競合が、サポートされているViewセレクター（例えば名前、Instrumentの種別）によって区別できるInstrumentに関わる場合、リネームするViewのレシピが警告にSHOULD含まれるものとします。
  3. それ以外の場合（例えば複数の単位の使用）、SDKはデータをそのまま通過させ、両方のMetricオブジェクトを報告し、重複したInstrumentの登録を説明する一般的な警告をSHOULD発するものとします。

重複したInstrumentの登録の結果として同一または異なるInstrumentインスタンスが返されるかどうか、あるいはどのような条件下でそうなるかは規定されていません。Instrumentに適用される_同一_という用語は、すべての識別に関わるフィールドが等しいインスタンスを表します。Instrumentに適用される_別個_という用語は、少なくとも1つのフィールドの値が異なるインスタンスを表します。

データモデルからの推奨事項に対応するため、SDKはエクスポートパイプラインにおいて同一のInstrumentからのデータをMUST集約するものとします。

名前の競合

Instrumentのnameは、大文字小文字を区別しないと定義されています。SDKがこのnameを表現するために大文字小文字を区別するエンコーディングを使う場合、利用者が同じnameの複数の大文字小文字の形を渡すと、重複したInstrumentの登録が発生します。これが発生した場合、Meterは最初に見られたInstrument名を使ったInstrumentをMUST返すものとし、上述の通り適切なエラーをログに記録するものとします。

例えば、利用者がrequestCountという名前のInstrumentを作成し、その後同じMeterに対してRequestCountという名前のInstrumentを作成する別のリクエストを行った場合、両方の場合においてrequestCountという名前のInstrumentが利用者に返される必要があり、2番目のリクエストに対してログメッセージが発せられる必要があります。

Instrumentの名前

Meterがinstrumentを作成する際、Instrument名の構文に準拠しているかをInstrumentの名前をSHOULD検証するものとします。

Instrumentの名前がこの構文に準拠しない場合、Meterは無効な名前について利用者に通知するエラーをSHOULD発するものとします。有効なInstrumentも返されるかどうかは規定されていません。

Instrumentの単位

Meterがinstrumentを作成する際、Instrumentの単位を検証すべきではありません（SHOULD NOT）。単位が提供されない場合、あるいは単位がnullの場合、Meterはそれを空の単位文字列と同じようにMUST扱うものとします。

Instrumentの説明

Meterがinstrumentを作成する際、Instrumentの説明を検証すべきではありません（SHOULD NOT）。説明が提供されない場合、あるいは説明がnullの場合、Meterはそれを空の説明文字列と同じようにMUST扱うものとします。

Instrument advisory parameters

ステータス: Stable（特記のない限り）

Meterがinstrumentを作成する際、Instrument advisoryパラメータをSHOULD検証するものとします。advisoryパラメータが有効でない場合、Meterは利用者に通知するエラーをSHOULD発し、そのパラメータが提供されなかったかのように処理を続けるものとします。

異なるadvisoryパラメータを持つ複数の同一のInstrumentが作成された場合、Meterは最初に見られたadvisoryパラメータを使ったInstrumentをMUST返すものとし、重複したInstrumentの登録に記述された通り適切なエラーをログに記録するものとします。

Viewとadvisoryパラメータの両方がストリーム設定の同じ側面を指定している場合、Viewで定義された設定はadvisoryパラメータよりMUST優先されるものとします。

Instrument advisoryパラメータ: ExplicitBucketBoundaries

このadvisoryパラメータは、Explicit Bucket Histogram集約が使われる場合に適用されます。

一致するViewがExplicit Bucket Histogram集約を（バケット境界の有無にかかわらず）指定している場合、ExplicitBucketBoundaries advisoryパラメータは無視されます。

一致するViewがない場合、または一致するViewがデフォルトの集約を選択している場合、ExplicitBucketBoundaries advisoryパラメータがMUST使用されるものとします。どちらも提供されない場合は、デフォルトのバケット境界が適用されます。

Instrument advisoryパラメータ: Attributes

ステータス: Development

このadvisoryパラメータは、すべての集約に適用されます。

Attributes（属性キーのリスト）は、メトリックストリームを生成するために集約される測定値に対して推奨される属性キーの集合を指定します。

利用者がView経由で属性キーを提供している場合、それらのキーが優先されます。Viewが設定されていない場合、または一致するViewが属性キーを指定していない場合、advisoryパラメータが使われるべきです。どちらも提供されない場合、すべての属性が保持されなければなりません。

Instrument enabled

同期InstrumentのEnabledは、以下のいずれかの場合にfalseをMUST返すものとします。

それ以外の場合はtrueをSHOULD返すものとします。追加の最適化や機能をサポートするためにfalseを返してもかまいません（MAY）。

注: 利用者が設定を変更しない場合、デフォルトでMeterConfig.enabled=trueであり、Instrumentは一致するViewがない場合デフォルトの集約を使うため、Enabledはtrueを返します。

Instrument bind

ステータス: Development

束縛済みInstrumentは、各測定値に対して事前に束縛されたAttributesを伴って、対応する束縛されていない記録操作を呼び出すのと同一にMUST振る舞うものとします。

属性の処理とカーディナリティ制限の評価は、bind時にMUST実行されるものとします。Bindへの各呼び出しは、その時点でのカーディナリティの状態に対して独立にMUST評価されるものとします。結果として、同一の属性を持つBindへの別々の呼び出しが、各呼び出し時点でのカーディナリティの状態に基づいて異なるAggregator（例えば片方は具体的なシリーズへ、もう片方はオーバーフローシリーズへ）に解決されることがあります。解決されたAggregatorは固定でMUSTあるものとし、収集サイクルをまたいで変化してはなりません（MUST NOT）。

束縛済みInstrumentで記録された測定値は、Exemplarサンプリングの対象にMUSTなるものとします。各記録に関連付けられたContext（暗黙的か明示的かにかかわらず）は、exemplarのTraceBasedフィルタリングにMUST使用されるものとし、ExemplarReservoirのofferメソッドにMUST渡されるものとします。

SDKは、束縛済みInstrument上での属性を伴わない記録が、記録ごとのマップ検索を回避することをMUST保証するものとします。

属性の制限

ステータス: Stable

Metricsに属する属性は、現時点では属性制限の共通ルールの対象外です。属性の切り詰めや削除は、メトリックタイムシリーズの識別に影響を与える可能性があり、この論点はさらなる分析を必要とします。

Exemplar

ステータス: Stable

Exemplarは、集約されたデータに対する例示データポイントです。これらは、そうでなければ一般的な集約に対して、具体的なコンテキストを提供します。Exemplarは、集約されたメトリックデータと、測定値が記録された元のAPI呼び出しとの間の相関を可能にします。Exemplarは、Spanからも導出できるメトリクスに限らず、任意のメトリクスにおけるトレース・メトリクス間の相関のために機能します。Exemplarは、Instrumentの種別（非同期Instrumentを含む）にかかわらず、集約中に（例えばView設定によって）削除される属性も保持します。

Exemplarは、記録されたMeasurementであり、以下の情報を公開します。

  • API呼び出しによって記録されたMeasurementのvalue。
  • Measurementを記録するためにAPI呼び出しが行われたtime。
  • メトリックデータポイントにまだ含まれていない、Measurementに関連付けられたAttributesの集合。
  • 同期Instrumentについては、API呼び出し時点におけるMeasurementの、アクティブなContext内のSpanに関連付けられたTraceIdとSpanId。

例えば、利用者が属性XとYを保持するようにViewを設定しているが、以下のように測定値を記録した場合を考えます。

const span = tracer.startSpan('makeRequest');
api.context.with(api.trace.setSpan(api.context.active(), span), () => {
  // Record a measurement.
  cache_miss_counter.add(1, {"X": "x-value", "Y": "y-value", "Z": "z-value"});
  ...
  span.end();
})

その場合、OTLPにおけるexemplarの出力は以下から構成されます。

  • valueは1。
  • addメソッドが呼び出されたtime。
  • 結果として得られるメトリックポイントに保持されない{"Z": "z-value"}というAttributes。
  • makeRequestスパンのトレースID・スパンID。

一方、counterのメトリックデータポイントは属性XとYを保持します。

Metric SDKは、ExemplarFilterとExemplarReservoirのフックを通じて測定値からExemplarをサンプリングする仕組みをMUST提供するものとします。

Exemplarサンプリングはデフォルトで有効になっているべきです（SHOULD）。Exemplarサンプリングが無効な場合、SDKはexemplarサンプリングに関連するオーバーヘッドを持ってはなりません（MUST NOT）。

Metric SDKは、exemplarサンプリングがメトリック集約の設定を活用できることをMUST許容するものとします。例えば、ヒストグラムのExemplarサンプリングはバケット境界を活用できるべきです。

Metric SDKは、Exemplarサンプリングのための設定を、特に以下についてSHOULD提供するものとします。

  • ExemplarFilter: どの測定値がexemplarになれるかをフィルタリングする。
  • ExemplarReservoir: exemplarの格納とサンプリング。

ExemplarFilter

ExemplarFilterの設定は、利用者が組み込みのExemplarFilterのいずれかを選択できることをMUST許容するものとします。ExemplarFilterはどの測定値がExemplarになる_資格がある_かを決定しますが、実際に測定値がexemplarになり格納されるかどうかの最終的な決定はExemplarReservoirが行います。

ExemplarFilterは、SDKにおけるMeterProviderの設定パラメータであるべきです（SHOULD）。デフォルト値はTraceBasedであるべきです（SHOULD）。フィルタの設定は環境変数の仕様にSHOULD従うものとします。

OpenTelemetry SDKは以下のフィルタをMUSTサポートするものとします。

AlwaysOn

すべての測定値をExemplarになる資格があるとするExemplarFilterです。

AlwaysOff

いかなる測定値もExemplarになる資格がないとするExemplarFilterです。このExemplarFilterを使うことは、Exemplar機能を無効化することと同等です。

TraceBased

サンプリングされた親スパンのコンテキストで記録された測定値をExemplarになる資格があるとするExemplarFilterです。

ExemplarReservoir

ExemplarReservoirインターフェースは、レザバーに測定値を提供するメソッドと、蓄積されたExemplarを収集する別のメソッドをMUST提供するものとします。

新しいExemplarReservoirは、集約とView設定によって決定される、既知のタイムシリーズごとにMUST作成されるものとします。このデータポイントとその識別に関わる属性の集合は、関連するタイムシリーズポイントと呼ばれます。

「offer」メソッドは、以下を含む測定値をSHOULD受け付けるものとします。

  • 測定値のvalue。
  • 測定値のAttributesの完全な集合。
  • 測定値のContext。これはBaggageと現在アクティブなSpanを含みます。
  • 測定が行われたことを最もよく表すtimestamp。

「offer」メソッドは、完全なコンテキストを記録する必要なく、関連するトレースとスパンの情報を取得できるべきです（SHOULD）。つまり、現在のスパンコンテキストとbaggageは、この時点で検査できます。

「offer」メソッドは、与えられたすべての測定値を格納する必要はなく、ExemplarFilterを超えて追加でサンプリングしてもかまいません（MAY）。

「offer」メソッドは、レザバーが関連付けられているタイムシリーズから外れたフィルタリング済みのAttributesの部分集合を受け付けてもかまいません（MAY）。これはAPIに明確にドキュメント化される必要があり（MUST）、レザバーが実施する追加のサンプリングが「offer」メソッド内の測定値からすべての属性にアクセスできるように、レザバーはそのタイムシリーズポイントに関連付けられたAttributesを構築時に与えられるMUSTものとします。SDKの作者は、この選択肢が自分たちの実装に最も適しているかどうかをベンチマークすることが推奨されます。

「collect」メソッドは、蓄積されたExemplarをMUST返すものとします。Exemplarは、それが記録されるメトリックポイントのAggregationTemporalityに従うことが期待されます。つまり、あるメトリックデータポイントに対して報告されるExemplarは、そのポイントの開始・終了タイムスタンプの範囲内で発生したものであるべきです（SHOULD）。SDKは、「collect」がdelta temporality集約の収集のために内部ストレージをリセットするべきかどうか、あるいはより最適な実装を使うべきかどうかを自由に決められます。

Exemplarは、集約やView設定によって関連するタイムシリーズに対して保持されない、測定値の中で利用可能な属性をMUST保持するものとします。Exemplar上の属性と、その関連するメトリックデータポイント上で利用可能な属性を結合すると、元のサンプル測定値からの属性の完全な集合が得られるはずです。

ExemplarReservoirは、exemplarをサンプリングする際にメモリ割り当てをSHOULD避けるものとします。

Exemplarのデフォルト

SDKは、2種類の組み込みexemplarレザバーをMUST含むものとします。

  1. SimpleFixedSizeExemplarReservoir
  2. AlignedHistogramBucketExemplarReservoir

デフォルトでは、

  • 2個より多いバケットを持つexplicit bucket histogram集約は、AlignedHistogramBucketExemplarReservoirをSHOULD使用するものとします。
  • Base2 Exponential Histogram Aggregationは、集約に設定された最大バケット数と20のうち小さい方（例えばmin(20, max_buckets)）と等しいレザバーを持つSimpleFixedSizeExemplarReservoirをSHOULD使用するものとします。
  • 他のすべての集約はSimpleFixedSizeExemplarReservoirをSHOULD使用するものとします。

Exemplarのデフォルトレザバーは、マイナーバージョンの増加で変更されてもかまいません（MAY）。返されるexemplarの形や統計的性質については何の保証もありません。

SimpleFixedSizeExemplarReservoir

このレザバーは、これまでに見た測定値の数に基づいて、提供された測定値をサンプリングすべきかどうかを決定する、均一に重み付けされたサンプリングアルゴリズムをMUST使用するものとします。例えば、単純なレザバーサンプリングアルゴリズムを使えます。

if num_measurements_seen < num_buckets then
  bucket = num_measurements_seen
else
  bucket = random_integer(0, num_measurements_seen)
end
if bucket < num_buckets then
  reservoir[bucket] = measurement
end
num_measurements_seen += 1

サンプリング計算のうち状態を持つ部分は、収集サイクルごとにSHOULDリセットされるものとします。上記の例では、これはnum_measurements_seenのカウントがレザバーが収集されるたびにリセットされることを意味します。

このExemplarレザバーは、レザバーのサイズに対する設定パラメータを取ってもかまいません（MAY）。サイズの設定が提供されない場合、デフォルトサイズは、競合を減らすために、並行して実行可能なスレッド数（例えばCPU数）であってもかまいません（MAY）。それ以外の場合、デフォルトサイズ1がSHOULD使用されるものとします。

AlignedHistogramBucketExemplarReservoir

このExemplarレザバーは、Histogramの設定である設定パラメータをMUST取るものとします。この実装は、ヒストグラムバケット内に収まる測定値を最大1つMUST格納するものとし、バケットがこれまでに見た測定値の数に基づいて、提供された測定値をサンプリングすべきかどうかを決定する均一に重み付けされたサンプリングアルゴリズムをSHOULD使用するものとします。あるいは、実装は代わりにヒストグラムバケット内に収まる最後に見た測定値を保持してもかまいません（MAY）。

レザバーは、以下のような単純なアルゴリズムと同等の方法で測定値を受け付けます。

bucket = find_histogram_bucket(measurement)
num_measurements_seen_bucket = num_measurements_seen[bucket]
if random_integer(0, num_measurements_seen_bucket) == 0 then
  reservoir[bucket] = measurement
end
num_measurements_seen[bucket] += 1

def find_histogram_bucket(measurement):
  for boundary, idx in bucket_boundaries do
    if value <= boundary then
      return idx
    end
  end
  return boundaries.length

このExemplarレザバーは、レザバーが使うバケット境界に対する設定パラメータを取ってもかまいません（MAY）。レザバーのサイズは常にバケット境界の数に1を加えたものです。この設定パラメータは、Explicit Bucket Histogram Aggregationにバケット境界を指定する場合と同じ形式をSHOULD持つものとします。

カスタムExemplarReservoir

SDKは、SDKの利用者が自分自身のExemplarReservoir実装を提供できる仕組みをMUST提供するものとします。この拡張は、メトリックのViewに対して設定可能でMUSTあるものとしますが、個々のレザバーはメトリック・タイムシリーズごとにMUST依然としてインスタンス化されるものとします（ExemplarReservoir - 2番目の段落を参照）。

MetricReader

ステータス: Stable

MetricReaderは、OpenTelemetry Metrics SDKの共通の設定可能な側面を提供し、以下の能力を決定するSDK実装オブジェクトです。

SDKを設定する際にMetricReaderを構築するために、少なくとも以下がSHOULD提供されるものとします。

  • 使用するexporter。これはMetricExporterのインスタンスです。
  • デフォルトの出力aggregation（任意）。これはInstrument種別の関数です。この関数はexporterから取得されるべきです（SHOULD）。設定されていない場合、デフォルトの集約がSHOULD使用されるものとします。
  • 出力temporality（任意）。これはInstrument種別の関数です。この関数はexporterから取得されるべきです（SHOULD）。設定されていない場合、Cumulative temporalityがSHOULD使用されるものとします。
  • 使用するデフォルトの集約カーディナリティ制限（任意）。これはInstrument種別の関数です。設定されていない場合、デフォルト値の2000がSHOULD使用されるものとします。
  • ステータス: Development - MetricReader#Collectの間にメトリクスと属性に適用するMetricFilter。
  • メトリクスを収集する対象として、SDKからのメトリクスに加えて、0個以上のMetricProducer（任意）。

ステータス: Development - MetricReaderは、Produce操作を呼び出す際に、MetricFilterをSDKまたは登録されたMetricProducerにSHOULD提供するものとします。

MetricReader.Collectメソッドは、汎用のMetricExporterインスタンスが明示的に収集を開始することを許容します。これは一般にpullベースのメトリクス収集で使われます。MetricReaderの一般的な実装であるperiodic exporting MetricReaderは、通常pushベースのメトリクス収集で使われるためにSHOULD提供されるものとします。

MetricReaderは、OpenTelemetryのInstrumentからのデータポイントが、Instrument種別ごとに設定された集約temporalityで出力されることをMUST保証するものとします。Cumulative集約temporalityを持つ同期Instrumentについて、これはDeltaからCumulativeへの変換集約temporalityを意味します。Delta temporalityを持つ非同期Instrumentについて、これはCumulativeからDeltaへの変換集約temporalityを意味します。

MetricReaderは、非SDKのMetricProducerからのデータポイントが設定された集約temporalityで出力されることを保証する必要はありません。これらのデータポイントはOpenTelemetryのInstrumentを使って収集されたものではないためです。

MetricReaderのInstrument種別の関数としてのtemporalityの選択は、収集をまたいだメトリックデータポイントの永続性に影響します。Cumulative集約temporalityを持つ同期Instrumentについて、新しい測定値が記録されたかどうかにかかわらず、MetricReader.Collectは以前の収集で公開されたデータポイントをMUST受け取るものとします。Delta集約temporalityを持つ同期Instrumentについて、MetricReader.Collectは前回の収集以降に記録された測定値を持つデータポイントのみをMUST受け取るものとします。Delta集約またはCumulative集約temporalityを持つ非同期Instrumentについて、MetricReader.Collectは前回の収集以降に記録された測定値を持つデータポイントのみをMUST受け取るものとします。これらのルールは、ポイントの種別に集約temporalityフィールドを含むメトリクスだけでなく、すべてのメトリクスに適用されます。

MetricReaderのInstrument種別の関数としてのtemporalityの選択は、MetricReader.Collectによって受け取られるメトリクスデータポイントの開始タイムスタンプ（すなわちStartTimeUnixNano）にも影響します。Cumulative集約temporalityを持つInstrumentについて、MetricReader.Collectへの連続する呼び出しによって受け取られる連続するデータポイントは、同じ開始タイムスタンプをMUST繰り返すものとします（例えば(T0, T1], (T0, T2], (T0, T3]）。Delta集約temporalityを持つInstrumentについて、MetricReader.Collectへの連続する呼び出しによって受け取られる連続するデータポイントは、開始タイムスタンプをMUST進めるものとします（例えば(T0, T1], (T1, T2], (T2, T3]）。終了タイムスタンプ（すなわちTimeUnixNano）は、メトリックデータポイントが有効になった時刻、つまりMetricReader.Collectが呼び出された時刻と常に等しくなければなりません（MUST）。これらのルールは、ポイントの種別に集約temporalityフィールドを含むメトリクスだけでなく、すべてのメトリクスに適用されます。詳細はデータモデルのtemporalityを参照してください。

SDKは、同じMeterProviderに複数のMetricReaderインスタンスが登録されることをMUSTサポートするものとし、あるMetricReaderインスタンスに対するMetricReader.Collectの呼び出しは、他のMetricReaderインスタンスに副作用を及ぼすべきではありません（SHOULD NOT）。例えば、あるMetricReaderインスタンスがdeltaのtemporalityを持つメトリックデータポイントを受け取っている場合、SDKはこの特定のMetricReaderインスタンスに対してのみ時間範囲を更新することが期待されます（例えば(Tn, Tn+1]から(Tn+1, Tn+2]へ）。

SDKは、MetricReaderインスタンスを複数のMeterProviderインスタンスに登録することをMUST NOT許容するものとします。

+-----------------+            +--------------+
|                 | Metrics... |              |
| In-memory state +------------> MetricReader |
|                 |            |              |
+-----------------+            +--------------+

+-----------------+            +--------------+
|                 | Metrics... |              |
| In-memory state +------------> MetricReader |
|                 |            |              |
+-----------------+            +--------------+

SDKは、MetricReaderがMeterProvider.ForceFlushとMeterProvider.Shutdownに応答できるようにする方法をSHOULD提供するものとします。OpenTelemetry SDKの作者は、例えばOnForceFlushやOnShutdownコールバック関数として、言語にとってイディオマティックなアプローチを決めてもかまいません（MAY）。

MetricReaderの操作

Collect

SDKと登録済みのMetricProducerからメトリクスを収集します。非同期SDK Instrumentが関わっている場合、そのコールバック関数がトリガーされます。

Collectは、呼び出し元に成功、失敗、タイムアウトのいずれであったかを知らせる手段をSHOULD提供するものとします。Collect操作が一部のInstrumentで失敗またはタイムアウトした場合、SDKは正常に収集された結果と失敗理由のリストを呼び出し元に返してもかまいません（MAY）。

Collectには必須のパラメータはありませんが、OpenTelemetry SDKの作者はパラメータ（例えばコールバック、フィルタ、タイムアウト）を追加してもかまいません（MAY）。OpenTelemetry SDKの作者は返り値の型を選んでも、何も返さなくてもかまいません（MAY）。

Collectは、登録済みのMetricProducerに対してProduceをSHOULD呼び出すものとします。ProduceからのメトリックポイントのバッチがResource情報を含む場合、Collectは、代わりにMeterProviderインスタンスを構築する際に提供されたResourceでMetricProducerからのResourceを置き換えてもかまいません（MAY）。

注: MetricReader.Collectの実装はSDKによって提供されることが期待されるため、可能であれば利用者が誤ってそれを上書きしてしまうことを防ぐことがRECOMMENDEDです（例えばC++やJavaにおけるfinal、C#におけるsealed）。

Shutdown

このメソッドは、MetricReaderが必要なクリーンアップを行うための手段を提供します。

Shutdownは、MetricReaderインスタンスごとにMUST一度だけ呼び出されるものとします。Shutdownの呼び出し後、Collectへのその後の呼び出しは許可されません。SDKは、可能であればこれらの呼び出しに対して何らかの失敗をSHOULD返すものとします。

Shutdownは、呼び出し元に成功、失敗、タイムアウトのいずれであったかを知らせる手段をSHOULD提供するものとします。

Shutdownは、何らかのタイムアウト内に完了または中断すべきです（SHOULD）。Shutdownは、ブロッキングAPIとして実装されても、コールバックやイベントを通じて呼び出し元に通知する非同期APIとして実装されてもかまいません（MAY）。OpenTelemetry SDKの作者は、シャットダウンのタイムアウトを設定可能にするかどうかを決めてもかまいません（MAY）。

Periodic exporting MetricReader

これは、利用者が設定可能な時間インターバルに基づいてメトリクスを収集し、設定されたPush Metric Exporterにメトリクスを渡すMetricReaderの実装です。

設定可能なパラメータ:

  • exportIntervalMillis - 連続する2回の収集の間の時間インターバル（ミリ秒）。デフォルト値は60000（ミリ秒）です。
  • exportTimeoutMillis - エクスポートがキャンセルされるまでにどのくらいの時間実行できるか。デフォルト値は30000（ミリ秒）です。
  • ステータス: Development - maxExportBatchSize - 1回のエクスポートに提供されるバッチ内のメトリックデータポイントの最大数。

ステータス: Development - maxExportBatchSizeが設定されている場合、リーダーは、メトリックデータポイントのバッチをより小さなバッチに分割することによって、Exportに提供されるバッチがmaxExportBatchSizeを超えないことをMUST保証するものとします。最初のメトリックデータのバッチは、同じメトリクスに属するデータポイントが異なるバッチに分割されることになっても、できるだけ多くのmaxExportBatchSizeサイズの「フル」バッチにMUST分割されるものとします。リーダーは、メトリックポイントが順序通りに送信されるように、単一のCollect()からのすべてのメトリックデータポイントが、その後のCollect()からのメトリックデータポイントより前にExportに提供されることをMUST保証するものとします。リーダーは、異なるCollect()呼び出しからのメトリクスをExportに提供する同じバッチに結合してはなりません（MUST NOT）。

リーダーは、MetricExporterのExportへの呼び出しが並行して呼び出されないことを保証するためにMUST同期するものとします。

periodic exporting MetricReaderの実装の1つは、MetricReaderを継承し、要求されたexportIntervalMillisで継承されたCollect()メソッドを呼び出すバックグラウンドタスクを開始することです。リーダーのCollect()メソッドは、他の呼び出し元によっても呼び出される場合があります。例えば、

  • 利用者がpushエクスポーターと30秒のインターバルでperiodic exporting MetricReaderを設定します。
  • 最初の30秒のインターバルで、バックグラウンドタスクがCollect()を呼び出し、メトリクスをpushエクスポーターに渡します。
  • 15秒後、利用者がこのリーダーだけについてメトリクスをフラッシュすることを決めます。彼らはCollect()を呼び出し、メトリクスをpushエクスポーターに渡します。
  • さらに15秒後（2回目の30秒インターバルの終わり）、バックグラウンドタスクがCollect()を呼び出し、メトリクスをpushエクスポーターに渡します。

ForceFlush

このメソッドは、periodic exporting MetricReaderが、メトリクスの収集と送信のためにできる限りのことを行える手段を提供します。

ForceFlushは、メトリクスを収集し、必要であればバッチに分割し、各バッチに対してExport(batch)を呼び出し、設定されたPush Metric Exporterに対してForceFlush()をSHOULD呼び出すものとします。タイムアウトが既に切れている場合、ForceFlushはExport(batch)の呼び出しをスキップしてもかまいません（MAY）が、タイムアウトが過ぎていても設定されたPush Metric Exporterに対するForceFlush()の呼び出しはSHOULD行うものとします。

ForceFlushは、呼び出し元に成功、失敗、タイムアウトのいずれであったかを知らせる手段をSHOULD提供するものとします。ForceFlushは、エラー状態がある場合は何らかのERRORステータスを返すべきであり（SHOULD）、エラー状態がない場合は何らかのNO ERRORステータスを返すべきです（SHOULD）。言語実装は、ERRORとNO ERRORをどのようにモデル化するかを決めてもかまいません（MAY）。

ForceFlushは、何らかのタイムアウト内に完了または中断すべきです（SHOULD）。ForceFlushは、ブロッキングAPIとして実装されても、コールバックやイベントを通じて呼び出し元に通知する非同期APIとして実装されてもかまいません（MAY）。

MetricExporter

ステータス: Stable

MetricExporterは、プロトコル固有のエクスポーターがOpenTelemetry SDKに組み込まれ、テレメトリーデータの送信をサポートできるようにするために実装しなければならないインターフェースをMUST定義するものとします。

Metric Exporterには常に_関連付けられた_MetricReaderがあります。OpenTelemetry Metric SDKで使われるaggregationとtemporalityのプロパティは、関連付けられたMetricReaderを通じてMetric Exporterを登録する際に決定されます。OpenTelemetryの言語実装は、Exporterが使うMetricReaderを自動的に設定することをサポートしてもかまいません（MAY）。

このインターフェースの目標は、プロトコル依存のテレメトリーエクスポーターの実装負荷を最小化することです。プロトコルエクスポーターは、主に単純なテレメトリーデータのエンコーダーおよび送信者であることが期待されます。

Metric Exporterは集約されたメトリクスデータにアクセスできます。Metric Exporterは、この状況がMetricReaderの設定変更によって修正できるため、サポートされていないAggregationやAggregation Temporalityを持つMetricReaderが出力するデータについてエラー状態をSHOULD報告するものとします。

Push Metric ExporterやPull Metric Exporter、あるいはそれらの混合が、あるMeterProviderに同時に複数設定され、各エクスポーターに対して1つのMetricReaderを使うことがあります。異なるエクスポーターは異なるスケジュールで動作できます。例えば、

  • Exporter Aは、1分ごとにデータを送信するpushエクスポーターです。
  • Exporter Bは、5秒ごとにデータを送信するpushエクスポーターです。
  • Exporter Cは、HTTP経由のスクレイパーに反応するpullエクスポーターです。
  • Exporter Dは、名前付きパイプ経由の別のスクレイパーに反応するpullエクスポーターです。

Push Metric Exporter

Push Metric Exporterは、対となるMetricReaderから受け取ったメトリックデータを送信します。例をいくつか示します。

  • 利用者が設定したスケジュールに基づいてデータを送信する（例えば1分ごと）。これは、エクスポーターをperiodic exporting MetricReaderと組み合わせることでMAY実現できます。
  • 重大なエラーがあるときにデータを送信する。

以下の図は、Push Metric ExporterのSDK内の他のコンポーネントとの関係を示しています。

+-----------------+            +---------------------------------+
|                 | Metrics... |                                 |
| In-memory state +------------> Periodic exporting MetricReader |
|                 |            |                                 |
+-----------------+            |    +-----------------------+    |
                               |    |                       |    |
                               |    | MetricExporter (push) +-------> Another process
                               |    |                       |    |
                               |    +-----------------------+    |
                               |                                 |
                               +---------------------------------+

インターフェース定義

Push Metric Exporterは以下の関数をMUSTサポートするものとします。

Export(batch)

メトリックポイントのバッチをエクスポートします。この関数を実装するプロトコルエクスポーターは、一般に、データを宛先へシリアライズして送信することが期待されます。

SDKは、各Metric Pointに関連付けられたMeter情報（例えば名前、バージョンなど）を取得する方法をエクスポーターにMUST提供するものとします。

Exportは、同じエクスポーターインスタンスに対する他のExport呼び出しと同時に呼び出されてはなりません。

Exportは無期限にブロックしてはならず（MUST NOT）、タイムアウトしてエラー結果（Failure）を返すまでの妥当な上限がMUSTなければならないものとします。

エクスポーターに必要なリトライロジックは、エクスポーターの責務です。デフォルトのSDKはリトライロジックを実装すべきではありません（SHOULD NOT）。必要なロジックは、メトリクスが送信される特定のプロトコルとバックエンドに大きく依存する可能性が高いためです。

パラメータ:

batch - メトリックポイントのバッチ。バッチの正確なデータ型は言語固有であり、通常は何らかのリストです。Metric Pointの正確な型は言語固有であり、通常は高いパフォーマンスのために最適化されています。例をいくつか示します。

       +--------+ +--------+     +--------+
Batch: | Metric | | Metric | ... | Metric |
       +---+----+ +--------+     +--------+
           |
           +--> name, unit, description, meter information, ...
           |
           |                  +-------------+ +-------------+     +-------------+
           +--> MetricPoints: | MetricPoint | | MetricPoint | ... | MetricPoint |
                              +-----+-------+ +-------------+     +-------------+
                                    |
                                    +--> timestamps, attributes, value (or buckets), exemplars, ...

詳細については、Metrics Data Model仕様のメトリックポイントの節を参照してください。

注: 実装者は、protoファイルから生成されるデータ型を直接使うのではなく、それを_基にした_Metricデータ型をデータモデルを基に設計することが強く推奨されます（protoファイルから生成される型は後方互換性が保証されていないためです）。

返り値: ExportResult

ExportResultは以下のいずれかです。

  • Success - バッチが正常にエクスポートされました。プロトコルエクスポーターにとって、これは通常、データが送信され宛先サーバーに配信されたことを意味します。
  • Failure - エクスポートに失敗しました。バッチは破棄されなければなりません。例えば、バッチに不正なデータが含まれていてシリアライズできない場合に発生します。

注: この結果は、言語実装にとってイディオマティックであれば、非同期の仕組みやコールバックを介して返されてもかまいません。

ForceFlush

これは、ForceFlushの呼び出しより前にエクスポーターが受け取ったすべてのMetricsのエクスポートが、可能な限り早く（できればこのメソッドから戻る前に）完了すべきであることを示すヒントです（SHOULD）。

ForceFlushは、呼び出し元に成功、失敗、タイムアウトのいずれであったかを知らせる手段をSHOULD提供するものとします。

ForceFlushは、絶対に必要な場合にのみ呼び出されるべきです（SHOULD）。例えば、一部のFaaSプロバイダーが、呼び出し後にエクスポーターが完了したメトリクスをエクスポートする前にプロセスを一時停止する可能性がある場合などです。

ForceFlushは、何らかのタイムアウト内に完了または中断すべきです（SHOULD）。ForceFlushは、ブロッキングAPIとして実装されても、コールバックやイベントを通じて呼び出し元に通知する非同期APIとして実装されてもかまいません。OpenTelemetry SDKの作者は、フラッシュのタイムアウトを設定可能にするかどうかを決めてもかまいません（MAY）。

Shutdown

エクスポーターをシャットダウンします。SDKがシャットダウンされるときに呼び出されます。これは、エクスポーターが必要なクリーンアップを行う機会です。

Shutdownは、MetricExporterインスタンスごとにSHOULD一度だけ呼び出されるものとします。Shutdownの呼び出し後、Exportへのその後の呼び出しは許可されず、Failure結果を返すべきです（SHOULD）。

Shutdownは無期限にブロックすべきではありません（SHOULD NOT）（例えばデータをフラッシュしようとして宛先が利用できない場合）。OpenTelemetry SDKの作者は、シャットダウンのタイムアウトを設定可能にするかどうかを決めてもかまいません（MAY）。

Pull Metric Exporter

Pull Metric Exporterは、メトリクスのスクレイパーに反応し、受動的にデータを報告します。このパターンはPrometheusによって広く採用されています。

自分自身のスケジュールでデータを送信できるPush Metric Exporterとは異なり、pullエクスポーターはスクレイパーから要求されたときにのみデータを送信でき、ForceFlushは意味を持ちません。

実装者は、自分の言語にとって最良のイディオマティックな設計を選んでもかまいません（MAY）。例えば、一貫性のためにPush Metric Exporterインターフェースの設計を一般化してそれを使うことも、pullエクスポーターをMetricReaderとしてモデル化することも、まったく異なるpullエクスポーターインターフェースを設計することもできます。pullエクスポーターがMetricReaderとしてモデル化される場合、実装者は命名の混乱を避けるためにMetricExporterインターフェースをPushMetricExporterと名付けてもかまいません（MAY）。

以下の図は、Pull Metric ExporterがSDK内の他のコンポーネントとどのようにやり取りするようモデル化できるかの例を示しています。

  • pullエクスポーターをMetricReaderとしてモデル化する

    +-----------------+            +-----------------------------+
|                 | Metrics... |                             |
| In-memory state +------------> PrometheusExporter (pull)   +---> Another process (scraper)
|                 |            | (modeled as a MetricReader) |
+-----------------+            |                             |
                               +-----------------------------+

  • pushとpull両方のエクスポーターに同じMetricExporter設計を使う

    +-----------------+            +-----------------------------+
|                 | Metrics... |                             |
| In-memory state +------------> Exporting MetricReader      |
|                 |            |                             |
+-----------------+            |  +-----------------------+  |
                               |  |                       |  |
                               |  | MetricExporter (pull) +------> Another process (scraper)
                               |  |                       |  |
                               |  +-----------------------+  |
                               |                             |
                               +-----------------------------+

MetricProducer

ステータス: Stable（特記のない限り）

MetricProducerは、サードパーティのメトリクスソースへのブリッジが実装しなければならないインターフェースを定義し、それによってOpenTelemetryのMetricReaderに集約されたメトリックデータのソースとして組み込めるようにします。SDKのインメモリ状態は、便宜上MetricProducerインターフェースを実装してもかまいません（MAY）。

MetricProducerの実装は、生成されるメトリクスのAggregationTemporalityに対する設定をSHOULD受け付けるものとします。SDKの作者は、deltaとcumulativeのtemporality間の変換を容易にするユーティリティライブラリを提供してもかまいません（MAY）。

+-----------------+            +--------------+
|                 | Metrics... |              |
| In-memory state +------------> MetricReader |
|                 |            |              |
+-----------------+            |              |
                               |              |
+-----------------+            |              |
|                 | Metrics... |              |
| MetricProducer  +------------>              |
|                 |            |              |
+-----------------+            +--------------+

新しいOpenTelemetryのインテグレーションが追加される場合、APIが優先されるインテグレーションポイントです。MetricProducerは、事前処理済みのデータをブリッジするインテグレーションのためだけに意図されています。

インターフェース定義

MetricProducerは以下の関数をMUSTサポートするものとします。

Produce batch

Produceは、MetricProducerから呼び出し元にメトリクスを提供します。Produceは、任意のmetricFilterパラメータでフィルタリングされたメトリックポイントのバッチをMUST返すものとします。実装は、可能な限り多くの性能向上（メモリ割り当て、内部的なメトリクス取得など）を得るために、できるだけ早くフィルタをSHOULD使用するものとします。

メトリックポイントのバッチがリソース情報を含む場合、ProduceはパラメータとしてリソースをSHOULD要求するものとします。Produceには他に必須のパラメータはありませんが、OpenTelemetry SDKの作者は必須または任意のパラメータ（例えばタイムアウト）を追加してもかまいません（MAY）。

Produceは、呼び出し元に成功、失敗、タイムアウトのいずれであったかを知らせる手段をSHOULD提供するものとします。Produce操作が失敗した場合、MetricProducerは正常に収集された結果と失敗理由のリストを返してもかまいません（MAY）。

メトリックポイントのバッチがInstrumentationScope情報を含められる場合、ProduceはMetricProducerを識別する単一のInstrumentationScopeをSHOULD含むものとします。

パラメータ:

ステータス: Development metricFilter: 任意のMetricFilter。

MetricFilter

ステータス: Development

MetricFilterは、MetricReaderに登録されたMetricProducer、あるいはSDKのMetricProducerが、そのProduce操作内で集約されたデータポイント（メトリックポイント）をフィルタリングできるようにするインターフェースを定義します。フィルタリングは、パフォーマンス上の理由からMetricProducerで行われます。

MetricFilterは、そのTestMetric操作によって、メトリックストリーム全体をフィルタリングすることを許容します（そのすべての属性集合を破棄・許可する）。この操作はメトリックストリーム情報（スコープ、名前、種別、単位）を受け取り、Accept、Drop、Accept_Partialのいずれかの列挙値を返します。後者が返された場合、TestAttributes操作がそのメトリックストリームの属性集合ごとに呼び出され、その（メトリックストリーム、属性）の組に対するデータポイントがMetricProducerのProduce操作の結果に許可されるかどうかを決定する列挙値を返します。

インターフェース定義

MetricFilterは以下の関数をMUSTサポートするものとします。

TestMetric

この操作は、各MetricProducerのProduce操作において、メトリックストリームごとに1回呼び出されます。

パラメータ:

  • instrumentationScope: メトリックストリームのinstrumentation scope
  • name: メトリックストリームの名前
  • kind: メトリックストリームの種別
  • unit: メトリックストリームの単位

返り値: MetricFilterResult

MetricFilterResultは以下のいずれかです。

  • Accept - 与えられたメトリックストリームのすべての属性が許可されます（フィルタリングされません）。これは、属性集合ごとにTestAttributes操作を呼び出す必要がないため「短絡」を提供します。
  • Drop - 与えられたメトリックストリームのすべての属性が許可されません（フィルタリングされ破棄されます）。これは、属性集合ごとにTestAttributes操作を呼び出す必要がなく、それらのデータポイントを（同期・非同期にかかわらず）収集する必要もないため「短絡」を提供します。例えば、このInstrumentのコールバックは呼び出される必要がありません。
  • Accept_Partial - 一部の属性は許可され一部は許可されないため、そのInstrumentの属性集合ごとにTestAttributes操作を呼び出す必要があります。

TestAttributes

与えられたメトリックストリームと属性集合について、それが許可されるかフィルタリングされるかを決定する操作です。

この操作は、TestMetric操作が与えられたメトリックストリームの引数（instrumentationScope、name、kind、unit）に対してAccept_Partialを返した場合にのみ呼び出されるべきです（SHOULD）。

パラメータ:

  • instrumentationScope: メトリックストリームのinstrumentation scope
  • name: メトリックストリームの名前
  • kind: メトリックストリームの種別
  • unit: メトリックストリームの単位
  • attributes: 属性

返り値: AttributesFilterResult

AttributesFilterResultは以下のいずれかです。

  • Accept - この与えられたattributesは許可されます（フィルタリングされません）。
  • Drop - この与えられたattributesは許可されません（フィルタリングされ破棄されます）。

デフォルトと設定

SDKは、SDK環境変数仕様に従って設定をMUST提供するものとします。

数値限界の処理

SDKは、OpenTelemetryにおけるエラー処理に従って、数値限界を適切な方法でMUST処理するものとします。

SDKがInstrumentから浮動小数点数値を受け取る場合、可能なすべての値をMUST処理するものとします。例えば、言語のランタイムがIEEE 754をサポートしている場合、SDKはNaNと無限大を処理する必要があります。

SDKが入力の限界をどのように処理する_か_は規定されていません。SDKの作者は、各値がAPIから来るたびにチェックを行うのではなく、より良いパフォーマンスのために言語ランタイムの振る舞いを活用・追従してもかまいません（MAY）。

SDKが出力の限界（例えば整数オーバーフロー）をどのように処理する_か_は規定されていません。SDKの作者は、エラーや例外が処理されている限り、言語ランタイムの振る舞いに依存してもかまいません（MAY）。

互換性の要件

ステータス: Stable

すべてのメトリクスコンポーネントは、破壊的変更を導入せずに既存のコンポーネントへ新しいメソッドを追加できることをSHOULD許容するものとします。

すべてのメトリクスSDKのメソッドは、可能な場合、破壊的変更を導入せずに既存のメソッドへ任意のパラメータを追加できることをSHOULD許容するものとします。

並行性の要件

ステータス: Stable

並行実行をサポートする言語について、Metrics SDKは特定の保証と安全性を提供します。

MeterProvider - Meterの作成、ForceFlush、Shutdownは、並行して呼び出されてもMUST安全であるものとします。

ExemplarReservoir - すべてのメソッドは、並行して呼び出されてもMUST安全であるものとします。

MetricReader - Collect、ForceFlush（periodic exporting MetricReaderの場合）、Shutdownは、並行して呼び出されてもMUST安全であるものとします。

MetricExporter - ForceFlushとShutdownは、並行して呼び出されてもMUST安全であるものとします。

セルフオブザーバビリティ

ステータス: Development

Metrics SDKは、SDKのセルフオブザーバビリティをSHOULDサポートするものとします。

参考文献