Grafana Cloud 是全托管可观测性平台，其 Tempo 组件支持分布式追踪。通过 OpenRouter Broadcast，每次 LLM 请求的 trace 通过标准 OTLP HTTP/JSON 协议发送到 Grafana Cloud，无需额外代理。配置需要三个值：OTLP Gateway Base URL（格式 https://otlp-gateway-prod-{region}.grafana.net）、数字 Instance ID 和具备 traces:write 权限的 API Token（以 glc_ 开头）。在 Grafana Explore 中使用 TraceQL { resource.service.name = "openrouter" } 查询所有 LLM trace；自定义元数据通过 trace.metadata.* 命名空间存储。

Grafana Cloud 是全托管可观测性平台，包含 Grafana Tempo 分布式追踪组件。OpenRouter 通过标准 OTLP HTTP/JSON 协议将 trace 发送到 Grafana Cloud，与现有指标和日志数据关联分析。

配置步骤

第一步：获取 Grafana Cloud 凭证

需要三个值：

获取 OTLP Endpoint：

1. 登录 Grafana Cloud 门户
2. 进入 Connections > Add new connection
3. 搜索 OpenTelemetry (OTLP) 并选择
4. 复制 OTLP endpoint URL

Base URL 格式为 https://otlp-gateway-prod-{region}.grafana.net，不是你的 Grafana 仪表盘 URL。

获取 Instance ID：

1. 进入 https://grafana.com/orgs/{your-org}/stacks
2. 选择你的 stack
3. 复制页面显示的数字 Instance ID

创建 API Token：

1. 进入 My Account > Access Policies
2. 创建新访问策略，作用域包含 traces:write
3. 从策略生成 token（以 glc_ 开头）

第二步：在 OpenRouter 开启 Broadcast

前往 Settings > Observability，打开 Enable Broadcast 开关。

第三步：配置 Grafana Cloud

点击 Grafana Cloud 旁边的编辑图标，填写：

字段	填写内容
Base URL	Grafana Cloud OTLP Gateway URL（如 https://otlp-gateway-prod-us-west-0.grafana.net）
Instance ID	数字 Grafana Cloud Instance ID
API Key	具备 write 权限的 Grafana Cloud API Token

第四步：测试并保存

点击 Test Connection 验证配置，测试通过后自动保存。

第五步：查看 LLM Trace

通过 OpenRouter 发送 API 请求后，有两种方式查看 trace：

方式一：Explore + TraceQL

1. 进入 Grafana Cloud 实例
2. 点击左侧 Explore
3. 选择 Tempo 数据源（如 grafanacloud-*-traces）
4. 切换到 TraceQL 标签
5. 运行查询：

{ resource.service.name = "openrouter" }

方式二：Drilldown > Traces

1. 进入左侧 Drilldown > Traces
2. 按服务名、时长等属性过滤
3. 点击任意 trace 查看完整 span 详情

Trace 属性说明

资源属性（Resource Attributes）

属性	值
service.name	openrouter
service.version	1.0.0

Span 属性

属性	说明
gen_ai.request.model	请求的模型
gen_ai.response.model	实际使用的模型
gen_ai.usage.input_tokens	输入 token 数
gen_ai.usage.output_tokens	输出 token 数
gen_ai.response.finish_reason	生成结束原因

元数据映射

通过 trace 字段传入的自定义元数据存储在 trace.metadata.* 命名空间：

键	Grafana 映射	说明
trace_id	Trace ID	将多个请求归入同一 trace
trace_name	Span Name	根 span 的自定义名称
span_name	Span Name	中间 span 的名称
generation_name	Span Name	LLM 生成 span 的名称
parent_span_id	Parent Span ID	链接到现有 span

其他映射：

• user → user.id（span attributes）
• session_id → session.id（span attributes）
• trace 中的自定义键 → trace.metadata.* 命名空间

示例

{
  "model": "openai/gpt-4o",
  "messages": [{ "role": "user", "content": "Analyze this metric..." }],
  "user": "user_12345",
  "session_id": "session_abc",
  "trace": {
    "trace_id": "monitoring_pipeline_001",
    "trace_name": "Metric Analysis Pipeline",
    "generation_name": "Anomaly Detection",
    "environment": "production",
    "alert_id": "alert_789"
  }
}

TraceQL 查询示例

# 按自定义元数据过滤
{ resource.service.name = "openrouter" && span.trace.metadata.environment = "production" }

# 慢请求（超过 5 秒）
{ resource.service.name = "openrouter" && duration > 5s }

# 按用户过滤
{ resource.service.name = "openrouter" && span.user.id = "user_abc123" }

# 查找错误
{ resource.service.name = "openrouter" && status = error }

Privacy Mode

当为此目的地开启 Privacy Mode 时，prompt 和 completion 内容会从 trace 中排除。其他 trace 数据仍正常发送。

常见问题

Q: Trace 为什么没有出现在 Grafana 中？

A: 排查顺序：① 检查时间范围是否覆盖请求时间（建议选"Last 1 hour"）；② 确认 Base URL 是 OTLP Gateway URL（otlp-gateway-prod-{region}.grafana.net），而非主仪表盘 URL；③ 确认 Instance ID 是数字，API Token 有 traces:write 权限；④ 等待 1-2 分钟，Grafana 有摄入延迟。

Q: 如何选择正确的 Tempo 数据源？

A: 在 Explore 视图中，数据源通常命名为 grafanacloud-{stack}-traces。如果看不到 trace，先确认选的是 Tempo 数据源，而非 Loki（日志）或 Prometheus（指标）。

Q: Grafana Broadcast 和 Datadog 的选型差异是什么？

A: Grafana Cloud 适合已有 Grafana 可观测性基础设施的团队，可将 LLM trace 与现有指标、日志、告警统一管理；Datadog 适合需要更完整 APM 功能（如 Service Map、Real User Monitoring）的场景，但成本相对更高。