OpenCensusとの互換性

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

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

ステータス: Deprecated

[!NOTE] OpenCensusとの互換性に関する要求事項は非推奨（Deprecated）です。 既存のOpenCensusシムは、後方互換性のために継続してサポートされてもかまいません（MAY）が、 新たにOpenCensus互換性を実装することは本仕様書によって要求されません。

OpenCensusとの互換性に関する要求事項は、2026年6月時点で非推奨となっています。 本仕様書内のOpenCensusとの互換性に関する要求事項は、2027年6月より前には削除されません。

OpenTelemetryプロジェクトは、計装済みのコードベースの移行を容易にするため、OpenCensusプロジェクトとの後方互換性の提供を目指しています。

移行パス

OpenTelemetryへ移行する際の破壊的変更

OpenCensusからOpenTelemetryへの移行では、以下の理由により、生成されるテレメトリーに破壊的変更が必要になる場合があります。

• 名前や属性についての異なる、あるいは新しいセマンティック規約（例: grpc.io/server/server_latencyとrpc.server.call.durationの違い）
• データモデルの違い（例えば、OpenCensusはSumOfSquaredDeviationsをサポートしますが、OTLPはサポートしません）
• 計装APIの機能の違い（例えば、OpenCensusはコンテキストベースの属性をサポートしますが、OTelはサポートしません）
• 相当するOCとOTelのエクスポーター間の違い（例えば、OpenTelemetryのPrometheusエクスポーターは型と単位のサフィックスを追加しますが、OpenCensusは追加しません）

この移行パスは、ほとんどの破壊的変更をブリッジの導入というかたちにまとめています。これにより、利用者は最初の破壊的変更を導入するタイミングを自分で管理できるようになり、その後の計装の移行（サードパーティのライブラリを含む）は破壊的変更を伴わずに行えるようになります。

移行計画

OpenCensus AgentとProtocolからの移行

OC ProtocolによるOC Agentのデプロイから始める場合、以下の手順で移行します。

1. OpenCensusとOTLPのレシーバー、および相当するプロセッサーとエクスポーターを持つOpenTelemetry Collectorをデプロイする。
2. 破壊的変更: OC Protocolを送信している各ワークロードについて、OpenTelemetry CollectorのOpenCensusレシーバーへの送信に変更する。
3. OC Agentのデプロイを削除する。
4. 各ワークロードについて、以下のガイダンスに従ってOpenCensusからOpenTelemetryへアプリケーションを移行し、OTLPエクスポーターを使う。

ブリッジを使ったアプリケーションの移行

トレースとメトリクスの両方について完全にOpenCensusの計装を使っているアプリケーションから始める場合、以下の手順で移行できます。

1. エクスポーター（SDK）を移行する。
   1. 相当するエクスポーターを持つOpenTelemetry SDKをインストールする。
      1. OpenCensusのエクスポーターを使っている場合は、OTLPエクスポーターへ切り替える。
   2. 相当するOpenTelemetryのリソース検出器をインストールする。
   3. OpenCensusのTextFormatプロパゲーターに相当する、OpenTelemetryのW3c TraceContextプロパゲーターをインストールする。
   4. 破壊的変更: メトリクスとトレースのブリッジをインストールする。
   5. OpenCensusエクスポーターの初期化処理を削除する。
2. 計装（API）を移行する。
   1. 破壊的変更: OpenCensusの計装パッケージについて、相当するOpenTelemetryのパッケージへ移行する。
      1. gRPCを移行する場合、言語がサポートしていればBinaryPropagationプロパゲーターを有効にする。サポートしていない場合は、OpenTelemetryのgRPC計装でOpenCensusのBinaryPropagationを有効にする。
   2. 外部の依存関係については、それらがOpenTelemetryへ移行するのを待ち、依存関係を更新する。
   3. アプリケーションの一部である計装については、以下の「ライブラリ」向けのガイダンスに従って移行する。
3. クリーンアップ: メトリクスとトレースのブリッジを削除する。

OC計装を使うライブラリの移行

現状維持での移行

簡単な移行を望むライブラリは、計装をその場で置き換えることを選べます。

OpenCensusの計装を使うライブラリから始める場合、以下の手順で移行します。

1. ライブラリがOpenCensusからOpenTelemetryへ移行することを利用者に告知し、OCブリッジの採用を推奨する。
2. 単体テストをOCブリッジを使うように変更し、OpenTelemetryの単体テストフレームワークを使う。
3. 告知期間を経た後、計装を1行ずつOpenTelemetryへ移行する。よく使われているライブラリについては告知期間を長くとるべきです。
4. 単体テストからOCブリッジを削除する。

