> Source: https://www.ymotongpoo.com/works/otel-specs-ja/spec/schemas/file_format_v1.0.0/


**ステータス**: [Development](/works/otel-specs-ja/spec/document-status/)

スキーマファイルは、特定のバージョンのスキーマを記述するYAMLファイルです。同じスキーマファミリーの他の古い互換バージョンで表現されたテレメトリーデータを、このスキーマバージョンへ変換するために使える変換を定義します。

## ファイル構造

スキーマファイルの構造を以下に示します。

```yaml
# ファイル形式を定義します。1.0.0にMUST設定するものとします。
file_format: 1.0.0

# このファイルが公開されるSchema URL。このURLのバージョン番号は、以下の
# "versions"セクションの最も高いバージョン番号にMUST一致するものとします。
# 注記：URL内のスキーマバージョン番号は、上記のfile_format設定とは
# まったく関係ありません。
schema_url: https://opentelemetry.io/schemas/1.2.0

# このファミリーに含まれる各スキーマバージョンの定義。
# 注記：バージョンの順序は、semverのバージョン番号順序付け規則に
# 従って定義されます。
versions:
  <version_number_last>:
    # このバージョンの定義。詳細は以下を参照。

  <version_number_previous>:
    # 前のバージョンの定義
    ...
  <version_number_first>:
    # 最初のバージョンを定義します。
```

各`<version_number>`セクションは、以下の構造を持ちます。

```yaml
  <version_number>:
    all:
      changes:
        # 変換の並び。

    resources:
      changes:
        # 変換の並び。

    spans:
      changes:
        # 変換の並び。

    span_events:
      changes:
        # 変換の並び。

    metrics:
      changes:
        # 変換の並び。

    logs:
      changes:
        # 変換の並び。
```

各バージョン定義の下には、"all"、"resources"、"spans"、"span_events"、"metrics"、"logs"の6つのサブセクションがあります。この一覧の最後の5つのサブセクションには、対応するテレメトリーデータ種別のみに適用される定義が含まれます。"all"セクションには、すべての種別のテレメトリーデータに適用される定義が含まれます。

以下では、各セクションを詳しく説明します。

### allセクション

スキーマファイルの"all"セクションは変換を定義します。このセクションは、属性が前のバージョンからこのバージョンへどのように名前変更されたかを定義する、"changes"という名前のサブセクションをMUST含むものとします。

"changes"セクションは変換の並びです。"all"セクションでサポートされる変換は、"rename_attributes"変換のみです。

"rename_attributes"変換には、キーと値の組のマップが必要です。キーは前のバージョンで使われていた属性の古い名前、値はこのバージョンから始まる新しい属性名です。構造を以下に示します。

```yaml
    all:
      changes:
        - rename_attributes:
            attribute_map:
              # キーと値の組のマップ。
```

"all"セクションの変換は、以下のテレメトリーデータに適用されます。リソース属性、スパン属性、スパンイベント属性、ログ属性、メトリック属性。

重要：前のバージョンから現在のバージョンへ変換する場合、"all"セクションの変換の並びが最初に実行されます。その後、変換対象のデータ種別に対応する特定のセクション（"resources"、"spans"、"span_events"、"metrics"、"logs"）の変換が適用されます。

"rename_attributes"変換は、多くの場合可逆である点に注意してください。逆方向に適用し、テレメトリーデータをこのバージョンから前のバージョンへ変換することも可能です。唯一の例外は、前のバージョンの2つ以上の異なる属性が新しいバージョンで同じ属性に名前変更される場合です。この場合、逆変換は曖昧になるため不可能です。逆変換が不可能な場合、それは互換性のない変更とみなされます。この場合、スキーマのMAJORバージョン番号は新しいバージョンでSHOULD増加するものとします。

### resourcesセクション

"resources"セクションは、その構造が"all"セクションと非常に似ています。"all"セクションと同様に、"resources"セクションの変換には"rename_attributes"変換のみを含められます。

"all"セクションとの唯一の違いは、この変換がResourceデータ種別にのみ適用される点です。

構造を以下に示します。

```yaml
    resources:
      changes:
        - rename_attributes:
            attribute_map:
              # キーと値の組のマップ。キーは前のバージョンで使われていた
              # 古い属性名、値はこのバージョンから始まる新しい属性名です。
```

### spansセクション

スキーマファイルの"spans"セクションは、Spanデータ種別にのみ適用される変換を定義します。前のバージョンからこのバージョンへSpanを変換するために適用するアクションの並びを定義する、"changes"という名前のサブセクションをMUST含むものとします。

"span"セクションでサポートされる変換は、"rename_attributes"の1つです。

#### rename_attributes変換

