Schema 文件格式 1.1.0

状态: 开发中

Schema 文件是一个 YAML 文件，描述特定版本的 schema。它定义了可用于将表示为任何其他兼容的旧版本同一 schema 系列的遥测数据转换为此 schema 版本的转换。

文件结构

Schema 文件的结构如下

# Defines the file format. MUST be set to 1.1.0.
file_format: 1.1.0

# The Schema URL that this file is published at. The version number in the URL
# MUST match the highest version number in the "versions" section below.
# Note: the schema version number in the URL is not related in any way to
# the file_format setting above.
schema_url: /schemas/1.2.0

# Definitions for each schema version in this family.
# Note: the ordering of versions is defined according to semver
# version number ordering rules.
versions:
  <version_number_last>:
    # definitions for this version. See details below.

  <version_number_previous>:
    # definitions for previous version
    ...
  <version_number_first>:
    # Defines the first version.

每个 <version_number> 部分具有以下结构

  <version_number>:
    all:
      changes:
        # sequence of transformations.

    resources:
      changes:
        # sequence of transformations.

    spans:
      changes:
        # sequence of transformations.

    span_events:
      changes:
        # sequence of transformations.

    metrics:
      changes:
        # sequence of transformations.

    logs:
      changes:
        # sequence of transformations.

每个版本定义下有 6 个子部分：“all”、“resources”、“spans”、“span_events”、“metrics”、“logs”。列表中最后的 5 个子部分包含仅适用于相应遥测数据类型的定义。“all”部分包含适用于所有类型遥测数据的定义。

下面我们将详细描述每个部分。

all 部分

Schema 文件中的“all”部分定义了转换。它必须包含一个名为“changes”的子部分，该子部分定义了从前一个版本到此版本的属性如何重命名。

“changes”部分是转换序列。对于“all”部分，只支持一种转换：“rename_attributes”转换。

“rename_attributes”转换需要一个键/值对的映射，其中键是前一个版本中使用的属性的旧名称，值是从此版本开始的属性的新名称。结构如下

    all:
      changes:
        - rename_attributes:
            attribute_map:
              # map of key/values.

“all”部分中的转换适用于以下遥测数据：资源属性、span 属性、span 事件属性、log 属性、metric 属性。

重要提示：在从前一个版本转换为当前版本时，首先执行“all”部分中的转换序列。然后，应用特定部分（“resources”、“spans”、“span_events”、“metrics”或“logs”）中与要转换的数据类型相对应的转换。

请注意，“rename_attributes”转换在大多数情况下是可逆的。可以向后应用它，以便遥测数据从当前版本转换为前一个版本。唯一的例外是当前一个版本中的 2 个或更多不同的属性被重命名为新版本中的同一属性时。在这种情况下，反向转换是不可能的，因为它会产生歧义。当反向转换不可行时，这被认为是不兼容的更改。在这种情况下，Schema 的 MAJOR 版本号在*/新版本中应增加。

resources 部分

“resources”部分的结构与“all”部分非常相似。与“all”部分一样，“resources”部分中的转换可能只包含“rename_attributes”转换。

与“all”部分唯一的区别是此转换仅适用于 Resource 数据类型。

结构如下

    resources:
      changes:
        - rename_attributes:
            attribute_map:
              # map of key/values. The keys are the old attribute name used
              # the previous version, the values are the new attribute name
              # starting from this version.

spans 部分

Schema 文件中的“spans”部分定义了仅适用于 Span 数据类型的转换。它必须包含一个名为“changes”的子部分，该子部分定义了从前一个版本到此版本转换 Span 所需应用的一系列操作。

“span”部分支持一种转换：“rename_attributes”。

rename_attributes 转换

这与“all”和“resource”部分支持的“rename_attributes”转换类似。此外，还可以选择性地指定转换应应用于的 spans。结构如下

    spans:
      changes:
        - rename_attributes:
            attribute_map:
              # map of key/values. The keys are the old attribute name used
              # in the previous version, the values are the new attribute name
              # starting from this version.

            apply_to_spans:
              # Optional. If it is missing the transformation is applied
              # to all spans. If it is present the transformation is applied
              # only to the spans with the name that is found in the sequence
              # specified below.

span_events 部分

Schema 文件中的“spans_events”部分定义了仅适用于 Span 的 Event 数据类型的转换。它必须包含一个名为“changes”的子部分，该子部分定义了从前一个版本到此版本转换事件所需应用的一系列操作。

“spans_events”部分支持两种转换：“rename_events”和“rename_attributes”。

rename_events 转换

此转换允许更改事件名称。它应用于所有事件，或仅应用于具有指定名称的 spans 的事件。结构如下

    span_events:
      changes:
        - rename_events:
            name_map:
              # The keys are old event name used in the previous version, the
              # values are the new event name starting from this version.

rename_attributes 转换

