上报端点参考
本页集中列出 Argus 上报网关（Ingestion） 的写入端点。所有上报都需 DSN + HMAC-SHA256 签名 认证，机制见 DSN 与 HMAC 签名。
绝大多数场景用对应平台的 SDK 即可，它们已封装签名、批量、重试与降级。本页面向 需要自定义客户端或理解底层协议的场景。
认证：HMAC 签名
每个请求按 canonical 串 METHOD\nPATH\nTS\nsha256hex(BODY) 计算 HMAC-SHA256，用 DSN 的 secret_key
签名。各语言 SDK（go / node / python / java / rust）与服务端逐字节一致（已交叉验证）。签名头与时间戳
的具体字段名以 DSN 与 HMAC 签名 及
sdks/common-protocol 为准。
核心写入端点
上报网关注册以下 HMAC 认证的写入端点（源码见
services/ingestion/main.go）：
POST /v1/events — 统一事件端点
端上 SDK 的主上报通道。日志 / 崩溃 / APM / 埋点 / trace 都走这一个端点，用请求体内的
channel（log / crash / apm / track / trace）区分类型（ADR-0038 统一协议 · 方案 B）。
- 认证：DSN + HMAC
- 请求体：
EventBatch（批量事件，JSON），字段跨端逐字节一致 - 典型响应：
200（接收）；配额耗尽402；速率过快429 + Retry-After
POST /v1/backend/logs — 后端 SDK 日志
后端 SDK（go / node / python / java / rust）的应用日志上报通道。
- 认证：DSN + HMAC
- 请求体：批量日志条目（JSON）
POST /v1/experiment — 实验事件
A/B 实验的曝光（exposure）与转化（conversion）上报。
- 认证：DSN + HMAC
- 请求体：实验事件（JSON）
- 对应能力：A/B 实验
trace span 也经统一 EventBatch 上报到 /v1/events（channel="trace"），而非独立 trace 端点——
这样端 + 后端的 span 用同一条摄取管线，见 分布式追踪。
相关端点
以下端点由其他服务提供，认证方式因场景而异：
| 端点 | 用途 | 说明 |
|---|---|---|
POST /v1/logs/upload | 日志回捞文件上传 | 设备被远程触发后上传本地加密日志，见 日志回捞 |
/v1/feedback、/v1/feedback/attachments | 用户反馈与富媒体附件 | 见 用户反馈 |
行为约定（SDK 侧）
| 方面 | 行为 |
|---|---|
| 批量 | 事件入缓冲，按间隔 / 满批 / 手动 flush 批量上报 |
| 重试 | 5xx / 网络错误指数退避重试；4xx（鉴权 / payload）立即丢弃不重试 |
| 背压 | 缓冲超上限 drop-oldest（保留最新窗口） |
| 配额 | 收到 402 停止重试该类事件并走本地降级队列；429 按 Retry-After 退避 |
常见问题
Q：我一定要手写 HMAC 签名吗？ 不需要。用 SDK 即可，签名由 SDK 内部处理。只有自定义客户端才需手工实现。
Q：为什么崩溃和日志用同一个端点？
统一 /v1/events 让所有端上数据走同一条摄取 + 存储管线，用 channel 区分。这是 Argus”多能力统一
接入框架”的一部分，见 平台架构。
Q：查询数据用哪个 API？ 上报（写）用本页端点 + HMAC；查询（读）用 PAT Bearer，见 API 总览与认证 与 OpenAPI。