Schema 文件格式 1.0.0

状态: 开发中

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

文件结构

Schema 文件的结构如下

# Defines the file format. MUST be set to 1.0.0.
file_format: 1.0.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”转换类似。此外，还可以选择性地指定转换应应用于的 span。结构如下

    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 事件数据类型的转换。它必须包含一个名为“changes”的子部分，该子部分定义了要应用于将事件从上一个版本转换为当前版本的操作序列。

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

rename_events 转换

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

    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”转换类似。此外，还可以选择性地指定转换应应用于的 span 和事件（如果指定，则必须同时满足这两个可选条件才能应用转换）。结构如下

    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”的子部分，该子部分定义了要应用于将 metric 从上一个版本转换为当前版本的操作序列。

“metrics”部分支持两种转换：“rename_metrics”和“rename_attributes”。

rename_metrics 转换

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

    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.

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。（注意，版本号不是整数的连续。将自然数 1 加到版本号的概念是“此 Schema 系列中定义的下一个较新版本号”的占位符。）

特定版本 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.0.0”。对此数字的任何更改都必须遵循 OTEP 流程并在规范中发布。

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

随着 Schema 文件格式随时间的推移而演变，格式版本号应根据以下规则进行更改

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

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

  • 如果以向后兼容的方式向文件格式添加新设置，应增加 MINOR 号。“向后兼容”在此上下文中意味着，了解新 MINOR 号的使用者可以消耗特定 MINOR 版本号的文件或任何低于该 MINOR 版本号的文件，前提是 MAJOR 版本号相同。通常，这意味着文件格式中添加的设置是可选的，并且设置的默认值与前一个文件格式版本的行为匹配。

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

  • 如果文件格式以不兼容的方式更改，应增加 MAJOR 号。例如，在“changes”部分中添加新的转换类型是不可兼容的更改，因为它不能被现有的 Schema 转换逻辑忽略，因此此类更改将需要新的 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.0.0.
file_format: 1.0.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

    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.