链路追踪与监控集成

数据墙DBW 内置 OpenTelemetry 支持，可以输出分布式追踪（Tracing）和运行时指标（Metrics）。REST、GraphQL、数据库查询和 MCP 工具调用都会生成追踪数据，方便接入外部监控平台。

启用 OpenTelemetry

使用 dab add-telemetry 命令将 OpenTelemetry 配置写入配置文件：

bash

dab add-telemetry \
  -c dab-config.json \
  --otel-enabled true \
  --otel-endpoint "http://localhost:4317" \
  --otel-protocol "grpc" \
  --otel-service-name "dab-api" \
  --otel-headers "api-key=key"

生成的配置：

json

{
  "runtime": {
    "telemetry": {
      "open-telemetry": {
        "enabled": true,
        "endpoint": "http://localhost:4317",
        "exporter-protocol": "grpc",
        "service-name": "dab-api",
        "headers": "api-key=key"
      }
    }
  }
}

字段	说明
`enabled`	是否启用 OpenTelemetry 导出
`endpoint`	OpenTelemetry Collector 的接收端点地址
`exporter-protocol`	传输协议：`grpc`（推荐）或 `httpprotobuf`
`service-name`	服务名称，在追踪后端中标识此服务
`headers`	导出请求头，多个头用逗号分隔（如 `api-key=key,other=value`）

IMPORTANT

OpenTelemetry 配置只能通过 dab add-telemetry 命令添加，dab configure 不支持修改 OpenTelemetry 选项。如需修改，请手动编辑配置文件。

追踪内容

数据墙DBW 为以下操作创建追踪 Span：

追踪范围	包含的标签（Tag）
HTTP 请求（REST）	`http.method`、`http.url`、`http.querystring`、`http.status_code`、`user.role`、`user-agent`
GraphQL 操作	操作类型、实体名、查询深度、`api.type`
数据库查询	`data-source.type`、`data-source.name`、实体名、SQL 语句
MCP 工具调用	工具名、实体名、操作类型
中间件步骤	认证、授权、请求处理各阶段耗时

每个 Span 包含时间戳、耗时和状态信息，帮助你定位慢查询、权限问题和异常。

指标内容

数据墙DBW 输出以下 OpenTelemetry 指标：

指标	类型	标签
请求总数	Counter	HTTP 方法、状态码、端点、`api.type`
错误数	Counter	错误类型、HTTP 方法、状态码、端点、`api.type`
请求耗时	Histogram（毫秒）	HTTP 方法、状态码、端点、`api.type`
并发请求数	UpDownCounter	实时并发连接数

所有指标按 api.type（REST / GraphQL）标签区分，便于分别监控两种协议的表现。

接入监控平台

Jaeger（分布式追踪）

部署 Jaeger All-in-One：

bash

docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

数据墙DBW 配置中指向 Jaeger 的 OTLP gRPC 端点：

json

{
  "runtime": {
    "telemetry": {
      "open-telemetry": {
        "enabled": true,
        "endpoint": "http://localhost:4317",
        "exporter-protocol": "grpc",
        "service-name": "dab-api"
      }
    }
  }
}

访问 Jaeger UI：http://localhost:16686

Prometheus + Grafana（指标监控）

OpenTelemetry Collector 作为中间代理，接收数据墙DBW 的追踪和指标，再转发给 Prometheus：

yaml

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [prometheus]

Prometheus 配置中抓取 Collector 暴露的指标端点：

yaml

scrape_configs:
  - job_name: 'otel-collector'
    static_configs:
      - targets: ['localhost:8889']

Grafana 连接 Prometheus 作为数据源，即可展示数据墙DBW 的请求量、错误率、延迟分布等仪表盘。

开发环境：.NET Aspire Dashboard

如果在 .NET Aspire 环境中开发，仪表盘自带 OpenTelemetry 追踪和指标的查看界面，无需额外配置 Collector。在开发阶段可以直接使用。

追踪数据的使用

定位慢查询

在 Jaeger 中找到耗时最长的 Span，关注 data-source.type 标签确认是哪个数据库、哪个实体的查询慢了。结合数据库的慢查询日志和索引分析定位根因。

分析错误模式

通过 status.code 和错误标签（Tag），统计特定端点或操作的错误率。比如某个 POST 端点频繁返回 403，检查该实体的权限配置。

追踪 MCP 调用链

MCP 工具调用也生成完整追踪。当 AI 代理查询结果不符合预期时，可以回溯整个 MCP 调用链：代理 → MCP 端点 → 权限验证 → 数据库查询 → 响应。

性能影响

OpenTelemetry 导出是异步的，对请求延迟的影响通常低于 1ms。但在高吞吐场景下（>1000 req/s），采样率是一个重要的调优手段。

数据墙DBW 目前不支持内置采样策略配置。如果需要采样，可以在 OpenTelemetry Collector 端配置采样规则（如概率采样、尾部采样），减少传输和存储的追踪数据量。

导出机制

遥测通过 .NET OpenTelemetry SDK 导出到配置的后端。导出时机由 SDK 控制：

追踪（Tracing）：在 Span 活动完成时立即导出。
指标（Metrics）：按 SDK 配置的定期间隔批量导出。未设置间隔时使用 SDK 默认值。

追踪上下文通过请求传播，确保跨服务和中间件的调用链完整。

NOTE

快速关闭的临时容器可能在导出完成之前退出。容器停止时应允许优雅退出（graceful shutdown），确保待处理的遥测数据刷新完成。

配置检查清单

检查项	操作
OpenTelemetry Collector 是否运行	确认 `endpoint` 指向的地址可访问
协议是否匹配	`grpc` vs `httpprotobuf`，与 Collector 的接收器配置一致
服务名是否唯一	多实例部署时用相同 `service-name`
网络连通性	容器环境中确认容器间网络可达
防火墙规则	确认 Collector 端口未被防火墙阻止
优雅关闭	容器停止时允许优雅退出，确保待处理的遥测数据刷新完成

下一步

健康检查 — /health 端点用于存活和就绪探测。
日志级别 — 配合追踪的诊断日志。

链路追踪与监控集成 ​

启用 OpenTelemetry ​

追踪内容 ​

指标内容 ​

接入监控平台 ​

Jaeger（分布式追踪） ​

Prometheus + Grafana（指标监控） ​

开发环境：.NET Aspire Dashboard ​

追踪数据的使用 ​

定位慢查询 ​

分析错误模式 ​

追踪 MCP 调用链 ​

性能影响 ​

导出机制 ​

配置检查清单 ​

下一步 ​