这与“all”和“resource”部分支持的“rename_attributes”转换类似。此外，还可以选择性地指定转换应应用于的 spans 和 events（如果指定，则必须同时满足这两个可选条件，转换才适用）。结构如下

    span_events:
      changes:
        - rename_attributes:
            attribute_map:
              # map of key/values. The keys are the old attribute name used
              # in the previous version, the values are the new attribute name
              # starting from this version.

            apply_to_spans:
              # Optional span names to apply to. If empty applies to all spans.

            apply_to_events:
              # Optional event names to apply to. If empty applies to all events.

metrics 部分

Schema 文件中的“metrics”部分定义了仅适用于 Metric 数据类型的转换。它必须包含一个名为“changes”的子部分，该子部分定义了从前一个版本到此版本转换 metrics 所需应用的一系列操作。

“metrics”部分支持三种转换：“rename_metrics”、“rename_attributes”和“split”。

rename_metrics 转换

此转换允许更改 metric 名称。它应用于所有 metrics。结构如下

    metrics:
      changes:
        - rename_metrics:
            # map of key/values. The keys are the old metric name used
            # in the previous version, the values are the new metric name
            # starting from this version.

rename_attributes 转换

这与“span”部分支持的“rename_attributes”转换类似。结构如下

    metrics:
      changes:
        - rename_attributes:
            attribute_map:
              # map of key/values. The keys are the old attribute name used
              # in the previous version, the values are the new attribute name
              # starting from this version.

            apply_to_metrics:
              # Optional. If it is missing the transformation is applied
              # to all metrics. If it is present the transformation is applied
              # only to the metrics with the name that is found in the sequence
              # specified below.

split 转换

此转换将一个 metric 分割成多个 metric 并移除一个属性。结构如下

    metrics:
      changes:
        - split:
            # Name of old metric to split.
            apply_to_metric:
            # Name of attribute in the old metric to use for splitting. The attribute will be
            # eliminated, the new metric will not have it.
            by_attribute:
            # Names of new metrics to create, one for each possible value of attribute.
            metrics_from_attributes:
              # map of key/values. The keys are the new metric name starting from this
              # version, the values are the old attribute value used in the previous version.

logs 部分

Schema 文件中的“logs”部分定义了仅适用于 Log Record 数据类型的转换。它必须包含一个名为“changes”的子部分，该子部分定义了从前一个版本到此版本转换 logs 所需应用的一系列操作。

“logs”部分支持一种转换：“rename_attributes”。

rename_attributes 转换

这与“spans”部分支持的“rename_attributes”转换类似。结构如下

    logs:
      changes:
        - rename_attributes:
            attribute_map:
              # map of key/values. The keys are the old attribute name used
              # the previous version, the values are the new attribute name
              # starting from this version.

转换顺序

在从旧版本 X 转换为同一 schema 系列的新版本 Y 时，将在每个版本中指定的转换（在 [X..Y] 范围内）一个接一个地应用，即，我们首先从 X 转换为 X+1，然后从 X+1 转换为 X+2，...，Y-2 转换为 Y-1，Y-1 转换为 Y。（注意，版本号不是整数的连续体。“adding a natural number 1 to the version number”的概念是“next newer version number that is defined for this schema family”这一短语的占位符。）

为特定版本 X 列出的转换描述了自同一 schema 系列中紧接版本 X 的前一个版本以来发生的变化。这些转换列在 6 个部分中：“all”、“resources”、“spans”、“span_events”、“metrics”、“logs”。转换应用的顺序如下

  • “all”部分中的转换始终首先应用，然后是其他 5 个部分中的任何转换。

  • “spans”部分中的转换在“span_events”部分中的转换之前应用。

  • 在其余部分（“resources”、“metrics”、“logs”）中的转换相对于彼此或其他部分（如“spans”）应用的顺序未定义（因为不存在相互依赖性，所以顺序无关紧要）。

在这些 6 个部分的每个特定部分的“changes”子部分中，转换序列按其在 schema 文件中列出的顺序应用，从上到下。

当反向转换时，从较新版本 Y 到较旧版本 X，上述转换顺序完全相反，每个单独的转换也执行反向转换。

Schema 文件格式编号

Schema 文件中的“file_format”设置指定了文件的格式版本。格式版本遵循 MAJOR.MINOR.PATCH 格式，类似于 semver 2.0。

“file_format”设置用于文件的使用者，以便他们知道自己是否能够解释文件内容。

此设置的当前值为“1.1.0”。对此数字的任何更改都必须在规范中发布。

当前 schema 文件格式允许表示有限的遥测数据转换集。我们预计未来可能会支持更多类型的转换，或者可能需要在 schema 文件中记录其他附加信息。

