Yoshi Yamaguchi

コンテキスト

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

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

ステータス: Stable

Overview

Contextは、実行スコープを持つ値をAPIの境界を越えて、また論理的に関連する実行単位の間で運ぶ伝搬機構です。横断的関心事は、同じ共有Contextオブジェクトを使ってプロセス内でそのデータにアクセスします。

Contextは不変でなければならず（MUST）、その書き込み操作は、元の値と指定された更新後の値を含む新しいContextの生成をMUST結果とするものとします。

言語は、既存の広く使われている単一のContext実装があれば、それを使うことが期待されます。極めて明確な既存の選択肢が存在しない場合、OpenTelemetryは独自のContext実装をMUST提供するものとします。言語によっては、その使用方法が明示的か暗黙的かが異なります。

Contextを暗黙的に使う言語で計装を書くユーザーは、Context APIを直接使うことを推奨されません。そのような場合、ユーザーは代わりに、指定されたContextに対してトレースやバゲージのエントリーを設定するといった操作を行うために、横断的関心事のAPIを介してContextを操作します。

Contextは、それぞれの言語の違いを伴いつつ、以下の操作を持つことが期待されます。

Create a key

キーは、横断的関心事が自身のローカル状態へのアクセスを制御できるようにするために使われます。キーは、同じコンテキストを使う可能性のある他のライブラリが誤って同じキーを使ってしまわないように一意です。関心事は、キーへの直接的な公開アクセスを提供するのではなく、APIを介してデータアクセスを媒介することが推奨されます。

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

  • キー名。キー名はデバッグ目的で存在し、キーを一意に識別するものではありません。言語の制約によって異なる動作が定められていない限り、同じ名前でCreateKeyを複数回呼び出しても同じ値をSHOULD NOT返すものとします。想定される型に対する制限は言語によって異なるため、このパラメータは実装の詳細に委ねられます。

このAPIは、新しく作成されたキーを表す不透明なオブジェクトをMUST返すものとします。

Get value

関心事は、Contextによって表される現在の実行状態において、自身のローカル状態にアクセスできます。

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

  • Context
  • キー

このAPIは、指定されたキーに対するContext内の値をMUST返すものとします。

Set value

関心事は、Contextによって表される現在の実行状態に、自身のローカル状態を記録できます。

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

  • Context
  • キー
  • 設定する値

このAPIは、新しい値を含む新しいContextをMUST返すものとします。

Optional Global operations

これらの操作は、Contextを暗黙的に使う言語でのみ実装されることが期待されるため任意です。これらの操作は、SDKコンポーネントやOpenTelemetryの計装ライブラリが自動的なスコープの切り替えを実装したり、より高レベルのAPIを定義したりする目的でのみ使うべきです（SHOULD）。

Get current Context

このAPIは、呼び出し元の現在の実行単位に関連付けられたContextをMUST返すものとします。

Attach Context

Contextを呼び出し元の現在の実行単位に関連付けます。

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

  • Context

このAPIは、以前のContextを復元するためのTokenとして使える値をMUST返すものとします。

この操作を呼び出すたびに、対応するDetach Contextの呼び出しが結果として生じるべきである点に注意してください。

Detach Context

呼び出し元の現在の実行単位に関連付けられたContextを、指定されたContextをアタッチする前の値にリセットします。

この操作は、正しいContextが呼び出し元の現在の実行単位に関連付けられていることを確認する助けとなることを意図しています。ユーザーはこれを利用して、誤った呼び出し順序（現在のインスタンスではないContextをデタッチしようとするなど）を識別できます。この場合、この操作はエラーのログ出力やエラー値の返却など、誤った呼び出し順序をユーザーに警告する信号を発してもよいです（MAY）。

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

  • Contextをアタッチする以前の呼び出しで返されたToken

このAPIは、操作が成功したかどうかを確認するために使える値をMAY返してもよいものとします。