設定による移行

より早くネイティブのOpenTelemetry計装を追加したい、またはOpenCensusへの拡張サポートを提供したいライブラリは、利用者にOpenCensusの計装かOpenTelemetryの計装かを選択できるオプションを提供することを選べます。

OpenCensusの計装を使うライブラリから始める場合、以下の手順で移行します。

1. 単体テストをOCブリッジを使うように変更し、OpenTelemetryの単体テストフレームワークを使う。
2. OpenTelemetryの計装を有効にし、OpenCensusの計装を無効にできる設定を追加する。
3. その設定によって制御されるOpenTelemetryの計装を追加し、同じ単体テスト群を使ってテストする。
4. 告知期間を経た後、既定でOpenTelemetryの計装を使うように切り替える。
5. 非推奨期間を経た後、OpenCensusの計装を使うオプションを削除する。

トレースブリッジ

トレースブリッジは、OpenTelemetryのトレースAPIを使ってOpenCensusのトレースAPIを実装するシム層として提供されます。この層は、OpenTelemetry SDKの実装固有の詳細に依存してはなりません（MUST NOT）。

より具体的には、OpenCensusの計装をOpenTelemetryを使って記録できるようにすることが意図されています。このシム層は、upstreamのOpenTelemetry APIを公に公開してはなりません（MUST NOT）。

OpenCensusシムとOpenTelemetryのAPI/SDKは、前者から後者への移行を容易にするため、稼働中のサービスの中で同時に利用されることが想定されています。アプリケーションの所有者は、シムを介してOpenTelemetryへの移行プロセスを開始し、OpenTelemetryを使って新しいテレメトリー情報を追加していくことが見込まれます。徐々に、ライブラリや連携先もOpenTelemetryへ移行していき、最終的にシムが不要になります。

例えば、あるアプリケーションが現在、次のようなトレースを持っているとします。

|-- Application - Configured OpenCensus --------------------------------- |
    |--  gRPC -> Using OpenCensus to generate Trace A  --------- |
      |--  Application -> Using OpenCensus to generate a sub Trace B-- |

この場合、アプリケーションは、すべての下流の依存関係がOpenTelemetryへ更新されるのを待つことなく（あるいはそこでの非互換性に対処することなく）、外側の層をOpenTelemetryへ更新できるべきです。また、アプリケーションは自身の計装を書き直す必要もありません。

|-- Application - Configured Otel w/ OpenCensus Shim ------------------- |
    |--  gRPC -> Using OpenCensus to generate Trace A  --------- |
      |--  Application -> Using OpenCensus to generate a sub Trace B-- |

次に、アプリケーションは自身の計装を段階的に更新できます。

|-- Application - Configured Otel w/ OpenCensus Shim ---------------------- |
    |--  gRPC -> Using OpenCensus to generate Trace A  --------- |
      |--  Application -> Using OpenTelemetry to generate a sub Trace B-- |

このOtel -> OpenCensus -> Otelというトレーシングの層は「OpenTelemetryサンドイッチ」問題として捉えることができ、本仕様書の主な動機となっています。

最終的に、アプリケーションはOpenCensusのすべての使用箇所をOpenTelemetryへ更新します。

|-- Application - Configured Otel standalone ----------------------------- |
    |--  gRPC -> Using Otel to generate Trace A  --------- |
      |--  Application -> Using OpenTelemetry to generate a sub Trace B-- |

要件

OpenTelemetryとOpenCensusのトレースブリッジには、以下の要件があります。

• OpenCensusはOpenTelemetryへの必須の依存を持たない。
• OpenCensus側の実装への変更は最小限にとどめる。
• 利用者にとって使いやすく、理想的にはコードの変更が不要である。
• アプリケーションとライブラリ間の親子Span関係を維持する。
• アプリケーションとライブラリ間のスパンリンク関係を維持する。
• このコンポーネントは任意の依存関係でなければなりません（MUST）。

OpenCensusでのSpanの作成

シムが導入されている場合、すべてのOpenCensusのSpanは、OpenTelemetry APIで規定されたOpenTelemetryのTracerを経由して送出されなければなりません（MUST）。

この仕組みは、依存関係の発見と自動注入が可能な言語では、利用者にとって透過的であるべきです（SHOULD）。

Span上のメソッド

OpenCensusで規定されているすべてのメソッドは、OpenTelemetryの基盤となるSpanに委譲されます。

Resource

注: OpenCensusの「API」セクションでは、Resourceは利用できないようです。

既知の非互換性

