请求日志与追踪

v2.6.0 新增

从 v2.6.0 起，poeti.ai 自动为每次 API 调用生成追踪记录（Request Trace）。无需任何额外配置，即可查看每条请求的完整生命周期：从入口到路由决策、再到上游提供商响应。

🆕 v2.6.0 核心特性

每次请求自动记录，零配置启用
响应头返回 X-Trace-ID，方便端对端追踪
记录 Token 消耗、成本、延迟、路由策略
支持按模型/提供商/状态/时间过滤
提供聚合统计：按模型/应用分组
缓存命中请求也会记录（cost = $0）

Trace 记录字段说明

每条 Trace 记录包含以下字段：

字段名	类型	说明
trace_id	string	唯一追踪 ID，格式：`trace-poeti-xxxxxxxx`。同时通过响应头 `X-Trace-ID` 返回给调用方
model	string	请求中指定的模型名称
provider	string	实际路由到的 AI 提供商（openai / anthropic / bedrock / cache 等）
status	string	success / error / timeout
prompt_tokens	integer	本次请求消耗的输入 Token 数
completion_tokens	integer	本次请求生成的输出 Token 数
cost_usd	number	本次请求的美元成本（缓存命中为 0）
latency_ms	integer	端到端响应延迟（毫秒），从收到请求到返回结果
routing_strategy	string	本次使用的路由策略（comprehensive / round_robin / failover 等）
api_key_id	integer	用于本次调用的 poeti.ai API Key 的 ID
app_id	string	调用方应用 ID（通过请求头 `X-App-ID` 传入，可选）
error_message	string	失败时的错误信息（status 为 error 或 timeout 时有值）
created_at	string	请求时间（ISO 8601 格式，UTC 时区）

在控制台查看请求日志

进入控制台 → 请求日志，可以查看：

📈

实时统计卡片

总请求数、成功率、总 Token 数、总成本、平均延迟

🔍

多维过滤

按模型、状态、时间范围筛选

📋

日志明细列表

每条请求的完整信息，支持分页

💰

成本分析

按模型/提供商分组的成本消耗

通过 X-Trace-ID 定位请求

每次 API 调用，poeti.ai 都会在响应头中返回 X-Trace-ID。在出现问题时，可以用这个 ID 快速定位具体的调用记录。

# Step 1: 发送请求，从响应头获取 Trace ID
curl -i https://api.poeti.ai/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hello"}]}'

# 响应头中会包含：
HTTP/2 200
X-Trace-ID: trace-poeti-7f8e9d0a
Content-Type: application/json
                

# Step 2: 用 Trace ID 查询详情
curl https://api.poeti.ai/api/v1/request-traces/trace-poeti-7f8e9d0a \
  -H "Authorization: Bearer $API_KEY"
                

// 单条 Trace 详情响应
{
  "trace_id": "trace-poeti-7f8e9d0a",
  "model": "gpt-4o",
  "provider": "openai",
  "status": "success",
  "prompt_tokens": 128,
  "completion_tokens": 256,
  "total_tokens": 384,
  "cost_usd": 0.00768,
  "latency_ms": 843,
  "routing_strategy": "comprehensive",
  "api_key_id": 7,
  "created_at": "2026-04-09T14:23:18Z"
}
                

💡 最佳实践：建议在应用的日志系统中记录 X-Trace-ID，方便在用户反馈问题时快速定位对应的 AI 请求记录。

过滤与搜索

支持多个维度组合过滤：

# 多条件组合查询：查看昨天 gpt-4o 的所有失败请求
curl "https://api.poeti.ai/api/v1/request-traces?model=gpt-4o&status=error&date_from=2026-04-08&date_to=2026-04-09&page=1&page_size=50" \
  -H "Authorization: Bearer $API_KEY"
                

参数	类型	说明	示例
model	string	按模型名称过滤（精确匹配）	gpt-4o
provider	string	按提供商过滤	anthropic
status	string	success / error / timeout	error
date_from	string	开始时间（ISO 8601）	2026-04-01
date_to	string	结束时间（ISO 8601）	2026-04-30
app_id	string	按应用 ID 过滤（多租户场景）	app-123
page / page_size	integer	分页控制（page_size 最大 100）	page=1&page_size=20

统计与成本分析

追踪 API 提供三种统计接口：

GET /api/v1/request-traces/stats

总体汇总统计：总请求数、成功/失败数、Token 总量、总成本、平均延迟

{
  "total_requests": 15420,
  "success_count": 15210,
  "error_count": 210,
  "total_tokens": 8450230,
  "total_cost_usd": 42.18,
  "avg_latency_ms": 723,
  "avg_cost_per_request": 0.00274
}
                        

GET /api/v1/request-traces/stats/by-model

按模型分组统计（Top 50），了解哪个模型用量最大

{
  "by_model": [
    { "model": "gpt-4o", "requests": 8240, "cost_usd": 28.45, "avg_latency_ms": 650 },
    { "model": "claude-3-5-sonnet", "requests": 4180, "cost_usd": 10.23, "avg_latency_ms": 820 }
  ]
}
                        

GET /api/v1/request-traces/stats/by-app

按应用分组统计，多租户场景下了解各应用的用量

完整 API 参考

方法	端点	说明
GET	/api/v1/request-traces	获取请求追踪列表（支持过滤、分页）
GET	/api/v1/request-traces/{trace_id}	获取单条请求的完整详情
GET	/api/v1/request-traces/stats	总体汇总统计
GET	/api/v1/request-traces/stats/by-model	按模型分组统计（Top 50）
GET	/api/v1/request-traces/stats/by-app	按应用分组统计

典型使用场景

🐛 调试 AI 应用问题

用户报告某次回复不正确 → 从应用日志中找到 X-Trace-ID → 在控制台查看该请求的完整上下文、使用的模型和 Token 数 → 快速定位问题

💰 成本优化分析

通过 by-model 统计，发现 GPT-4o 占总成本 70% → 将部分简单任务迁移到 GPT-3.5 或 Claude Haiku → 成本降低 40%

📊 性能监控告警

定期查询 error_count 和 avg_latency_ms → 当失败率超过 5% 或延迟超过 2s 时触发告警 → 及时发现上游提供商异常

📋 多租户计费

SaaS 产品中，每个租户请求时传入 X-App-ID 头 → 通过 by-app 统计各租户用量 → 按实际消耗向租户收费