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

otelcol.connector.servicegraph

otelcol.connector.servicegraph 接受来自其他 otelcol 组件的 span 数据，并输出代表系统中各种服务之间关系的指标。一个指标代表服务图中的一条边。这些指标随后可以由数据可视化应用（例如 Grafana）用于绘制服务图。

注意：otelcol.connector.servicegraph 是上游 OpenTelemetry Collector servicegraph 连接器的封装。如有必要，bug 报告或功能请求将转发到上游仓库。

可以通过赋予 otelcol.connector.servicegraph 组件不同的标签来指定多个实例。

此组件基于 Grafana Tempo 的服务图处理器。

服务图在以下用例中非常有用

• 推断分布式系统的拓扑结构。随着分布式系统规模的扩大，它们变得越来越复杂。服务图可以帮助你理解系统的结构。
• 提供系统健康的概览。服务图显示错误率、延迟和其他相关数据。
• 提供系统拓扑的历史视图。分布式系统变化非常频繁，服务图提供了一种查看这些系统随时间演变的方式。

由于 otelcol.connector.servicegraph 需要处理一条边的两侧，因此需要处理跟踪数据中的所有 span 才能正常工作。如果跟踪数据的 span 分布在多个 Alloy 实例上，则无法可靠地配对 span。解决此问题的一个方法是在运行 otelcol.connector.servicegraph 的 Alloy 实例前使用 otelcol.exporter.loadbalancing。

用法

alloy 复制

otelcol.connector.servicegraph "LABEL" {
  output {
    metrics = [...]
  }
}

参数

otelcol.connector.servicegraph 支持以下参数

服务图的工作原理是检查跟踪数据，查找具有父子关系且代表请求的 span。otelcol.connector.servicegraph 使用 OpenTelemetry 语义约定来检测多种请求。目前支持以下请求

• 两个服务之间的直接请求，其中出站 span 和入站 span 的 Span Kind 值必须分别为 client 和 server。
• 跨消息系统的请求，其中出站 span 和入站 span 的 Span Kind 值必须分别为 producer 和 consumer。
• 数据库请求，其中 span 的 Span Kind 值为 client，并且包含键为 db.name 的属性。

每个可以配对形成请求的 span 都保存在内存存储中

• 如果在 span 配对之前其 TTL 过期，则将其从存储中删除。TTL 在store块中配置。
• 如果在 span 过期之前完成配对，则记录指标并从存储中删除 span。

处理器发出以下指标

持续时间从客户端和服务端测量。

latency_histogram_buckets 参数控制 traces_service_graph_request_server 和 traces_service_graph_request_client 的桶。

每个发出的指标系列都有一个 client 和 server 标签，分别对应发起请求的服务和接收请求的服务。标签的值派生自这两个 span 的 service.name 资源属性。

connection_type 标签可能未设置。如果已设置，其值将是 messaging_system 或 database。

可以使用 dimensions 配置选项包含额外标签

• 这些标签将带有前缀，以标记其来源（客户端或服务端 span 类型）。client_ 前缀与 Span Kind 为 client 的 span 中的维度相关。server_ 前缀与 Span Kind 为 server 的 span 中的维度相关。
• 首先搜索资源属性。如果未找到该属性，则搜索 span 属性。

当 metrics_flush_interval 设置为 0s 时，每次接收到跟踪数据批次时都会刷新指标。

块

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

store 块

store 块配置 span 的内存存储。

output 块

output 块配置一组组件来转发产生的遥测数据。

支持以下参数

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

debug_metrics 块

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

支持以下参数

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

导出的字段

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

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

组件健康状态

仅当配置无效时，otelcol.connector.servicegraph 才会被报告为不健康。

调试信息

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

示例

以下示例接受跟踪数据，从中创建服务图指标，并将指标写入 Mimir。跟踪数据写入 Tempo。

otelcol.connector.servicegraph 还为每个指标添加一个标签，其值取自 span/资源属性“http.method”。

alloy 复制

otelcol.receiver.otlp "default" {
  grpc {
    endpoint = "0.0.0.0:4320"
  }

  output {
    traces  = [otelcol.connector.servicegraph.default.input,otelcol.exporter.otlp.grafana_cloud_traces.input]
  }
}

otelcol.connector.servicegraph "default" {
  dimensions = ["http.method"]
  output {
    metrics = [otelcol.exporter.prometheus.default.input]
  }
}

otelcol.exporter.prometheus "default" {
  forward_to = [prometheus.remote_write.mimir.receiver]
}

prometheus.remote_write "mimir" {
  endpoint {
    url = "https://prometheus-xxx.grafana.net/api/prom/push"

    basic_auth {
      username = sys.env("PROMETHEUS_USERNAME")
      password = sys.env("GRAFANA_CLOUD_API_KEY")
    }
  }
}

otelcol.exporter.otlp "grafana_cloud_traces" {
  client {
    endpoint = "https://tempo-xxx.grafana.net/tempo"
    auth     = otelcol.auth.basic.grafana_cloud_traces.handler
  }
}

otelcol.auth.basic "grafana_cloud_traces" {
  username = sys.env("TEMPO_USERNAME")
  password = sys.env("GRAFANA_CLOUD_API_KEY")
}

Mimir 中的一些指标可能如下所示

复制

traces_service_graph_request_total{client="shop-backend",failed="false",server="article-service",client_http_method="DELETE",server_http_method="DELETE"}
traces_service_graph_request_failed_total{client="shop-backend",client_http_method="POST",failed="false",server="auth-service",server_http_method="POST"}

兼容的组件

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

• 导出 OpenTelemetry otelcol.Consumer 的组件

otelcol.connector.servicegraph 具有可供以下组件消费的导出

• 消费 OpenTelemetry otelcol.Consumer 的组件