これは、"all"セクションと"resource"セクションでサポートされている"rename_attributes"変換に似ています。加えて、変換を適用する対象のスパンを任意で指定することもできます。構造を以下に示します。

```yaml
    spans:
      changes:
        - rename_attributes:
            attribute_map:
              # キーと値の組のマップ。キーは前のバージョンで使われていた
              # 古い属性名、値はこのバージョンから始まる新しい属性名です。

            apply_to_spans:
              # 任意。指定がない場合、変換はすべてのスパンに適用されます。
              # 指定がある場合、変換は以下で指定される並びに見つかった名前を
              # 持つスパンにのみ適用されます。
```

### span_eventsセクション

スキーマファイルの"spans_events"セクションは、Spanの Eventデータ種別にのみ適用される変換を定義します。前のバージョンからこのバージョンへイベントを変換するために適用するアクションの並びを定義する、"changes"という名前のサブセクションをMUST含むものとします。

"spans_events"セクションでサポートされる変換は、"rename_events"と"rename_attributes"の2つです。

#### rename_events変換

この変換により、イベント名を変更できます。すべてのイベント、または指定された名前を持つスパンのイベントのみに適用されます。構造を以下に示します。

```yaml
    span_events:
      changes:
        - rename_events:
            name_map:
              # キーは前のバージョンで使われていた古いイベント名、値は
              # このバージョンから始まる新しいイベント名です。
```

#### rename_attributes変換

これは、"all"セクションと"resource"セクションでサポートされている"rename_attributes"変換に似ています。加えて、変換を適用する対象のスパンとイベントを任意で指定することもできます（指定する場合、両方の任意の条件が一致する必要があります）。構造を以下に示します。

```yaml
    span_events:
      changes:
        - rename_attributes:
            attribute_map:
              # キーと値の組のマップ。キーは前のバージョンで使われていた
              # 古い属性名、値はこのバージョンから始まる新しい属性名です。

            apply_to_spans:
              # 任意の適用対象スパン名。空の場合はすべてのスパンに適用されます。

            apply_to_events:
              # 任意の適用対象イベント名。空の場合はすべてのイベントに適用されます。
```

### metricsセクション

スキーマファイルの"metrics"セクションは、Metricデータ種別にのみ適用される変換を定義します。前のバージョンからこのバージョンへメトリクスを変換するために適用するアクションの並びを定義する、"changes"という名前のサブセクションをMUST含むものとします。

"metrics"セクションでサポートされる変換は、"rename_metrics"と"rename_attributes"の2つです。

#### rename_metrics変換

この変換により、メトリック名を変更できます。すべてのメトリクスに適用されます。構造を以下に示します。

```yaml
    metrics:
      changes:
        - rename_metrics:
            # キーと値の組のマップ。キーは前のバージョンで使われていた
            # 古いメトリック名、値はこのバージョンから始まる新しい
            # メトリック名です。
```

#### rename_attributes変換

これは、"span"セクションでサポートされている"rename_attributes"変換に似ています。構造を以下に示します。

```yaml
    metrics:
      changes:
        - rename_attributes:
            attribute_map:
              # キーと値の組のマップ。キーは前のバージョンで使われていた
              # 古い属性名、値はこのバージョンから始まる新しい属性名です。

            apply_to_metrics:
              # 任意。指定がない場合、変換はすべてのメトリクスに適用されます。
              # 指定がある場合、変換は以下で指定される並びに見つかった名前を
              # 持つメトリクスにのみ適用されます。
```

### logsセクション

スキーマファイルの"logs"セクションは、Log Recordデータ種別にのみ適用される変換を定義します。前のバージョンからこのバージョンへログを変換するために適用するアクションの並びを定義する、"changes"という名前のサブセクションをMUST含むものとします。

"logs"セクションでサポートされる変換は、"rename_attributes"の1つです。

#### rename_attributes変換

これは、"spans"セクションでサポートされている"rename_attributes"変換に似ています。構造を以下に示します。

```yaml
    logs:
      changes:
        - rename_attributes:
            attribute_map:
              # キーと値の組のマップ。キーは前のバージョンで使われていた
              # 古い属性名、値はこのバージョンから始まる新しい属性名です。
```

### 変換の順序

同じスキーマファミリーに属する古いバージョンXから新しいバージョンYへスキーマを変換する場合、範囲[X..Y]の各バージョンで指定された変換が1つずつ適用されます。つまり、最初にXからX+1へ変換し、次にX+1からX+2へ、……、Y-2からY-1へ、Y-1からYへ変換します（注記：バージョン番号は整数の連続体ではありません。バージョン番号に自然数の1を加えるという考え方は、「このスキーマファミリーで定義されている、次に新しいバージョン番号」というフレーズのプレースホルダーです）。

