Baggage API

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

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

ステータス: Stable

Overview

Baggageは、分散リクエストやワークフローの実行に文脈的に関連付けられたアプリケーション定義のプロパティの集合です（W3C Baggage Specificationも参照してください）。バゲージは、他の用途に加えて、テレメトリーへの注釈付けや、メトリクス・トレース・ログへの文脈情報の付加に使えます。

OpenTelemetryにおいてBaggageは、ユーザー定義のプロパティを記述する名前・値の組の集合として表現されます。Baggage内の各名前は、_厳密に1つの値_にMUST関連付けられるものとします。これは、同じ名前に対する重複するエントリーを許容するW3C Baggage Specification, § 3.2.1.1よりも制限が強くなっています。

バゲージの名前は、任意の有効な空でないUTF-8文字列です。言語APIは、バゲージの名前として使える文字列をSHOULD NOT制限するものとします。しかし、バゲージのエントリーをコンポーネントの境界を越えて送信するために使われる特定のPropagatorは、バゲージの名前に独自の制約を課すことがあります。例えばW3C Baggageの仕様は、バゲージのキーをRFC7230, Section 3.2.6のtokenの定義を満たす文字列に制限しています。最大限の互換性のため、バゲージの名前には英数字を使うことが強く推奨されます。

バゲージの値は、任意の有効なUTF-8文字列です。言語APIは、Setにおいてバゲージの値として任意の有効なUTF-8文字列をMUST受け付けるものとし、Getから同じ値をMUST返すものとします。

言語APIは、バゲージの名前と値の両方を大文字・小文字を区別するものとしてMUST扱うものとします。W3C Baggage Rationaleも参照してください。

例:

baggage.Set('a', 'B% 💼');
baggage.Set('A', 'c');
baggage.Get('a'); // "B% 💼" を返す
baggage.Get('A'); // "c" を返す

Baggage APIは以下から構成されます。

論理的なコンテナとしてのBaggage
Context内のBaggageと相互作用する関数群

ここで説明する関数は、Baggageの内容全体を表す構造体・オブジェクトを持つことによってBaggageと相互作用するための1つのアプローチです。言語の慣用表現によっては、言語APIはContextを直接介してバゲージと相互作用することでこれらの関数をMAY実装してもよいものとします。

Baggage APIは、SDKがインストールされていない状態でも完全に機能しなければなりません（MUST）。これは、透過的なプロセス間のバゲージ伝搬を可能にするために必要です。Baggage propagatorがAPIにインストールされている場合、SDKがインストールされているかどうかに関わらず動作します。

Baggageコンテナは不変でなければならず（MUST）、それを含むContextもまた不変であり続けます。

Operations

Get Value

以前のイベントによって設定された名前・値の組の値にアクセスするために、Baggage APIは、名前を入力として受け取り、指定された名前に関連付けられた値を返す関数、あるいは指定された名前が存在しない場合はnullを返す関数をMUST提供するものとします。

REQUIREDパラメータ:

Name 値を返す対象の名前。

Get All Values

Baggage内の名前・値の組を返します。名前・値の組の順序はMUST NOT重要であるものとします。言語の特性に応じて、返される値は不変のコレクションでも、Baggage内の名前・値の組の不変のコレクションに対するイテレーターでも構いません。

Set Value

名前・値の組の値を記録するために、Baggage APIは、名前と値を入力として受け取る関数をMUST提供するものとします。新しい値を含む新しいBaggageを返します。言語の慣用表現によっては、言語APIはBuilderパターンを使い、BaggageからBuilderを構築する方法を公開することでこれらの関数をMAY実装してもよいものとします。

REQUIREDパラメータ:

Name 値を設定する対象の名前。文字列型。

Value 設定する値。文字列型。

OPTIONALパラメータ:

Metadata 名前・値の組に関連付けられる任意のメタデータ。これは意味を持たない文字列の不透明なラッパーであるべきです。将来の機能のために不透明なままにされています。

Remove Value

名前・値の組を削除するために、Baggage APIは、名前を入力として受け取る関数をMUST提供するものとします。選択された名前を含まない新しいBaggageを返します。言語の慣用表現によっては、言語APIはBuilderパターンを使い、BaggageからBuilderを構築する方法を公開することでこれらの関数をMAY実装してもよいものとします。

REQUIREDパラメータ:

Name 削除する対象の名前。

Context Interaction

本節は、Contextと相互作用するBaggage API内のすべての操作を定義します。

このAPIの実装がContextを直接操作しない場合、Contextインスタンスと相互作用するために以下の機能をMUST提供するものとします。

ContextインスタンスからBaggageを抽出する
ContextインスタンスにBaggageを挿入する

上記の機能が必要なのは、APIのユーザーがBaggage APIの実装が使うContext KeyへのアクセスをSHOULD NOT持つべきであるためです。

言語が暗黙的に伝搬されるContextをサポートしている場合（こちらを参照）、APIは以下の機能もSHOULD提供するものとします。

暗黙のコンテキストから現在アクティブなBaggageを取得する。これは、暗黙のコンテキストを取得し、そのコンテキストからBaggageを抽出することと同等です。
現在アクティブなBaggageを暗黙のコンテキストに設定する。これは、暗黙のコンテキストを取得し、そのコンテキストにBaggageを挿入することと同等です。

上記のすべての機能は、コンテキストAPIのみを操作するものであり、baggageモジュールの静的メソッド、baggageモジュール内のクラス（BaggageUtilitiesという名前でMAY構いません）の静的メソッド、またはBaggageクラスのメソッドとしてMAY公開されても構いません。この機能は、可能な場合はAPI内で完全に実装されるべきです（SHOULD）。

Clear Baggage in the Context

信頼されていないプロセスにいかなるバゲージの名前・値の組も送信しないようにするため、Baggage APIは、コンテキストからすべてのバゲージのエントリーを削除する方法をMUST提供するものとします。

この機能は、ユーザーが空のBaggageオブジェクト・構造体をコンテキストに設定できるようにすることで実装しても、Contextを入力として受け取り、Baggageが関連付けられていない新しいContextを返すAPIを提供することで実装しても構いません。

Propagation

Baggageは、プロセス境界を越えて、あるいは任意の境界（プロセス、$OTHER_BOUNDARY1、$OTHER_BOUNDARY2など）を越えて、様々な理由でMAY伝搬されても構いません。

APIレイヤーまたは拡張パッケージは、以下のPropagatorをMUST含むものとします。

W3C Baggage Specificationを実装するTextMapPropagator。

propagatorがどのように配布されるかについてはPropagators Distributionを参照してください。

環境変数をプロセス間のキャリア機構として使う場合の伝搬の扱いについてはEnvironment Variable Carriersを参照してください。

注: W3C baggageの仕様は現時点で、任意のメタデータに意味を割り当てていません。

extract時、propagatorはすべてのメタデータをエントリーごとに単一のメタデータインスタンスとして保存すべきです（should）。inject時、propagatorはW3Cの仕様の形式に従ってメタデータを追記すべきです（should）。これらの操作が従うべき追加の要件については、API PropagatorsのOperation節を参照してください。

Conflict Resolution

新しい名前・値の組が追加され、その名前が既存の名前と同じ場合、新しい組はMUST優先されるものとします。値は（ローカルで生成されたものかリモートのピアから受信したものかに関わらず）追加された値で置き換えられます。