> Source: https://www.ymotongpoo.com/works/oteps/otep-4815/


# OTEP-4815: セマンティック規約スキーマ v2

この OTEP では、複数の規約レジストリをサポートし、メタデータへの完全なアクセスを提供する新しいテレメトリースキーマフォーマットを提案します。

これは [OTEP 0243 - OpenTelemetryにおけるアプリケーションテレメトリースキーマの導入 - ビジョンとロードマップ](/oteps/0243-app-telemetry-schema-vision-roadmap.md) を土台とし、それと整合するものです。

## 動機 {#motivation}

セマンティック規約はテレメトリースキーマを記述します。
OpenTelemetryがホストする規約は、HTTPのような共通の概念や、さまざまなOTel計装が生成するテレメトリーを記述します。

OTel Collectorや言語固有の計装は、それぞれのエコシステム内でのみ適用可能な独自の規約を公開できるべきです。
また、[Schema URL](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.54.0/specification/schemas/README.md#schema-url) を通じて、使用しているスキーマを伝える手段も持つべきです。

OTelがホストしていない計装も、OTelの規約に依存関係を持たせつつ、独自の規約を文書化して公開できるべきです。

テレメトリーの利用者は、テレメトリーを検証、アップグレード、あるいはサニタイズするために、完全なスキーマにアクセスできるべきです。
Schema URLを使って発見可能な完全に解決されたレジストリは、テレメトリーに関するメタデータの追加のチャネルとして機能します。
このアプローチは、テレメトリー量やそれに伴うコストを増加させません。

例:

- あるテレメトリーシグナルが与えられたとき、利用者はそれに対応するテレメトリー項目の完全な定義を見つけられるべきです。
  これにより、いくつかのユースケースが実現します。
  - UXヒントやAIアシスタント（このメトリクスが何を測定するのか、あるいはこの属性が何を意味するのかを説明する）
  - 検証（テレメトリー項目がスキーマに準拠しているか）
  - コスト削減（本質的でないメトリクスをすべてドロップする）
  - サニタイズ（スキーマ内の注釈に基づいて、機密性の高い可能性のあるデータをマスクする）
- OTelの規約を依存関係として取り込みつつ、会社やサービス固有の規約を文書化し、そのスキーマを利用者がアクセスできるようにします。
  詳細は [OTEP 0243](/oteps/0243-app-telemetry-schema-vision-roadmap.md) を参照してください。

[テレメトリースキーマ](/specification/schemas/README.md) はこうしたシナリオの基盤を築いてきましたが、それらを完全にはサポートしていません。
これはスキーマの変換を中心に設計されており、属性名やメトリクス名の変更のような、スキーマバージョン間の差分を記述します。
これは単一のレジストリ（OpenTelemetryセマンティック規約）を前提として動作しますが、任意の規約レジストリをサポートするためにはアップグレードが必要です。

## 詳細 {#details}

有効なSchema URLに対してHTTP GETが発行されると、そのSchema URLをホストするサービスは、応答として有効な *manifest* を返すべきです（SHOULD）。

*manifest* の例を次に示します。

```yaml
file_format: manifest/2.0
# schema_url serves as the primary source of schema family and version
# schema family (everything before version) must be unique
schema_url: https://opentelemetry.io/schemas/semconv-dev/1.40.0-dev
# MAY point to a file under schema_url or to an arbitrary location.
resolved_registry_uri: https://opentelemetry.io/schemas/semconv-dev/1.40.0-dev/resolved.yaml

stability: development

# metadata
description: OpenTelemetry Semantic Conventions

# future
# diff_uri: ...
# all_in_one_uri: https://github.com/open-telemetry/semantic-conventions/archive/refs/tags/v1.40.0-dev.tar.gz
```

manifestには、次を含むセマンティック規約レジストリに関する情報が含まれます。

- `schema_url`（必須） - レジストリとそのバージョンを識別します。
  [Schema URLフォーマット](/specification/schemas/README.md#schema-url) に従わなければなりません（MUST）。
  バージョンより前のURL部分が *Schema Family* であり、これは既存の [Schema URL](/specification/schemas/README.md#schema-url) 仕様で定義されているとおりです。
- `resolved_registry_uri`（必須） - [*resolved* レジストリ](#definition-and-resolved-schemas)を含むYAMLファイルを指します。
  有効なURLでなければなりません（MUST）。
- `stability`（必須） - レジストリの安定度です。
  [Maturity levels](/specification/document-status.md#maturity-levels) のいずれかでなければなりません（MUST）。

他のプロパティは将来追加される可能性があります。

Schema URLをホストするサービスは、gzip圧縮をサポートしなければならず（MUST）、呼び出し側は [`Accept-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding) ヘッダーでそれを制御してもかまいません（MAY）（これは`opentelemetry.io`ですでにサポートされています）。

新しいプロパティは、マイナーな`file_format`バージョンの繰り上げに伴ってmanifestに追加されるかもしれません（MAY） - たとえば、以前のバージョンとの差分を指すURLを追加し、利用者が必要な部分だけをダウンロードできるようにする、といったことです。
将来のメジャーバージョンの繰り上げは、[バージョニングと安定性のポリシー](/specification/versioning-and-stability.md) に従います。

`manifest`、`resolved`、`definition` の各フォーマット識別子に適用されるルールについては、[File format and versioning](#file-format-and-versioning) を参照してください。

特定のリリースに対するすべてのアーティファクトは不変でなければなりません（MUST）。
利用者はホットパス上で使用する場合、manifestや解決済みレジストリ、あるいはそれらの一部をキャッシュすべきです（SHOULD）。

manifestのスキーマと、Schema URLを使ってそれを取得するREST APIは、公開の、認証不要のアクセス向けに正式に文書化される予定です。

`schema_url` のフォーマットと、スキーマファミリーがどのように成熟度（たとえば`semconv-dev`）を符号化するかについての詳細は、[Schema URL structure](#schema-url-structure) と [Differentiating between stable and not stable schemas](#differentiating-between-stable-and-not-stable-schemas) を参照してください。

### `file_format: 1.1.0` との違い {#difference-with-file_format-110}

スキーマの[ファイルフォーマット1.1.0](/specification/schemas/file_format_v1.1.0.md)には、`schema_url`と`versions`セクションが含まれていました。

`versions`セクションは、これまでのすべてのバージョンを列挙し、それぞれについて`vX`を`vX + 1`にアップグレードするために適用すべき変換のリストを含んでいました。

この機能は、現在では別の手段でカバーされています。
詳細については、[Listing available schema versions](#listing-available-schema-versions) と [Schema Transformations](#schema-transformations) を参照してください。

### Schema URLの構造 {#schema-url-structure}

現在のSchema URLのパターンは、レジストリごと、あるいは安定度ごとの区別を提供していません - `opentelemetry.io/schemas/{version}`。

自身の規約を公開したいOTelのコンポーネントは、次の新しいパターンに従うべきです（SHOULD）。

```text
opentelemetry.io/schemas/{component}[-{maturity}]/{version}[-{maturity}]
```

- `{component}` はレジストリを識別します - たとえば、中央の`semantic-conventions`リポジトリには`semconv`、OTel Collectorの規約には`collector`が使われます。
- `{maturity}`（任意）は、特定の安定度レベルにおけるレジストリのビューを選択します。
  省略された場合、URLは安定版のビューを指します。
  許可されるサフィックスは、このリポジトリで定義されている[maturity levels](/specification/document-status.md#maturity-levels)に対応します。

  | 成熟度レベル    | サフィックス    |
  | ----------------- | --------- |
  | 安定版            | *（なし）*  |
  | リリース候補 | `-rc`     |
  | ベータ | `-beta`   |
  | アルファ | `-alpha`  |
  | 開発版        | `-dev`    |

  このサフィックスはスキーマファミリーの一部です。
  成熟度サフィックス付きのバージョンとサフィックスなしのバージョンを1つのスキーマファミリーの下で混在させると、[依存関係の競合解決](#dependency-resolution-mechanism)が依拠しているバージョンの順序付けが壊れてしまいます。

- `{version}` は [Schema Version Number](/specification/schemas/README.md#schema-version-number) であり、該当する場合はプレリリース構成要素を伴うSemVer 2.0に従います。

レジストリは、同一リリースの複数の成熟度サフィックス付きビューを公開してもかまいません（MAY）。
各ビューは、それぞれ独自の一覧用SchemaURLと独自のmanifestを持つ、個別のスキーマファミリーです。

例:

- `opentelemetry.io/schemas/semconv/{version}` - semantic-conventionsリポジトリの安定版規約
- `opentelemetry.io/schemas/semconv-dev/{version}-dev` - semantic-conventionsリポジトリの開発版規約
- `opentelemetry.io/schemas/collector/{version}` - CollectorおよびCollector Contribの安定版規約
- `opentelemetry.io/schemas/java-instrumentation/{version}` - Java計装の安定版規約

#### 安定版と非安定版のスキーマの区別 {#differentiating-between-stable-and-not-stable-schemas}

現在、Schema URLにはセマンティック規約のバージョンが含まれていますが、安定度を示す情報は含まれていません。

OpenTelemetryセマンティック規約は、各リリースで2つのスキーマを公開する予定です。

- 安定版（例: `https://opentelemetry.io/schemas/semconv/1.40.0`） - セマンティック規約レジストリのうち安定版のサブセットのみを含みます。
- 開発版（例: `https://opentelemetry.io/schemas/semconv-dev/1.40.0-dev`） - 安定度に関わらず、レジストリで定義されているすべてのセマンティック規約を含みます。

両方のレジストリは同一のリリースから生成され、同じバージョン番号を共有します。
それぞれが独自の一覧用エンドポイントと独自のmanifestを持つ、個別のスキーマファミリーです。

追加の中間的な成熟度レベル（`-rc`、`-beta`、`-alpha`）が公開されることもあります（MAY）。
特定の成熟度で公開されたレジストリは、その成熟度以上のすべての規約を含むべきです（SHOULD）（たとえば`-alpha`レジストリはalpha、beta、RC、安定版の規約を含みます）。
実際には、中間レベルを公開することは現実的でなく、通常は不要です - 安定版と開発版のペアで、ほとんど、あるいはすべてのユースケースをカバーできると見込まれます。

manifestファイルは、実際の安定度レベルを含まなければなりません（MUST）。

OpenTelemetryの計装は、自身が従う規約のバージョンを反映したSchema URLを提供すべきです（SHOULD）。

たとえば、HTTP計装がHTTP規約に加えて実験的な機能をサポートしており、ユーザーがそれらの実験的機能を有効にしている場合、その計装は開発版のSchema URL（例: `https://opentelemetry.io/schemas/semconv-dev/1.40.0-dev`）を使用すべきです（SHOULD）。

#### 利用可能なスキーマバージョンの一覧表示 {#listing-available-schema-versions}

Schema URLをホストするサービスは、利用可能なバージョンの一覧表示もサポートすべきです（SHOULD）。

[Schema URLフォーマット](/specification/schemas/README.md#schema-url) は `http[s]://server[:port]/path/<version>` として定義されているため、サービスは `http[s]://server[:port]/path/` に対して利用可能なSchema URLのリストを返すべきです（SHOULD）。

たとえば、`https://opentelemetry.io/schemas/semconv` は次を返します。

```yaml
- "https://opentelemetry.io/schemas/semconv/1.{N}.0",
- "https://opentelemetry.io/schemas/semconv/1.{N-1}.0",
- ...
```

このフォーマットとコンテンツタイプは、非破壊的な形でページングをサポートできるように、正式に文書化される予定です。

この要件は、上記のバージョンセグメントより上の完全なパス - この例では`https://opentelemetry.io/schemas/semconv` - にのみ適用されます。
祖先のパスセグメント（たとえば`https://opentelemetry.io/schemas`）での一覧表示は、この OTEP のスコープ外です。

### definitionとresolvedのスキーマ {#definition-and-resolved-schemas}

セマンティック規約を書くために使われる[*definition* スキーマ](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.v2.md)は、*resolved* レジストリとは異なります。

たとえば、メトリクスは *definition* スキーマにおいて次のように定義できます。

```yaml
# definition schema
file_format: definition/2
attributes:
- key: my.operation.name
  type: string
  stability: development
  brief: My service operation name as defined in this Open API spec
  examples: ["get_object", "create_collection"]
...
metrics:
- name: my.client.operation.duration
  stability: stable
  instrument: histogram
  unit: s
  attributes:
    - ref: my.operation.name
    - ref_group: my.operation.server.attributes
    - ref: error.type
```

属性はメトリクスとは別に定義され、メトリクスから参照されます。
このアプローチは再利用性と一貫性を最適化するものです。
デフォルト値や継承されるプロパティは省略されます。
定義は任意の数のファイルにまたがって分散させることができます。

*resolved* レジストリは、一連の定義から生成される単一のファイルです。
これにはすべての属性がシグナル定義や絞り込みとともに含まれます。
配布とインメモリ表現に最適化されています。

このメトリクスに対する *resolved* レジストリは次のようになります。

```yaml
# resolved registry
file_format: resolved/2.0  # versioned independently of manifest format
schema_url: https://acme.com/schemas/1.0.0  # URL where the owning manifest is (or will be) published
attribute_catalog:
...
- key: my.operation.name
  type: string
  stability: development
  brief: My service operation name as defined in this Open API spec
  examples: ["get_object", "create_collection"]
...
registry:
  attributes:
  ...
  - 888   # this is the index of `server.address` in the attribute_catalog
  - 1042  # this is the index of `my.operation.name` in attribute_catalog
  ...
  metrics:
  - name: my.client.operation.duration
    instrument: histogram
    unit: s
    attributes:
      - base: 1042  # this is the index of `my.operation.name` in attributes list
        requirement_level: required
      - base: 888  # this is the index of `server.address` in the attributes list
        requirement_level: recommended
      ...
```

これらの例は説明のためのものです - 完全な構造については[JSON schema](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv.resolved.v2.json)を参照してください。

resolvedレジストリファイルは、特定のバージョンに対して一度公開されると不変です。
manifestとresolvedレジストリは一緒にバージョン管理され、各リリースは一意の`schema_url`を使用しなければなりません（MUST）。

resolvedレジストリを変更する必要がある場合は、manifestとresolvedレジストリの両方の新しいバージョンをリリースしなければなりません（MUST）。

resolvedレジストリは、[JSON schema](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv.resolved.v2.json)として正式に文書化されています。
[概要](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-schemas.md#resolved-schema)を参照してください。

参考データとして、[OTelセマンティック規約 v1.38.0](https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.38.0)のresolvedレジストリは、非圧縮でおよそ1.2MB、圧縮時でおよそ200KBです。

#### ファイルフォーマットとバージョニング {#file-format-and-versioning}

ファイルフォーマットは`{prefix}/<major>[.<minor>]`というパターンに従います。
サポートされるフォーマットは次のとおりです。

- `definition/2`
- `definition/2.{minor}`
- `manifest/2.{minor}`
- `resolved/2.{minor}`

パッチバージョンはフォーマット識別子には含まれません。

マイナーバージョンを含むすべてのフォーマットには、同じ互換性ルールが適用されます。

- **同じメジャーバージョン内での新しいマイナーバージョン**: 後方互換です。
  新しい任意のフィールドはメジャーバージョン内で追加されることがあります。
  利用者はファイルの解析を継続し、未知のフィールドは無視すべきであり（SHOULD）、そのファイルが利用者のサポートするものより新しいマイナーバージョンを使用していることを示す警告をログに記録すべきです（SHOULD）。
- **メジャーバージョンの不一致**: 破壊的変更です。
  利用者は解析前にメジャーバージョンを確認しなければならず（MUST）、サポートされていないメジャーバージョンのファイルの処理を拒否しなければなりません（MUST）。
  メジャーバージョンの移行のためのマイグレーションツールと文書が提供される予定です。

definitionスキーマは、マイナーバージョンを省略したメジャーのみの形式`definition/2`も受け付けます。
これにより、weaverが新しいマイナーバージョンをリリースするたびに、著者がすべてのdefinitionファイルをバージョンアップする必要がなくなります。
このようなファイルを解析する際、利用者（weaver）は未知のフィールドを無視すべきであり（SHOULD）、そのファイルが利用者のサポートするものより新しいマイナーバージョンを使用している可能性があるため、そうしたフィールドが見つかった場合は警告をログに記録すべきです（SHOULD）。

### 任意のセマンティック規約レジストリの構築と公開 {#building-and-publishing-arbitrary-semantic-convention-registries}

任意の組織、プロジェクト、アプリケーションは、独自のセマンティック規約を定義し、バージョン管理されたレジストリとして公開し、上記で説明した同じmanifestおよびresolvedレジストリのフォーマットを使ってSchema URL経由で公開してもかまいません（MAY）。

Weaverは、公開用アーティファクト（manifest、resolvedレジストリ、および将来の追加物）を読み取り、解決し、生成するための`weaver registry package --resolved-registry-uri <url>`を提供する予定です。
このコマンドは *definition* manifestとローカルのsemconv定義を消費し、resolvedレジストリと公開用manifestを出力します。

**Definitions（定義）:**

- semconvレジストリの定義ファイル（属性、エンティティ、シグナル）
- `manifest.yaml`（definition manifest。依存関係に関する情報を含む）

*definition manifest* には、開発時に利用可能なレジストリに関する情報が含まれ、公開用manifestを作成するために使用されます。

definition manifestの例を次に示します。

```yaml
schema_url: https://acme.com/schemas/1.0.0
description: This registry contains semantic conventions for Acme Corp.
stability: stable
```

**Publication artifacts（公開用アーティファクト）:**

- `manifest.yaml`（公開用manifest、`file_format: manifest/2.0`）。Schema URLに公開されます。
- `resolved-registry.yaml`。manifestで指定されたURLに公開されます。

上記のdefinitionから生成される公開用manifestの例を次に示します。

```yaml
file_format: manifest/2.0
schema_url: https://acme.com/schemas/1.0.0
resolved_registry_uri: https://acme.com/schemas/1.0.0/resolved.yaml
stability: stable
description: This registry contains semantic conventions for Acme Corp.
```

`resolved_registry_uri`は、`weaver registry package`に渡された公開先の場所に基づいて設定されます。
これは任意の場所を指します。

#### OpenTelemetryセマンティック規約に依存するレジストリの作成 {#creating-a-registry-that-depends-on-opentelemetry-semantic-conventions}

OpenTelemetry Collectorのコンポーネント、計装ライブラリ、その他任意のコンポーネントは、独自の規約を定義でき、OTelセマンティック規約やその他任意のレジストリを依存関係として取り込んでもかまいません（MAY）。

OTel規約への依存を含むdefinition manifestの例を次に示します。

```yaml
name: activemq-jmx-instrumentation
description: This registry contains semantic conventions for ActiveMQ JMX instrumentation.
version: 1.0.0
repository_url: https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/jmx-metrics/library/activemq.md
stability: development
dependencies:
  # schema_url is expected to point to the publication manifest of the dependency.
  # It's a unique identifier containing schema family and version.
  - schema_url: https://opentelemetry.io/schemas/semconv-dev/1.39.0-dev
    # in some cases (when registry_path is provided) schema_url is ONLY used as
    # a unique identifier containing schema family and version.
    # The actual registry artifacts come from `registry_path` property.
    # This allows supporting v1 registries and simplifying local development.
    # `registry_path` may be a local folder or a link to the registry on GitHub
    registry_path: https://github.com/open-telemetry/semantic-conventions/archive/refs/tags/v1.39.0.zip[model]
```

この例は簡略化されたものです - 実際には、Java計装固有のすべての規約をこのレジストリに含め、それらすべてに対して1つのSchema URLを公開することになるでしょう。

definitionは次のようになるでしょう。

```yaml
file_format: definition/2
# new attributes defined in this registry
attributes:
  - key: activemq.broker.name
    brief: The name of the ActiveMQ broker.
    ...
metrics:
  # based on https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/jmx-metrics/library/activemq.md
  - name: activemq.producer.count
    instrument: updowncounter
    stability: development
    brief: The number of producers attached to this destination
    unit: "{producer}"
    attributes:
      - ref: messaging.destination.name
      - ref: activemq.destination.type
      - ref: activemq.broker.name
imports:
  metrics:
    # this is not realistic, just an example of how to import existing metric
    - messaging.client.operation.duration
    # can also import by wildcard
    # - messaging.*

```

*resolved* レジストリには次が含まれます。

- このレジストリで定義されているすべてのもの
- 明示的にインポートまたは参照されているシグナルと属性についての（依存関係からの）定義と絞り込み

レジストリで使用されていない依存関係由来の属性やシグナルは、デフォルトでは含まれません。

[完全な例](https://github.com/open-telemetry/opentelemetry-weaver-examples/pull/33)を確認してください。

### 依存関係の解決メカニズム {#dependency-resolution-mechanism}

原則:

- **最新バージョンが優先されます:** あるレジストリが（推移的に）同じレジストリの複数のバージョンに依存している場合、解決プロセス中はその依存関係のうち最新のバージョンのみが使用されます。
  - あるオブジェクトが参照されているものの、選択されなかった古いバージョンにのみ存在する場合、解決は失敗します。
- **正確な依存関係バージョンのみがサポートされます:** 現時点ではバージョン範囲の指定はサポートされていません。
- **すべてのシグナルと属性は識別可能です**: メトリクス名、イベント名、スパンタイプ、エンティティタイプ、または属性キーのいずれかによって識別されます。
  シグナルの絞り込みには一意のIDがあります。
- **競合は許可されません:** 解決プロセスにおいて、同じキーを持つ複数の属性、あるいは同じ識別子を持つ複数のシグナルや絞り込みが発見された場合、解決は失敗します。
  このルールは単一のレジストリ内でも、そのすべての依存関係にまたがっても適用されます。
- **ソースの追跡:** 属性とシグナル定義（それらの絞り込みを含む）には、そのソースレジストリとバージョンを識別する来歴メタデータが含まれます。
- **拡張性:** manifestフォーマットは拡張可能に設計されており、将来的に非破壊的な形で追加の競合解決ヒントを追加できます。

## トレードオフと緩和策 {#trade-offs-and-mitigations}

### スキーマの変換 {#schema-transformations}

> [!NOTE]
>
> 私たちは、現在の[Development](/specification/document-status.md)ステータスにあるスキーマの[ファイルフォーマット1.1.0](/specification/schemas/file_format_v1.1.0.md)の公開を停止します。
>
> これは、（Collectorの`schemaprocessor`のような）スキーマ変換を行うコンポーネントにとって破壊的変更です。

スキーマの変換（diff）は、次の理由により公開 **しません**。

- resolvedレジストリには、非推奨（名前変更）となった属性やシグナルに関する情報がすでに含まれており、バージョンアップグレード時に名前変更の変換を適用するために使用できます。
- 必要に応じてオンデマンドで差分を生成する能力があります。
- 採用が限定的であり、機能も既存の多くの変換ニーズをカバーできていません。
- 変換に関するテストインフラが不足しており、その結果として、いくつかの不変であるはずのスキーマファイルに誤りがありました（採用が限定的だったため、誰も苦情を言いませんでした）。

新しいmanifestに加えて旧スキーマを公開することも可能ですが、それには（新しいmanifest用に`https://opentelemetry.io/schemas/v2/1.42.0`のような）別のURLフォーマットを使う必要があり、混乱を招くことになります。
さらに重要な点として、実際の利用が限定的であることを踏まえると、それは正当化できないと私たちは考えています。

現在Schema URLのコンテンツをダウンロードしている利用者は、認識できない、そして自分たちのシナリオでは使用できない新しいファイルフォーマットを受け取ることになります。

私たちが把握している既存のスキーマファイルの唯一の利用者は[schemaprocessor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/schemaprocessor)であり、これは約1年前にスキーマ変換のために部分的に実装されましたが、OTel Collectorのディストリビューションには含まれていません。

`schemaprocessor`の推奨されるアップデート方法は、ユーザーを壊さないようにファイルフォーマット`1.1.0`のサポートを維持しつつ、新しいファイルフォーマットへのサポートを追加することです。
これは、あるバージョン範囲が旧スキーマファイルと新スキーマファイルの両方でカバーされている場合、2段階の変換を伴う可能性があります。

可能なマイグレーションの選択肢を以下に列挙します。

[選択肢1: resolvedレジストリのみに基づくアップグレード](#migration-option-1-upgrades-based-on-resolved-registry-only)から始めることを推奨します。

（変換のリストに依存する）`schemaprocessor`に似たアプローチをすでに実装しているユーザーやベンダーにとっては、代替のマイグレーション選択肢として[選択肢2: オンデマンドでdiffを生成する](#migration-option-2-generate-diff-on-demand)があります。

スキーマ変換が進化してより多くの機能を提供するようになれば、OpenTelemetryは[選択肢3: 将来的にdiffを公開する](#migration-option-3-publish-diff-in-the-future)ためのツールとサポートの提供を検討できるでしょう。

#### 選択肢1: resolvedレジストリのみに基づくアップグレード {#migration-option-1-upgrades-based-on-resolved-registry-only}

OpenTelemetryセマンティック規約は、レジストリから属性やメトリクス、その他の識別可能なシグナルを削除することを許可していません。

ある属性やシグナルが推奨されなくなった場合、それは非推奨として扱われます。
後方互換性のチェックがこのポリシーを強制します。

resolvedレジストリにおける非推奨化の例を次に示します。

```yaml
attributes:
- key: http.method
  type: string
  stability: development
  deprecated:
    reason: renamed  # can also be `obsolete` or `uncategorized`
    renamed_to: http.request.method   # the replacement is validated to exist and not be deprecated.
    note: Replaced by `http.request.method`.
```

スキーマバージョン1.Nには、v1.N-Mからv1.Nへのアップグレード方法についての情報が含まれます。
このアプローチは1つのメジャーバージョンに限定され、アップグレードのみをカバーします。

この選択肢は、既存のスキーマ変換と同じ制約を共有しており、その能力の大部分をカバーしています。
これを置き換えとして使用することはできますが、将来[スキーマ変換が進化した](#schema-transformations-evolution)場合には、このアプローチだけでは不十分になります。

#### 選択肢2: オンデマンドでdiffを生成する {#migration-option-2-generate-diff-on-demand}

スキーマ変換を実行するために、schema processorやその他の利用者候補は、サポートしたいバージョン（たとえばvN → vTarget、vN+1 → vTarget）について、起動時（あるいはランタイム時に遅延して）に差分を生成する[`weaver registry diff`](https://github.com/open-telemetry/weaver/blob/main/docs/usage.md#weaver-registry-diff)の利用が推奨されます。

```bash
weaver registry diff \
  --registry ./semconv-dev-1.38.0 \
  --baseline-registry ./semconv-dev-1.28.0 \
  --diff-format yaml \
  --output diff_v1.28.0_v1.38.0 \
  --v2
```

これは、バージョン間の変更点を要約した機械可読な出力を次のように生成します。

```yaml
schema_url: https://opentelemetry.io/schemas/semconv/1.39.0
registry:
  attribute_changes:
  - name: system.memory.linux.slab.state
    type: added
  - new_name: rpc.response.status_code
    old_name: rpc.connect_rpc.error_code
    type: renamed
...
```

このdiffスキーマは、JSON schemaとして正式に文書化されています。
[概要](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-schemas.md#diff-schema)と[完全なスキーマ](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv.diff.v2.json)を参照してください。

<details>

<summary>（Weaverでサポートされる）任意の2つのバージョン間の差分の計算は、比較的低コストです。</summary>

データがすでにローカルで利用可能であると仮定した場合、最近のノートパソコンで`weaver`を直接実行すると約100ミリ秒、`docker`経由では約1秒かかります。

これには現在、ソーススキーマの展開、読み込み、検証、解決にかかる時間が含まれており、resolvedレジストリを活用することでさらに最適化できます。

</details>

#### 選択肢3: 将来的にdiffを公開する {#migration-option-3-publish-diff-in-the-future}

将来的には、フィードバックと需要に基づいて、diffの公開に戻ることもできます。

その時点で、diff生成を可能にするために`weaver registry package`を更新できます。

```bash
weaver registry package --include-diff --resolved-registry-uri <url>
```

そして、`diff_uri`フィールドを含むように公開用manifestファイルフォーマットを拡張することを検討できます。

これは非破壊的な形で行うことができます。

### ドキュメントとコード生成 {#documentation-and-code-generation}

現在のコードおよびドキュメント生成ツールはスキーマv1を使用しています。
OTelのコード生成スクリプトの大部分が引き続きこのフォーマットを使用する間、Weaverはこのフォーマットのサポートを継続します。

さらに、Weaverはスキーマv2へのオプトインを可能にします。
その場合、コードおよびドキュメント生成は[materialized resolved schema v2](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-schemas.md#materialized-resolved-schema)を受け取ります。

v2への移行には、Jinja2テンプレートとWeaverの設定ファイルへの小さな変更が伴います。
移行手順とレシピは文書化される予定です。
エンドユーザーに影響を与える生成済みドキュメントやアーティファクトへの影響はないはずです。

## 先行技術と代替技術 {#prior-art-and-alternatives}

現在の最新状況については、[テレメトリースキーマ](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.54.0/specification/schemas/README.md)を参照してください。

現在（v1）のdefinitionスキーマについては[セマンティック規約のYAMLスキーマ](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md)を、使用方法の詳細については[Weaverのドキュメント](https://github.com/open-telemetry/weaver?tab=readme-ov-file#usage)を参照してください。

## 未解決の疑問 {#open-questions}

### スキーマ変換の今後の発展 {#schema-transformations-evolution}

HTTP、データベース、コードの各規約を全面的に見直した安定化の取り組みの中で、私たちは次のようなさまざまな種類の変更を導入しました。

- 振る舞いの変更を伴う、あるいは伴わない属性名やメトリクス名の変更。
- 2つの属性を1つにマージしたり、既存の属性を分割したりすること。
- 特定のメトリクスやスパンへの属性の追加や削除。
- スパン名のテンプレート、エラー基準の変更、そしてカーディナリティの高さや機密性への懸念からの属性のオプトイン化。

振る舞いの変更を伴わない単純な名前変更だけが、既存のスキーマ変換でカバーできたものでした。
私たちは、計装コードの中で新旧両方の規約を並行してサポートすることで移行に対応しました。

コミュニティは、いくつかの議論の中で、単純な名前変更を超えた変換の必要性を認識しています。
[weaver/450](https://github.com/open-telemetry/weaver/issues/450)や[repo:open-telemetry/opentelemetry-specification schema transformation](https://github.com/search?q=repo%3Aopen-telemetry%2Fopentelemetry-specification+schema+transformation&type=issues)がその例です。

> [!NOTE]
>
> 私たちは不安定な規約に対しては多くの破壊的変更を行っていますが、安定版の規約に対しては一切破壊的変更を行っていません。
> 安定版規約における破壊的変更のハードルの高さを踏まえると、マイナーバージョンの更新においてスキーマ変換が有用になる可能性は低いでしょう。
>
> スキーマ変換は、メジャーバージョンのアップグレードや、規約レジストリ間の変換（ECSとOTelの間、あるいは[OTelのgRPCとネイティブのgRPC規約の間](https://github.com/open-telemetry/semantic-conventions/pull/3229)）において、大きな価値を提供できる可能性があります。

決めるべき設計上の判断や埋めるべきギャップは多くあります。

- 変換を記述するためにどのDSLを使うべきか（OTTL、SEL、新規に考案するなど）。
- 任意のバージョンへのアップグレードとダウングレードをどのように記述するか。
- セマンティック規約とテレメトリーに対して変換を検証するツール。

私たちはまだ広範な開発とフィードバックのサイクルを経ておらず、これらの問題をどう解決すべきかについての確信はまだありません。

### 規約はどこに属すべきか {#where-should-conventions-belong}

セマンティック規約のメンテナーは、一般的な基準について議論してきました。
複数の異なる計装で使用される規約（たとえば、複数の言語で実装されているデータベースドライバー）は中央の`semantic-conventions`リポジトリで文書化されるべき（SHOULD）である一方、コンポーネント固有の規約（たとえばKafkaクライアントのJMXメトリクス）はそれぞれのリポジトリに留まるべき（SHOULD）です。

この OTEP は、複数のレジストリをサポートする技術スタックを構築することに焦点を当てており、厳密な基準を定義することは目的ではありません。

### CollectorやCollector固有の計装の規約の粒度はどうあるべきか {#whats-the-granularity-for-collector-and-instrumentation-specific-conventions}

個々の計装ライブラリやOTel Collectorコンポーネントごとに規約を公開すべきでしょうか。

私たちは、コンポーネントごとではなくディストリビューションごとに規約を公開することを推奨しますが、ファーストパーティの計装は自身のライブラリのみに対する規約を公開してもかまいません（MAY）。

この OTEP は厳密なガイダンスを提供することを意図していません。

## プロトタイプ {#prototypes}

[セマンティック規約](https://github.com/open-telemetry/semantic-conventions/pull/2469)は、リリース準備のステップの中で次を行います。

- スキーマを解決する。
- manifestを生成する。
- TODO:
  - 安定版と開発版の両方を生成する。
  - SemConvのアーティファクトをGitHubリリースアセットとして（そしておそらくopentelemetry.io上にも）公開する。

[分散型規約の例](https://github.com/open-telemetry/opentelemetry-weaver-examples/pull/33)。
[スキーマ変換を実行するためのOTel Collectorのtransformprocessor設定の生成](https://github.com/open-telemetry/opentelemetry-weaver-examples/pull/36)。

## 将来の可能性 {#future-possibilities}

1. リリース時に、各スキーマファミリーの下に`latest`バージョンを公開します - たとえば`https://opentelemetry.io/schemas/semconv/latest`や`https://opentelemetry.io/schemas/semconv-dev/latest`です。
   これは計装やアプリケーションコードで使用されるべきではありませんが、利用者が最新のスキーマ（バージョンと内容）を知るために活用できます。

2. 私たちはこれまでOTelのスキーマをopentelemetry.io上で提供してきましたが、GitHubリリースアセットからもアーティファクトを提供することを提案しています。
   需要が大幅に高まった場合には、スケールや信頼性の要件をサポートするために他の配布オプションを検討する必要があるでしょう。
</content>