特定のバージョンXについて列挙される変換は、同じスキーマファミリーに属し、バージョンXに先行するスキーマバージョン以降に発生した変更を記述します。これらの変換は、"all"、"resources"、"spans"、"span_events"、"metrics"、"logs"の6つのセクションに列挙されます。変換が適用される順序は以下のとおりです。

- "all"セクションの変換は、常に他の5つのセクションの変換より前に適用されます。

- "spans"セクションの変換は、"span_events"セクションの変換より前に適用されます。

- 残りのセクション（"resources"、"metrics"、"logs"）の変換が互いに対して、あるいは"spans"セクションに対してどの順序で適用されるかは定義されていません（相互依存がないため、順序は問題になりません）。

これら6つのセクションそれぞれの"changes"サブセクションでは、変換の並びは、スキーマファイルに列挙されている順序で上から下へ適用されます。

逆方向、つまり新しいバージョンYから古いバージョンXへ変換する場合、上記で列挙された変換の順序は正確に逆になり、個々の変換もそれぞれ逆方向の変換を実行します。

### スキーマファイル形式番号

スキーマファイルの"file_format"設定は、ファイルの形式バージョンを指定します。形式バージョンは、semver 2.0と同様のMAJOR.MINOR.PATCH形式に従います。

"file_format"設定は、ファイルの利用者がその内容を解釈できるかどうかを知るために使われます。

この設定の現在の値は"1.0.0"です。この番号への変更は、OTEPプロセスにMUST従い、仕様書でMUST公開されるものとします。

現在のスキーマファイル形式は、テレメトリーデータの変換のうち限られた集合のみを表現できます。私たちは、将来的にはより多くの種類の変換をサポートすることが望ましくなる、あるいはスキーマファイルに記録することが望ましい他の追加情報が出てくることを予期しています。

スキーマファイル形式が時間の経過とともに進化するにつれて、形式のバージョン番号は以下の規則に従ってSHOULD変更されるものとします。

- PATCH番号は、既存のファイルの利用者に影響を与えない形でファイル形式が変更される場合にSHOULD増加するものとします。例えば、既存のセクションに影響を与えず、既存のスキーマ機能にも影響を与えない、完全に新しいセクションをスキーマファイルに追加することは、PATCH番号のみの増加で行えます。このアプローチは、ファイル内の新しい設定が既存のすべての処理ロジックによって完全かつ安全に無視できる場合にのみ有効です。

  例えば、スキーマの全体の状態を記述する完全に新しいセクションを追加することは、"changes"セクションのみを気にする既存の利用者には影響を与えません（この新しいセクションのセマンティクスを、スキーマの変更を処理する際に*考慮する必要がある*ように明示的に定義しない限り）。そのため、このような新しいセクションの追加はPATCH番号の増加で行えます。

- MINOR番号は、後方互換な方法でファイル形式に新しい設定が追加される場合にSHOULD増加するものとします。この文脈における「後方互換」とは、新しいMINOR番号を認識している利用者が、MAJORバージョン番号が同じである限り、特定のMINORバージョン番号やそれより低い任意のMINORバージョン番号のファイルを利用できることを意味します。通常、これはファイル形式に追加される設定が任意であり、その設定のデフォルト値が前のファイル形式バージョンの動作に一致することを意味します。

  注記：MINORバージョン番号に基づく「前方互換性」は存在しません。特定のMINORバージョン番号までの読み取りをサポートする利用者は、より高いMINORバージョン番号を持つファイルを利用しようとしてはなりません（SHOULD NOT）。

- MAJOR番号は、ファイル形式が互換性のない方法で変更される場合にSHOULD増加するものとします。例えば、"changes"セクションに新しい変換の種類を追加することは、既存のスキーマ変換ロジックによって無視できないため互換性のない変更にあたり、そのような変更には新しいMAJOR番号が必要になります。

これに対応して、

- スキーマファイルの利用者は、MAJORバージョン番号が利用者のサポートするものと（高くても低くても）異なる場合、そのスキーマファイルを解釈しようとしてはなりません（SHOULD NOT）。

- スキーマファイルの利用者は、MINORバージョン番号が利用者のサポートするものより高い場合、そのスキーマファイルを解釈しようとしてはなりません（SHOULD NOT）。

- 利用者はPATCH番号を無視してもかまいません（MAY）。

これをいくつかの例で示します。