以下に、OpenTelemetryとOpenCensusの仕様間で知られている非互換性を示します。OpenCensusでは未規定だがOpenTelemetryでは非互換な形で規定されている挙動に依存しているアプリケーションは、OpenCensusとOpenTelemetryのブリッジを使う対象にはなりません。

1. OpenCensusでは、子Spanに対して親Spanをいつ指定できるかについて仕様が存在しません。OpenTelemetryは、親SpanをSpan作成時に指定しなければならないことを規定しています。これにより、初期化後に親Spanを柔軟に指定できたOpenCensusのAPIとの間で問題が生じます。
2. Span作成後にSpanへ追加されたLinkについてです。これはOpenTelemetryではサポートされていないため、作成後にLinkが追加されたOpenCensusのSpanは、Linkを含まない形でOpenTelemetryのSpanへマッピングされます。
3. OpenTelemetryはSamplerがトレースプロバイダー全体に付随することを規定していますが、OpenCensusはSpanごとにカスタムのSamplerを許可しています。
4. OpenCensusとOpenTelemetryの両方において、TraceFlagsは単一のsampledフラグのみを規定しています（OpenTelemetry、OpenCensus）。一部のOpenCensusのAPIは、“sampled"に加えて"debug"や"defer"のトレーシングフラグをサポートしています。この場合、OpenCensusブリッジは、未規定のフラグを最も近いOpenTelemetryの相当物へ変換・サポートするよう最善を尽くします。

OpenCensusバイナリコンテキスト伝搬

シムは、OpenCensusのバイナリトレースコンテキスト形式をOpenTelemetryのSpanContextへマッピングする、OpenCensusのBinaryPropagator実装を提供します。

このアダプターは、OpenTelemetryのコンテキストを使ってOpenCensusのバイナリ形式を書き出すBinaryPropagatorの実装を提供しなければなりません（MUST）。この実装は、該当する場合はOpenCensusから引用してもかまいません。

BinaryPropagatorは、言語で可能であればTextMapPropagatorでなければなりません（MUST）。それができない場合、BinaryPropagatorはライブラリでなければならず（MUST）、OpenTelemetryのgRPC計装で使われることが想定されます。それらの言語のgRPC計装は、BinaryPropagatorを既定で有効にすべきではありません（SHOULD NOT）が、利用者が有効化できるよう設定を提供すべきです（SHOULD）。

メトリクス / Stats

OpenTelemetryは、OpenTelemetryのMetricProducerインターフェースを実装するOpenCensus-Metrics-Shimコンポーネントを提供します。Produce()が呼び出されると、シムはOpenCensusのグローバルな状態からメトリクスを収集し、OpenTelemetryのメトリクスバッチへ変換して返します。

要件

• このコンポーネントは任意の依存関係でなければなりません（MUST）。
• OpenCensusのAPI配布物にOpenTelemetryが含まれることを要求してはなりません（MUST NOT）。
• 実行時にOpenCensusがOpenTelemetryに依存することを要求すべきではありません（SHOULD NOT）。
• OpenCensusへの変更をほとんど、あるいは一切要求してはなりません（MUST）。
• プッシュ型とプル型の両方のエクスポーターと互換性がなければなりません（MUST）。
• Gauge、Counter、Cumulative Histogram、Summaryをサポートしなければなりません（MUST）。
• Gauge Histogramのサポートは必須ではありません（NOT REQUIRED）。
• エグゼンプラーへのスパンコンテキストの記録用ユーティリティを提供する言語では、エグゼンプラーのスパンコンテキストをサポートしなければなりません（MUST）。

Resource

シムは、OpenCensusのメトリクスに付随するResourceを破棄し、初期化時に提供されたResourceを挿入しなければならず（MUST）、それがなければOpenTelemetryの既定のResourceにフォールバックします。

Instrumentation Scope

シムは、そのシムを識別するInstrumentation Scopeの名前とバージョンを追加しなければなりません（MUST）。

使い方

シムは、OpenTelemetry SDKを設定する際に、OpenTelemetryのMetricReaderへのオプションとして渡すことができます。これにより、このブリッジはプッシュ型・プル型のメトリクスエクスポーターの両方で機能します。

既知の非互換性

• OpenTelemetryはOpenCensusのGaugeHistogram型をサポートしません。このブリッジを使う場合、これらのメトリクスは破棄されなければなりません（MUST）。
• OpenTelemetryは現在、コンテキストベースの属性（タグ）をサポートしていません。
• OpenTelemetryはOpenCensusのSumOfSquaredDeviationフィールドをサポートしません。このブリッジを使う場合、これは破棄されます。