文档 Grafana Alloy 参考 组件 otelcol otelcol.connector.spanmetrics

otelcol.connector.spanmetrics

otelcol.connector.spanmetrics 接收来自其他 otelcol 组件的 span 数据，并从 span 中聚合请求、错误和持续时间 (R.E.D) OpenTelemetry 指标。

• 请求计数计算为每个唯一维度集（包括错误）中看到的 span 数量。如果用户希望仅查看 service.name 和 span.name 上的调用计数，则可以聚合多个指标。

  请求使用 calls 指标进行跟踪，其中 status.code 数据点属性设置为 Ok。

  复制

  calls { service.name="shipping", span.name="get_shipping/{shippingId}", span.kind="SERVER", status.code="Ok" }

• 错误计数是从状态代码为 Error 的 span 数量计算得出的。

  错误使用 calls 指标进行跟踪，其中 status.code 数据点属性设置为 Error。

  复制

  calls { service.name="shipping", span.name="get_shipping/{shippingId}, span.kind="SERVER", status.code="Error" }

• 持续时间是根据 span 开始和结束时间之间的差异计算得出的，并插入到每个唯一维度集的相关持续时间直方图时间 buckets 中。

  Span 持续时间使用 duration 直方图指标进行跟踪。

  复制

  duration { service.name="shipping", span.name="get_shipping/{shippingId}", span.kind="SERVER", status.code="Ok" }

可以通过为多个 otelcol.connector.spanmetrics 组件赋予不同的标签来指定它们。

用法

alloy 复制

otelcol.connector.spanmetrics "LABEL" {
  histogram {
    ...
  }

  output {
    metrics = [...]
  }
}

参数

otelcol.connector.spanmetrics 支持以下参数

调整 dimensions_cache_size 可以提高 Alloy 进程的内存使用率。

aggregation_temporality 支持的值为

• "CUMULATIVE"：指标在刷新后不会被重置。
• "DELTA"：指标在刷新后将被重置。

如果设置了 namespace，则生成的指标名称将添加 namespace. 前缀。

将 metrics_expiration 设置为 "0s" 意味着指标将永不过期。

resource_metrics_cache_size 主要与累积时效性相关。它有助于避免内存增加和指标时间戳重置不正确的问题。

metric_timestamp_cache_size 仅与增量时效性 span 指标相关。它控制用于跟踪指标上次刷新时间的缓存大小。当指标从缓存中逐出时，其下一个数据点将指示序列中的“重置”。从增量转换为累积的下游组件可以通过将累积计数器设置回 0 来处理这些重置。

resource_metrics_key_attributes 可用于避免资源属性可能在服务重启时发生更改，从而导致指标计数器中断（和重复）的情况。资源不需要拥有所有属性。该列表必须包含足够的属性以正确识别唯一资源，否则可能会有从多个服务和 span 聚合数据的风险。例如：["service.name", "telemetry.sdk.language", "telemetry.sdk.name"]。

块

在 otelcol.connector.spanmetrics 的定义中支持以下块

必须指定 “exponential” 或 “explicit” 块之一

• 不允许同时指定 “exponential” 和 “explicit” 块。
• 不允许既不指定 “exponential” 也不指定 “explicit” 块。

dimension 块

dimension 块配置除了默认维度之外要添加的维度。

默认维度是

• service.name
• span.name
• span.kind
• status.code

默认维度始终添加。如果未指定其他维度，则只会添加默认维度。

支持以下属性

otelcol.connector.spanmetrics 将在 span 的属性集合中查找 name 属性。如果未找到，将检查资源属性。

如果 span 和资源属性中都缺少该属性

• 如果未设置 default，则将省略维度。
• 如果设置了 default，则将添加维度，并且其值将设置为 default 的值。

events 块

events 块配置 events 指标，该指标跟踪 span 事件。

支持以下属性

如果 enabled 设置为 true，则至少需要一个 dimension 块。

histogram 块

histogram 块配置从 span 持续时间派生的直方图。

支持以下属性

unit 支持的值为

• "ms"：毫秒
• "s"：秒

exponential 块

exponential 块配置具有指数 buckets 的直方图。

支持以下属性

explicit 块

explicit 块配置具有显式 buckets 的直方图。

支持以下属性

exemplars 块

exemplars 块配置如何将 exemplars 附加到直方图。

支持以下属性

max_per_data_point 可以帮助减少内存消耗。

output 块

output 块配置一组组件以将生成的遥测数据转发到。

支持以下参数

您必须指定 output 块，但其所有参数都是可选的。默认情况下，遥测数据将被丢弃。相应地配置 metrics 参数以将遥测数据发送到其他组件。

debug_metrics 块

debug_metrics 块配置此组件生成的用于监控其状态的指标。

支持以下参数

disable_high_cardinality_metrics 是 Grafana Alloy 等效于 OpenTelemetry Collector 中的 telemetry.disableHighCardinalityMetrics 功能门。它删除可能导致高基数指标的属性。例如，HTTP 和 gRPC 连接指标中包含 IP 地址和端口号的属性将被删除。

level 是 Alloy 等效于 OpenTelemetry Collector 中的 telemetry.metrics.level 功能门。可能的值为 "none"、"basic"、"normal" 和 "detailed"。

导出字段

以下字段已导出，可以被其他组件引用

input 接受 otelcol.Consumer 链路追踪遥测数据。它不接受指标和日志。

资源属性处理

otelcol.connector.spanmetrics 是一个 OTLP 原生组件。因此，它的目标是保留 span 的资源属性。

1. 例如，假设有两个传入的资源 span，它们具有相同的 service.name 和 k8s.pod.name 资源属性。

   两个传入 span 的 JSON 示例。

2. otelcol.connector.spanmetrics 将通过将传入的 service.name 和 k8s.pod.name 资源属性附加到输出指标资源来保留它们。只会创建一个指标资源，因为两个 span 资源都具有相同的资源属性。

   一个输出指标资源的 JSON 示例。

3. 现在假设 otelcol.connector.spanmetrics 接收到两个传入的资源 span，每个 span 的 k8s.pod.name 回溯属性的值都不同。

   两个传入 span 的 JSON 示例。

4. 为了保留所有资源属性的值，otelcol.connector.spanmetrics 将生成两个资源指标。每个资源指标的 k8s.pod.name 回溯属性的值都不同。这样，在生成指标期间，资源属性都不会丢失。

   两个输出指标资源的 JSON 示例。

组件健康状况

仅在给定无效配置时，otelcol.connector.spanmetrics 才会被报告为不健康。

调试信息

otelcol.connector.spanmetrics 不会暴露任何组件特定的调试信息。

示例

显式直方图和额外维度

在以下示例中，http.status_code 和 http.method 是在以下维度之上的额外维度

• service.name
• span.name
• span.kind
• status.code

alloy 复制

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    traces  = [otelcol.connector.spanmetrics.default.input]
  }
}

