# コンテキスト

> Source: https://www.ymotongpoo.com/works/otel-specs-ja/spec/context/


**ステータス**: [Stable](../document-status/)

## Overview

`Context`は、実行スコープを持つ値をAPIの境界を越えて、また論理的に関連する[実行単位](../glossary/#execution-unit)の間で運ぶ伝搬機構です。横断的関心事は、同じ共有`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)の呼び出しが結果として生じるべきである点に注意してください。

### Detach Context

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

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

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

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

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

- [Propagators API](/works/otel-specs-ja/spec/context/api-propagators/)
- [コンテキスト伝搬のキャリアとしての環境変数](/works/otel-specs-ja/spec/context/env-carriers/)