OTEP-0005: グローバルなSDKの初期化 #

ステータス: 提案中

OpenTelemetry APIと実装の起動時の動作を指定します。

動機 #

OpenTelemetryは、APIとそれを実装するSDKを分離して設計されており、アプリケーションはランタイムに互換性のあるSDKを設定しバインドできます。 OpenTelemetryは、グローバルインスタンスの使用により、サードパーティーライブラリの「ゼロタッチ」計装をサポートするように設計されています。

多くのプログラミング環境では、コードのライブラリが自動で初期化され、静的なプログラム状態を初期化している間などに、メインプログラムと同時に動作を開始することが可能です。これには次のような相反する要件があります。 (1) APIは設定可能なSDKをサポートすること。(2)サードパーティーのライブラリは設定なしでOpenTelemetryを使用できます。

解説 #

この状況に対処するには、いくつかの受け入れ可能な方法があります。各アプローチの実現可能性は言語によって異なります。実装は、以下の戦略のいずれかを選択しなければなりません。

サービスプロバイダー機構 #

言語がSDKコンポーネントを注入する一般的に認められた方法を提供する場合、それが優先されるべきです。 Java SPIは、最初に使用される前にグローバルSDKをロードして設定することをサポートしています。この特性により、サービスプロバイダー機構の場合は、他にほとんど指定するものがありません。

明示的なイニシャライザ #

APIが最初に使用される前にSDKがインストールされ設定されていることを保証できない場合、Ruby issue 19で述べられているように、SDKのロードは「適切なタイミングで」ユーザーに引き渡されます。この場合、次に説明するように、多くの要件を指定する必要があります。

要件: 明示的なイニシャライザ #

OpenTelemetryは、デフォルトの実装がノンオペレーション（すなわち、“no-op”）であることを明記しており、APIメソッド呼び出しの結果、計装のオーバーヘッドが事実上ゼロになることを要求しています。私たちは、サードパーティーのライブラリが、インストールされる前にグローバルSDKを使用することを期待しています。

明示的なイニシャライザーメソッドは、独立した Tracer オブジェクトと Meter オブジェクトを取る必要があります（例: opentelemetry.Init(Tracer, Meter)）。 SDKのインストールは1回までとします。最初にSDKをインストールした後、明示的なイニシャライザを呼び出すと、ログコンソールに警告が表示されます。

一般的な言語では、グローバルSDKインスタンス（すなわち、TracerとMeter）の使用は、SDKがインストールされると、以下の規定で「動作を開始」しなければなりません。

Tracer #

起動時にスパンが喪失するかもしれません。

SDKがインストールされる前に開始されたスパンは回復されず、No-opスパンとして継続されます。

Meter #

起動時にメトリクスが喪失するかもしれません。

SDK がインストールされる前に初期化されたメトリクスのサブ計測オブジェクト (つまり、事前定義されたラベルを持つメトリクス) は、インストール後にグローバルSDKにリダイレクトされます。

具象型 #

キー、タグ、属性、ラベル、リソース、スパンコンテキスト、分散コンテキストは、純粋なAPIオブジェクトとして指定されるため、インストールされているSDKに依存しません。

トレードオフと緩和策 #

テストのサポート #

テストは、グローバルSDKに依存することなく実行されるべきです。

同期 #

グローバルな Tracer オブジェクトと Meter オブジェクトは、SDK がインストールされると動作を開始する必要があるため、起動時に暗黙の同期オーバーヘッドが発生します。このオーバーヘッドはSDKがインストールされると計装を完全に無効にするために、明示的に No-op SDK をインストールすることをおすすめします。これは、このアプローチが、OpenTelemetry ライブラリを未初期化のままにするよりもオーバーヘッドが低くなるためです。

先行技術と代替技術 #

「一般的に受け入れられている」とは言えない例として、Go issue 52 を参照してください。この例では、最初の使用前に設定可能なSDKをロードするために、Go plugin パッケージを使用しています。

未解決の問題 #

明示的なグローバルイニシャライザーには、他にどのようなオプションを渡すべきでしょうか。

「SDKがインストールされているか、それは no-op か」の公開テストは存在するでしょうか。