otelcol.connector.spanmetrics "default" {
  // Since a default is not provided, the http.status_code dimension will be omitted
  // if the span does not contain http.status_code.
  dimension {
    name = "http.status_code"
  }

  // If the span is missing http.method, the connector will insert
  // the http.method dimension with value 'GET'.
  dimension {
    name = "http.method"
    default = "GET"
  }

  dimensions_cache_size = 333

  aggregation_temporality = "DELTA"

  histogram {
    unit = "s"
    explicit {
      buckets = ["333ms", "777s", "999h"]
    }
  }

  // The period on which all metrics (whose dimension keys remain in cache) will be emitted.
  metrics_flush_interval = "33s"

  namespace = "test.namespace"

  output {
    metrics = [otelcol.exporter.otlp.production.input]
  }
}

otelcol.exporter.otlp "production" {
  client {
    endpoint = sys.env("OTLP_SERVER_ENDPOINT")
  }
}

通过 Prometheus 远程写入发送指标

生成的指标可以发送到与 Prometheus 兼容的数据库，例如 Grafana Mimir。但是，需要额外的步骤才能确保接收到所有指标样本。这是因为 otelcol.connector.spanmetrics 旨在保留资源属性在其输出的指标中。

不幸的是，Prometheus 数据模型没有资源属性的概念。这意味着，如果 otelcol.connector.spanmetrics 输出具有相同指标属性但资源属性不同的指标，则 otelcol.exporter.prometheus 将把指标转换为相同的指标序列。这个问题可以通过执行以下任一操作来解决：

• 推荐方法：在 otelcol.connector.spanmetrics 之前，从传入的 span 中删除 otelcol.connector.spanmetrics 不需要的所有资源属性。

  删除不必要的资源属性的配置示例。

• 或者，在 otelcol.connector.spanmetrics 之后，将每个资源属性复制为指标数据点属性。这样做的好处是资源属性将作为指标标签可见。但是，指标的 基数 可能会高得多，这可能会增加存储和查询它们的成本。以下示例使用 merge_maps OTTL 函数。

  将所有资源属性添加为指标数据点属性的配置示例。

如果资源属性未以任一上述方式处理，则 prometheus.remote_write 可能会记录如下错误：the sample has been rejected because another sample with the same timestamp, but a different value, has already been ingested (err-mimir-sample-duplicate-timestamp) (样本已被拒绝，因为具有相同时间戳但不同值的另一个样本已被摄取)。

兼容组件

otelcol.connector.spanmetrics 可以接受来自以下组件的参数

• 导出 OpenTelemetry otelcol.Consumer 的组件

otelcol.connector.spanmetrics 具有可以被以下组件使用的导出

• 消费 OpenTelemetry otelcol.Consumer 的组件