Yoshi Yamaguchi

Instrumentation Scope

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

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

ステータス: Stable

発行されるテレメトリーを関連付けられる、論理的なソフトウェアの単位です。妥当なInstrumentation Scopeが何を指すかを決めるのは、通常開発者の選択に委ねられます。最も一般的な方法は、Instrumentation Libraryの名前とバージョンを使い、追加の識別情報をスコープの属性の一部とすることです。名前、バージョン、追加の属性を得るために、モジュール、パッケージ、クラス、プラグインなど他のソフトウェアコンポーネントを使うこともできます。

Instrumentation Scopeは、(name, version, schema_url, attributes)というタプルによって定義されます。ここでversion、schema_url、attributesは任意です。このタプルは、テレメトリーを発行する論理的なソフトウェアの単位を一意に識別すべきです（SHOULD）。一意性を確保する典型的な方法は、発行を行うソフトウェア単位の完全修飾名（例えば完全修飾ライブラリ名や完全修飾クラス名）を使うことです。

Instrumentation Scopeは、Tracer、Meter、またはLoggerを取得するために使われます。

Instrumentation Scopeの名前は、InstrumentationScopeの名前を識別するために指定すべきです（SHOULD）。

Instrumentation Scopeの任意のSchema URLは、その計装が発行するテレメトリーが準拠するTelemetry Schemaを識別すべきです（SHOULD）。

Instrumentation Scopeの任意の属性は、スコープに関する追加の情報を提供します。例えば、Instrumentation Libraryを指定するスコープでは、そのライブラリのソースコードが格納されているリポジトリのURLを示すために追加の属性が記録されることがあります。

Examples

以下は、想定される使用場面を網羅的に挙げたものではありませんが、その例です。

  • 汎用的なInstrumentation Libraryが、その名前・バージョンと、追加のライブラリ情報を含む属性を持つ場合。
  • データベースアクセスが、それ自身の名前とバージョン（例えばdb.system.name）で計装される場合。これは、JDBCやSqlAlchemyのような、異なる基盤データベースへのアクセスを抽象化するAPIによって活用できます。
  • 情報を消費または生成するクライアントが、その名前、バージョン、idを使ってInstrumentationScopeを設定する場合。
  • アプリケーション内部のコンポーネントが自身のテレメトリーを発行し、同じ種類の複数のインスタンスが存在する場合に自身を区別するためにInstrumentationScopeの属性に依存する場合。