OTEP-0083: InstrumentationLibrary

InstrumentationLibrary という概念を、データモデルにおいて名前付きの Tracer|Meter を表す第一級の概念としてOpenTelemetryに導入します。

動機

この変更の主な動機は、アプリケーション（Resource）内部のさまざまな計装ライブラリから届くテレメトリーをより適切にモデル化することです。この変更はOpenTelemetryのプロトコルとエクスポーターのみに影響し、APIの変更は必要ありません。

この提案は、InstrumentationLibrary をOpenTelemetryにおける第一級の概念にすることであり、そのスコープは named Tracer|Meter によって定義されます。これは、1つの named Tracer|Meter によって生成されるすべてのテレメトリーを記述します。

説明

                                Application
+--------------------------------------------------------------------------+
|                         TracerProvider(Resource)                         |
|                         MeterProvider(Resource)                          |
|                                                                          |
|      Instrumentation Library 1           Instrumentation Library 2       |
|  +--------------------------------+  +--------------------------------+  |
|  | Tracer(InstrumentationLibrary) |  | Tracer(InstrumentationLibrary) |  |
|  | Meter(InstrumentationLibrary)  |  | Meter(InstrumentationLibrary)  |  |
|  +--------------------------------+  +--------------------------------+  |
|                                                                          |
|      Instrumentation Library 3           Instrumentation Library 4       |
|  +--------------------------------+  +--------------------------------+  |
|  | Tracer(InstrumentationLibrary) |  | Tracer(InstrumentationLibrary) |  |
|  | Meter(InstrumentationLibrary)  |  | Meter(InstrumentationLibrary)  |  |
|  +--------------------------------+  +--------------------------------+  |
|                                                                          |
+--------------------------------------------------------------------------+

すべてのアプリケーションは、そのアプリケーションを記述する Resource に紐づけられた1つの TracerProvider と1つの MeterProvider を持ちます。

すべての計装ライブラリは、その計装ライブラリを記述する InstrumentationLibrary に紐づけられた1つの Tracer と1つの Meter を持ちます。

Spring Boot（あるいは古いJavaアプリケーションサーバー）のようなマルチアプリケーションのデプロイメントでは、それぞれのアプリケーションが自身の TracerProvider と MeterProvider のインスタンスを持ちます。

内部詳細

この提案はOpenTelemetryのプロトコルにのみ影響し、テレメトリーデータを構造化された形式で表現する方法を提案します。例として、metricsのprotobuf定義を以下に示します。

// Resource information.
message Resource {
  // Set of labels that describe the resource.
  repeated opentelemetry.proto.common.v1.AttributeKeyValue attributes = 1;
}

// InstrumentationLibrary is a message representing the instrumentation library
// informations such as the fully qualified name and version.
message InstrumentationLibrary {
  string name = 1;
  string version = 2;
  // Can be extended with attributes.
}

// A collection of InstrumentationLibraryMetrics from a Resource.
message ResourceMetrics {
  // The Resource for the metrics in this message.
  // If this field is not set then no Resource is known.
  Resource resource = 1;

  // A list of metrics that originate from a Resource.
  repeated InstrumentationLibraryMetrics instrumentation_library_metrics = 2;
}

// A collection of Metrics from a InstrumentationLibrary.
message InstrumentationLibraryMetrics {
  // The Instrumentation library information for the metrics in this message.
  // If this field is not set then no InstrumentationLibrary is known.
  InstrumentationLibrary instrumentation_library = 1;

  // A list of metrics that originate from a Instrumentation library.
  repeated Metric metrics = 2;
}

トレードオフと緩和策

OpenTelemetryのプロトコルとエクスポーターのフレームワークに新しい概念を追加することはやり過ぎに思えるかもしれませんが、この概念はAPIにすでに存在する概念に容易にマッピングでき、ユーザーへの説明も簡単です。

先行技術と代替技術

代替のアプローチが、protoのPRコメントで提案されました。これは、named Tracer|Meter を含む複数のレベルで Resource を包含することを提案するものでした。

未解決の問題

現時点で、InstrumentationLibraryが名前とバージョン以上のものをサポートすべきかどうか。

将来の可能性

将来的には、InstrumentationLibrary を拡張して、計装ライブラリの特定のインスタンスに適用される複数のプロパティ（属性）をサポートできるようにすることが考えられます。また、計装される側のライブラリに関する情報を追加することも考えられますが、その場合はグループ化について追加の検討が必要になります。たとえば、計装する側のライブラリだけでグループ化するのではなく、（計装する側のライブラリ、計装される側のライブラリ）というペアでグループ化するといった検討です。