随着 schema 文件格式随时间演变，格式版本号应根据以下规则更改

  • 当文件格式发生变化但不会影响现有文件使用者时，应增加 PATCH 号。例如，在 schema 文件中添加一个完全不影响现有部分且不影响任何现有 schema 功能的新部分，可以通过只增加 PATCH 号来实现。此方法仅在文件中的新设置可以被所有现有处理逻辑完全且安全地忽略时有效。

    例如，添加一个描述 schema 完整状态的新部分，对仅关心“changes”部分的现有使用者没有影响（除非我们明确定义新部分的语义，使其在处理 schema 更改时需要考虑）。因此，添加这样一个新部分可以使用 PATCH 号增加。

  • 如果以向后兼容的方式添加了新设置，则应增加 MINOR 号。“向后兼容”在此上下文中意味着，了解新 MINOR 号的消费者可以读取特定 MINOR 版本号或任何低于该版本号的 MINOR 版本号的文件，前提是 MAJOR 版本号相同。例如，这可能发生在

    • 添加了新的转换类型。

    • 向现有转换添加了新设置。新设置是可选的，并且设置的默认值与先前文件格式版本的行为匹配。

    注意：不存在基于 MINOR 版本号的“向前兼容”。支持读取到特定 MINOR 版本号的消费者不应尝试使用更高 MINOR 版本号的文件。

  • 如果文件格式以不兼容的方式更改，则应增加 MAJOR 号。这意味着文件使用者需要以不同于先前 MAJOR 版本的方式解析或解释文件。

相应地

  • Schema 文件的消费者不应尝试解释 schema 文件，如果 MAJOR 版本号与消费者支持的版本不同（更高或更低）。

  • Schema 文件的消费者不应尝试解释 schema 文件，如果 MINOR 版本号高于消费者支持的版本。

  • 消费者可以忽略 PATCH 号。

为了说明这一点，我们举例说明

文件格式版本消费者的预期版本消费者可以读取吗？
1.0.01.0.0是
1.0.x1.0.y是，对于任何 x 和 y。
1.a.x1.b.x如果 a<b 则为是，否则为否。
2.0.01.x.y否

附录 A. 示例 Schema 文件

# Defines the file format. MUST be set to 1.1.0.
file_format: 1.1.0

# The Schema URL that this file is published at. The version number in the URL
# MUST match the highest version number in the "versions" section below.
# Note: the schema version number in the URL is not related in any way to
# the file_format setting above.
schema_url: /schemas/1.1.0

# Definitions for each schema version in this family.
# Note: the ordering of versions is defined according to semver
# version number ordering rules.
versions:
  1.1.0:
    # Definitions for version 1.1.0.
    all:
      # Definitions that apply to all data types.
      changes:
        # Transformations to apply when converting from version 1.0.0 to 1.1.0.
        - rename_attributes:
            # map of key/values. The keys are the old attribute name used
            # the previous version, the values are the new attribute name
            # starting from this version.
            # Rename k8s.* to 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:
      # Definitions that apply to Resource data type.
      changes:
        - rename_attributes:
            telemetry.auto.version: telemetry.auto_instr.version

    spans:
      # Definitions that apply to Span data type.
      changes:
        - rename_attributes:
            attribute_map:
              # map of key/values. The keys are the old attribute name used
              # in the previous version, the values are the new attribute name
              # starting from this version.
              peer.service: peer.service.name
            apply_to_spans:
              # apply only to spans named "HTTP GET"
              - "HTTP GET"

    span_events:
      # Definitions that apply to Span Event data type.
      changes:
        - rename_events:
            # The keys are old event name used in the previous version, the
            # values are the new event name starting from this version.
            name_map: {stacktrace: stack_trace}

        - rename_attributes:
            attribute_map:
              peer.service: peer.service.name
            apply_to_events:
              # Optional event names to apply to. If empty applies to all events.
              - exception.stack_trace

    metrics:
      # Definitions that apply to Metric data type.
      changes:
        - rename_metrics:
            # map of key/values. The keys are the old metric name used
            # in the previous version, the values are the new metric name
            # starting from this version.
            container.cpu.usage.total: cpu.usage.total
            container.memory.usage.max: memory.usage.max

        - rename_attributes:
            attribute_map:
              status: state
            apply_to_metrics:
              # Optional. If it is missing the transformation is applied
              # to all metrics. If it is present the transformation is applied
              # only to the metrics with the name that is found in the sequence
              # specified below.
              - system.cpu.utilization
              - system.memory.usage
              - system.memory.utilization
              - system.paging.usage

        - split:
            # Example from the change done by https://github.com/open-telemetry/opentelemetry-specification/pull/2617
            # Name of old metric to split.
            apply_to_metric: system.paging.operations
            # Name of attribute in the old metric to use for splitting. The attribute will be
            # eliminated, the new metric will not have it.
            by_attribute: direction
            # Names of new metrics to create, one for each possible value of attribute.
            metrics_from_attributes:
              # If "direction" attribute equals "in" create a new metric called "system.paging.operations.in".
              system.paging.operations.in: in
              # If "direction" attribute equals "out" create a new metric called "system.paging.operations.out".
              system.paging.operations.out: out

    logs:
      # Definitions that apply to LogRecord data type.
      changes:
        - rename_attributes:
            attribute_map:
              process.executable_name: process.executable.name

  1.0.0:
    # First version of this schema family.