Grafana Cloud

将追踪发送到 Grafana Cloud

Grafana Cloud 是全托管可观测性平台，包含用于分布式追踪的 Grafana Tempo。OpenRouter 通过标准 OTLP HTTP/JSON 端点发送追踪。

第 1 步：获取 Grafana Cloud 凭据

你需要从 Grafana Cloud 门户获取三个值：

1. Base URL：你的 Grafana Cloud OTLP 端点（例如 https://otlp-gateway-prod-us-west-0.grafana.net）
2. Instance ID：你的 Grafana Cloud 数字实例 ID（例如 123456）
3. API Key：具有写入权限的 Grafana Cloud API 令牌（以 glc_... 开头）

查找 OTLP 端点

1. 登录 Grafana Cloud 门户
2. 前往 连接（Connections） > 添加新连接（Add new connection）
3. 搜索 OpenTelemetry (OTLP) 并选中
4. 在配置页上即可找到 OTLP endpoint URL

查找 Instance ID

1. 前往 https://grafana.com/orgs/{your-org}/stacks 打开你的 Grafana Cloud 账户
2. 选择你的 stack
3. Instance ID 是 URL 中或 stack 详情页上显示的数字值

创建 API 令牌

1. 在 Grafana Cloud 中，前往 我的账户（My Account） > 访问策略（Access Policies）
2. 创建具有 traces:write 作用域的新访问策略
3. 从该策略生成令牌
4. 复制令牌（以 glc_... 开头）

第 2 步：在 OpenRouter 中启用广播

前往 设置 > 可观测性（Settings > Observability），打开 启用广播（Enable Broadcast） 开关。

第 3 步：配置 Grafana Cloud

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

• Base URL：你的 Grafana Cloud OTLP 端点（例如 https://otlp-gateway-prod-us-west-0.grafana.net）
• Instance ID：你的 Grafana Cloud 数字实例 ID
• API Key：具有写入权限的 Grafana Cloud API 令牌

第 4 步：测试并保存

点击 测试连接（Test Connection） 验证配置。仅当测试通过时才会保存配置。

第 5 步：发送测试追踪

通过 OpenRouter 发出一次 API 请求，然后在 Grafana Cloud 中查看该追踪。

查看追踪

配置完成后，你可以通过两种方式在 Grafana Cloud 中查看追踪：

方式 1：使用 TraceQL 探索

1. 打开你的 Grafana Cloud 实例（例如 https://your-stack.grafana.net）
2. 点击左侧边栏中的 探索（Explore）
3. 选择 Tempo 数据源（例如 grafanacloud-*-traces）
4. 切换到 TraceQL 选项卡
5. 运行以下查询以查看所有 OpenRouter 追踪：

{ resource.service.name = "openrouter" }

你也可以按特定属性筛选：

{ resource.service.name = "openrouter" && span.gen_ai.request.model = "openai/gpt-4-turbo" }

方式 2：下钻 > 追踪（Drilldown > Traces）

1. 打开你的 Grafana Cloud 实例
2. 在左侧边栏前往 下钻（Drilldown） > 追踪（Traces）
3. 使用筛选器按服务名称、持续时间或其他属性查找追踪
4. 点击任意追踪以查看完整的 Span 分解

追踪属性

OpenRouter 追踪包含以下关键属性：

资源属性

• service.name：始终为 openrouter
• service.version：1.0.0
• openrouter.trace.id：OpenRouter 追踪 ID

Span 属性

• gen_ai.operation.name：操作类型（例如 chat）
• gen_ai.system：AI 模型服务提供商（例如 openai）
• gen_ai.request.model：请求的模型
• gen_ai.response.model：实际使用的模型
• gen_ai.usage.input_tokens：输入 Token 数
• gen_ai.usage.output_tokens：输出 Token 数
• gen_ai.usage.total_tokens：使用的 Token 总量
• gen_ai.response.finish_reason：生成结束的原因（例如 stop）

自定义元数据

附加到 OpenRouter 请求的任何元数据都会出现在 trace.metadata.* 命名空间下。详情见下文 自定义元数据。

自定义元数据

Grafana Cloud 通过 OTLP 协议接收追踪。trace 字段中的自定义元数据会作为 Span 属性发送，并可用 TraceQL 查询。

支持的元数据键

示例

{
  "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 查询自定义元数据

自定义元数据键作为 Span 属性位于 trace.metadata.* 下：

{ resource.service.name = "openrouter" && span.trace.metadata.environment = "production" }

{ resource.service.name = "openrouter" && span.trace.metadata.alert_id = "alert_789" }

补充说明

• user 字段会映射到 Span 属性中的 user.id
• session_id 字段会映射到 Span 属性中的 session.id
• trace 中的自定义元数据键会出现在 Span 属性的 trace.metadata.* 命名空间下
• 你可以根据自定义元数据属性创建 Grafana 仪表盘和告警

TraceQL 查询示例

查找慢请求（> 5 秒）

{ resource.service.name = "openrouter" && duration > 5s }

按用户查找请求

{ resource.service.name = "openrouter" && span.user.id = "user_abc123" }

查找错误

{ resource.service.name = "openrouter" && status = error }

按模型查找请求

{ resource.service.name = "openrouter" && span.gen_ai.request.model =~ ".*gpt-4.*" }

故障排除

追踪未出现

1. 检查时间范围：Grafana 的时间选择器可能未包含追踪时间戳。尝试扩大到「最近 1 小时（Last 1 hour）」或「最近 24 小时（Last 24 hours）」。
2. 核对端点：确保使用的是 OTLP 网关 URL（https://otlp-gateway-prod-{region}.grafana.net），而不是主 Grafana URL。
3. 检查身份验证：确保 Instance ID 为数字，且 API 密钥具有写入权限。
4. 稍等片刻：追踪出现在 Grafana 中可能有 1–2 分钟延迟。

数据源不正确

如果看不到任何追踪，请确认已在探索（Explore）视图中选择正确的 Tempo 数据源。通常名为 grafanacloud-{stack}-traces。

更多资源

• Grafana Cloud OTLP 文档
• TraceQL 查询语言
• Grafana Tempo 文档

隐私模式

当该目标端启用 隐私模式 时，追踪中会排除提示词和补全内容。其余追踪数据——Token 用量、费用、时间信息、模型信息以及自定义元数据——仍会正常发送。详情见 隐私模式。