Yoshi Yamaguchi

テレメトリーの安定性

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

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

ステータス: Development

この節では、OpenTelemetryの計装によって生成されるテレメトリーに対する安定性の要件を定義します。

OpenTelemetryが作成するすべての計装は、生成するテレメトリーの観点からUnstableまたはStableのいずれかとラベル付けされます。

新しいメトリクス、スパン、スパンイベント、ログレコードの追加、およびスパン、スパンイベント、ログレコード、リソースへの新しい属性の追加は、追加的で破壊的でない変更とみなされ、UnstableおよびStableの計装のいずれにおいても常に許容されます。

生成されるテレメトリーに対するその他の変更は、以下のルールによって規定されます。

Unstable計装

Unstableなテレメトリーを生成する計装（以下、unstableな計装）は、計装の作者がその言語に適していると考える任意の手段（例えばバージョン番号、アーティファクト名、ドキュメントなど）によって、そのようにはっきりとラベル付けされるべきです（SHOULD）。

unstableな計装は、生成するテレメトリーの形状や、その形状がバージョンを経てどのように変化するかについて、いかなる保証も提供しません。スパンやメトリクスの名前、あらゆるテレメトリー項目の属性は、制約なく変更される可能性があります。テレメトリーデータが特定のスキーマに準拠する場合、生成されるテレメトリーはSchema URLを指定してもかまいません（MAY）。

OpenTelemetryが作成するunstableな計装は、OpenTelemetryセマンティック規約に記述されていない追加のテレメトリーを生成してもかまいません（MAY）。

TODO: 生成されるテレメトリーがunstableな計装からのものであることを、ワイヤー上で示す必要があるかどうかを決定する。

Stable計装

[!WARNING] テレメトリーの安定性のためにスキーマ変換に依拠することについては、現在モラトリアム（一時停止）が設けられています。

Stableなテレメトリーを生成する計装（以下、stableな計装）は、計装の作者がその言語に適していると考える任意の手段（例えばバージョン番号、アーティファクト名、ドキュメントなど）によって、そのようにはっきりとラベル付けされるべきです（SHOULD）。

stableな計装は、固定スキーマのプロデューサーとスキーマファイル駆動のプロデューサーという2つのカテゴリーに分類されます。

OpenTelemetryが作成するstableな計装は、OpenTelemetryセマンティック規約に記述されていないテレメトリーを生成すべきではありません（SHOULD NOT）。しかし、このルールに違反する場合、その計装は固定スキーマのプロデューサーであるかスキーマファイル駆動のプロデューサーであるかにかかわらず、そのようなテレメトリーを変更してはなりません（MUST NOT）。生成されたテレメトリーがセマンティック規約に追加されれば、以下に説明する形で変更が許容されるようになります。

固定スキーマのテレメトリープロデューサー

Stableとラベル付けされ、生成するテレメトリーにSchema URLを含めない計装は、固定スキーマのテレメトリープロデューサーと呼ばれます。

このような計装は、生成するテレメトリーをいかなる形でも変更することを禁じられています。時間の経過とともに仕様書が変わり、セマンティック規約が更新されたとしても、その計装が変更を取り込むことは依然として禁じられています。計装がセマンティック規約の変更を取り込みたい場合は、生成するテレメトリーに適切なSchema URLを追加することで、まずスキーマファイル駆動のテレメトリープロデューサーにならなければなりません。

スキーマファイル駆動のテレメトリープロデューサー

生成するテレメトリーにSchema URLを含むstableな計装は、スキーマファイル駆動のテレメトリープロデューサーと呼ばれます。

このような計装は、テレメトリーの安定性のためにスキーマ変換に依拠することについてのモラトリアムが解除されるまで、生成するテレメトリーを変更することを禁じられており、その日までは固定スキーマのテレメトリープロデューサーとまったく同じ制約を受けます。

モラトリアムが解除された後は、次の条件がすべて満たされる場合に限り、stableな計装は生成するテレメトリーを変更できます。

  • その変更がOpenTelemetryセマンティック規約の一部であり、仕様書のリリース済みバージョンに含まれている。
  • その変更を記述する、対応する公開されたOpenTelemetryスキーマファイルが存在する。
  • 生成されるテレメトリーが、対応するSchema URLを正しく指定している。