<table>
  <tr>
   <td><strong>ファイル形式バージョン</strong>
   </td>
   <td><strong>利用者が想定するバージョン</strong>
   </td>
   <td><strong>利用者は読み取れるか</strong>
   </td>
  </tr>
  <tr>
   <td>1.0.0
   </td>
   <td>1.0.0
   </td>
   <td>はい
   </td>
  </tr>
  <tr>
   <td>1.0.x
   </td>
   <td>1.0.y
   </td>
   <td>xとyのどの組み合わせでもはい。
   </td>
  </tr>
  <tr>
   <td>1.a.x
   </td>
   <td>1.b.x
   </td>
   <td>a&lt;bならはい、それ以外はいいえ。
   </td>
  </tr>
  <tr>
   <td>2.0.0
   </td>
   <td>1.x.y
   </td>
   <td>いいえ
   </td>
  </tr>
</table>

## 付録A. スキーマファイルの例

```yaml
# ファイル形式を定義します。1.0.0にMUST設定するものとします。
file_format: 1.0.0

# このファイルが公開されるSchema URL。このURLのバージョン番号は、以下の
# "versions"セクションの最も高いバージョン番号にMUST一致するものとします。
# 注記：URL内のスキーマバージョン番号は、上記のfile_format設定とは
# まったく関係ありません。
schema_url: https://opentelemetry.io/schemas/1.1.0

# このファミリーに含まれる各スキーマバージョンの定義。
# 注記：バージョンの順序は、semverのバージョン番号順序付け規則に
# 従って定義されます。
versions:
  1.1.0:
    # バージョン1.1.0の定義。
    all:
      # すべてのデータ種別に適用される定義。
      changes:
        # バージョン1.0.0から1.1.0へ変換する際に適用する変換。
        - rename_attributes:
            # キーと値の組のマップ。キーは前のバージョンで使われていた
            # 古い属性名、値はこのバージョンから始まる新しい属性名です。
            # k8s.*をkubernetes.*へ名前変更
            k8s.cluster.name: kubernetes.cluster.name
            k8s.namespace.name: kubernetes.namespace.name
            k8s.node.name: kubernetes.node.name
            k8s.node.uid: kubernetes.node.uid
            k8s.pod.name: kubernetes.pod.name
            k8s.pod.uid: kubernetes.pod.uid
            k8s.container.name: kubernetes.container.name
            k8s.replicaset.name: kubernetes.replicaset.name
            k8s.replicaset.uid: kubernetes.replicaset.uid
            k8s.cronjob.name: kubernetes.cronjob.name
            k8s.cronjob.uid: kubernetes.cronjob.uid
            k8s.job.name: kubernetes.job.name
            k8s.job.uid: kubernetes.job.uid
            k8s.statefulset.name: kubernetes.statefulset.name
            k8s.statefulset.uid: kubernetes.statefulset.uid
            k8s.daemonset.name: kubernetes.daemonset.name
            k8s.daemonset.uid: kubernetes.daemonset.uid
            k8s.deployment.name: kubernetes.deployment.name
            k8s.deployment.uid: kubernetes.deployment.uid

    resources:
      # Resourceデータ種別に適用される定義。
      changes:
        - rename_attributes:
            telemetry.auto.version: telemetry.auto_instr.version

    spans:
      # Spanデータ種別に適用される定義。
      changes:
        - rename_attributes:
            attribute_map:
              # キーと値の組のマップ。キーは前のバージョンで使われていた
              # 古い属性名、値はこのバージョンから始まる新しい属性名です。
              peer.service: peer.service.name
            apply_to_spans:
              # "HTTP GET"という名前のスパンにのみ適用
              - "HTTP GET"

    span_events:
      # Span Eventデータ種別に適用される定義。
      changes:
        - rename_events:
            # キーは前のバージョンで使われていた古いイベント名、値は
            # このバージョンから始まる新しいイベント名です。
            name_map: {stacktrace: stack_trace}

        - rename_attributes:
            attribute_map:
              peer.service: peer.service.name
            apply_to_events:
              # 任意の適用対象イベント名。空の場合はすべてのイベントに適用されます。
              - exception.stack_trace

    metrics:
      # Metricデータ種別に適用される定義。
      changes:
        - rename_metrics:
            # キーと値の組のマップ。キーは前のバージョンで使われていた
            # 古いメトリック名、値はこのバージョンから始まる新しい
            # メトリック名です。
            container.cpu.usage.total: cpu.usage.total
            container.memory.usage.max: memory.usage.max

        - rename_attributes:
            attribute_map:
              status: state
            apply_to_metrics:
              # 任意。指定がない場合、変換はすべてのメトリクスに適用されます。
              # 指定がある場合、変換は以下で指定される並びに見つかった名前を
              # 持つメトリクスにのみ適用されます。
              - system.cpu.utilization
              - system.memory.usage
              - system.memory.utilization
              - system.paging.usage

    logs:
      # LogRecordデータ種別に適用される定義。
      changes:
        - rename_attributes:
            attribute_map:
              process.executable_name: process.executable.name

  1.0.0:
    # このスキーマファミリーの最初のバージョン。
```