OpenRouter 安全与可观测

OpenRouter 安全与可观测

S3 / S3 兼容存储

2 分钟阅读

S3 / S3-Compatible

将追踪发送到 Amazon S3 或兼容 S3 的存储

Amazon S3 是可扩展的对象存储服务。OpenRouter 可以向任何兼容 S3 的存储发送追踪，包括 AWS S3、Cloudflare R2、MinIO 以及其他兼容服务。

第 1 步：创建 S3 存储桶和凭据

在云服务提供商控制台中，创建一个用于存储追踪的存储桶，并生成对该存储桶具有写入权限的访问凭据。

对于 AWS S3：

  1. 创建新的 S3 存储桶或使用现有存储桶
  2. 前往 IAM > 用户（Users） 并创建具有编程访问权限的新用户
  3. 附加允许对存储桶执行 s3:PutObject 的策略
  4. 复制 Access Key ID 和 Secret Access Key

对于 Cloudflare R2：

  1. 在 Cloudflare 控制台中创建新的 R2 存储桶
  2. 前往 R2 > 管理 R2 API 令牌（Manage R2 API Tokens） 并创建具有写入权限的新令牌
  3. 复制 Access Key ID、Secret Access Key 以及账户的 S3 端点

第 2 步：在 OpenRouter 中启用广播

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

启用广播

第 3 步：配置 S3

点击 S3 / S3-Compatible 旁的编辑图标，并填写：

  • Bucket Name：你的 S3 存储桶名称（例如 my-traces-bucket）
  • Region（可选）：AWS 区域（AWS 可自动检测；部分兼容 S3 的服务需要填写）
  • Custom Endpoint（可选）：对于 R2 等兼容 S3 的服务，填写端点 URL（例如 https://your-account-id.r2.cloudflarestorage.com）
  • Access Key Id：你的访问密钥 ID
  • Secret Access Key：你的秘密访问密钥
  • Session Token（可选）：用于临时凭据
  • Path Template（可选）：自定义对象路径。默认为 openrouter-traces/{date}。可用变量：{prefix}、{date}、{year}、{month}、{day}、{apiKeyName}

第 4 步：测试并保存

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

第 5 步：发送测试追踪

通过 OpenRouter 发出一次 API 请求，然后检查 S3 存储桶中的追踪文件。每条追踪保存为单独的 JSON 文件，格式为 {traceId}-{timestamp}.json。

路径模板示例

自定义追踪在存储桶中的组织方式：

  • openrouter-traces/{date} - 默认，按日期组织（例如 openrouter-traces/2024-01-15/abc123-1705312800.json）
  • traces/{year}/{month}/{day} - 分层日期结构
  • {apiKeyName}/{date} - 先按 API 密钥名称、再按日期组织
  • production/llm-traces/{date} - 用于环境隔离的自定义前缀

若需要基于时间的批处理（例如按小时或按天聚合的文件），可考虑改用 AWS Kinesis Firehose，它会缓冲记录并将批量文件写入 S3。

自定义元数据

trace 字段中的自定义元数据会包含在存储到 S3 存储桶的 JSON 追踪文件中。元数据位于追踪内每个观测的 metadata 字段中。

支持的元数据键

键S3 JSON 映射说明
trace_idid（追踪级）自定义追踪标识符
trace_namename（追踪级）追踪的自定义名称
span_namename（观测级）中间 Span 的名称
generation_namename（观测级）LLM 生成的名称

示例

{
  "model": "openai/gpt-4o",
  "messages": [{ "role": "user", "content": "Analyze this document..." }],
  "user": "user_12345",
  "session_id": "session_abc",
  "trace": {
    "trace_name": "Document Analysis",
    "generation_name": "Extract Key Points",
    "document_type": "contract",
    "batch_id": "batch_456"
  }
}

在 S3 中访问元数据

每个追踪文件都是一个 JSON 对象。trace 中的自定义元数据键存储在 metadata 字段中，可以使用 Amazon Athena、Presto 或任何支持 JSON 的查询引擎进行查询：

-- 针对 S3 追踪文件的 Athena 查询示例
SELECT
  json_extract_scalar(metadata, '$.document_type') as doc_type,
  json_extract_scalar(metadata, '$.batch_id') as batch_id
FROM openrouter_traces
WHERE json_extract_scalar(metadata, '$.document_type') = 'contract';

补充说明

  • user 字段会映射到追踪 JSON 中的 userId
  • session_id 字段会映射到追踪 JSON 中的 sessionId
  • 追踪文件除自定义元数据外，还包含完整的输入/输出消息、Token 计数、费用和时间数据

隐私模式

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

上一页Ramp下一页 Sentry