OpenRouter Broadcast 的 S3 目的地支持将每次 LLM 请求的 trace 以独立 JSON 文件形式存储到 Amazon S3 或任意 S3 兼容存储（Cloudflare R2、MinIO 等）。每个 trace 文件以 {traceId}-{timestamp}.json 命名，包含请求/响应、token 用量、费用、时间和自定义元数据。支持自定义 Path Template（如按日期、API Key 名称、年月日层级组织），可用 Amazon Athena 或 Presto 查询存储的 trace 数据。

Amazon S3 是高扩展性对象存储服务。OpenRouter 可以将 trace 存储到任何 S3 兼容存储，包括 AWS S3、Cloudflare R2、MinIO 等。

配置步骤

第一步：创建存储桶和凭证

对于 AWS S3：

1. 创建新的 S3 存储桶
2. 进入 IAM > Users 创建新用户（Programmatic Access）
3. 附加允许对存储桶进行 s3:PutObject 操作的策略
4. 复制 Access Key ID 和 Secret Access Key

对于 Cloudflare R2：

1. 在 Cloudflare 控制台创建 R2 存储桶
2. 进入 R2 > Manage R2 API Tokens 创建拥有写权限的 token
3. 复制 Access Key ID、Secret Access Key 和账号的 S3 endpoint

第二步：在 OpenRouter 开启 Broadcast

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

第三步：配置 S3

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

字段	填写内容
Bucket Name	存储桶名称（如 my-traces-bucket）
Region（可选）	AWS 区域（AWS 自动检测，部分 S3 兼容服务需填写）
Custom Endpoint（可选）	S3 兼容服务的 endpoint（如 https://your-account-id.r2.cloudflarestorage.com）
Access Key Id	Access Key ID
Secret Access Key	Secret Access Key
Session Token（可选）	临时凭证的 Session Token
Path Template（可选）	自定义对象路径，默认 openrouter-traces/{date}

第四步：测试并保存

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

第五步：验证数据写入

通过 OpenRouter 发送 API 请求，检查 S3 存储桶中是否出现 trace 文件。每个 trace 以独立 JSON 文件保存，格式为 {traceId}-{timestamp}.json。

Path Template 示例

通过 Path Template 自定义 trace 在存储桶中的组织方式：

模板	效果	适用场景
openrouter-traces/{date}	按日期归档（默认）	通用
traces/{year}/{month}/{day}	按年/月/日层级目录	需要按时间精细查询
{apiKeyName}/{date}	按 API Key 名称，再按日期	多项目/多团队共用账号
production/llm-traces/{date}	固定前缀 + 日期	多环境（prod/staging）隔离

如需按小时或天的批量文件（而非每次请求一个文件），建议使用 AWS Kinesis Firehose，它会缓冲记录并写入批量文件。

元数据与查询

通过 trace 字段传入的自定义元数据存储在 JSON 文件的 metadata 字段中，可用 Amazon Athena 或 Presto 查询：

-- Amazon 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';

元数据键映射

键	S3 JSON 映射	说明
trace_id	id（trace 层级）	自定义 trace 标识符
trace_name	name（trace 层级）	trace 的自定义名称
span_name	name（observation 层级）	中间 span 的名称
generation_name	name（observation 层级）	LLM 生成的名称

字段映射说明：

• user 映射到 trace JSON 中的 userId
• session_id 映射到 sessionId
• trace 文件包含完整的 input/output 消息、token 计数、费用和时间数据

Privacy Mode

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

常见问题

Q: Cloudflare R2 和 AWS S3 的配置有什么区别？

A: R2 需要额外填写 Custom Endpoint（格式为 https://{account-id}.r2.cloudflarestorage.com），Region 通常为 auto。其余配置方式相同。使用 R2 的优点是出口带宽免费，适合大量读取 trace 数据的场景。

Q: 如何用 Athena 查询 S3 中的 trace 文件？

A: 先在 Athena 中创建外部表（External Table）指向你的 S3 路径，指定 JSON 格式的 SerDe，然后就可以用 SQL 查询。metadata 字段用 json_extract_scalar 函数提取嵌套值。具体建表 DDL 可参考 AWS 文档。

Q: 每个请求都会产生一个单独的 S3 文件，会不会产生大量小文件？

A: 是的，高频调用时会产生大量小文件，这是对象存储的常见痛点。如果你主要用途是批量分析，建议结合 AWS Glue 或 Athena 的 CTAS（Create Table As Select）定期合并文件。如果需要实时批量写入，考虑 Kinesis Firehose 代替直接写 S3。