Bulk Exports 目的地、计划作业与 Backfill

Bulk Export 将 workspace 内的 Traces/Experiments 按时间窗和 filter 输出到 S3 兼容目的地。它包含三层资源：Destination（去哪里）、Export（导出定义/计划）、Export Run（某个实际时间窗的执行）。

Destination

当前 destination type 只有 s3。创建必填 display name 和 config，可带 static credentials；config 包含 endpoint URL、bucket、prefix、region、S3/botocore 额外参数、path/virtual addressing、是否把 bucket 加进 prefix，以及可选 AWS role ARN。响应只返回 credentials_keys，不回显密钥值。

优先使用短期 AssumeRole 和限定 bucket/prefix 的最小权限，不用长期静态 access key。自定义 endpoint 要防 SSRF/DNS rebinding，禁止私网/云元数据地址，限制 TLS、重定向、端口和 bucket 命名。变更凭据时用“新权限验证 → 切换 → 跑一个受控导出 → 撤销旧凭据”，不在日志或 Trace 中记录 credentials。

当前组内没有 Destination 删除端点，不要自行拼猜 DELETE；退役时先停所有 Export/调度，再撤销 role/key 和 bucket 权限。

Export 定义与状态

创建必填 destination ID 和 start_time，可指定 session_id 或 all_experiments、end time、filter、interval_hours、导出字段。格式为 Parquet，版本 v1|v2_beta，压缩 none|gzip|snappy|zstandard。业务层强制明确且最小的作用域，不同时依赖含糊的 session/all-experiments 组合。

Export 状态：Created|IntervalScheduled|Running|Completed|Failed|TimedOut|Cancelled。interval_hours 会创建持续计划；列表中的 source_bulk_export_id 用来把派生执行关联回源计划。取消只是状态转换，不代表已写 S3 对象被删，也不保证正在上传的分片立即停止。

Export Run 与对账

• GET /api/v1/bulk-exports/{bulk_export_id}/runs：按 export 列执行，offset/limit；
• GET .../{bulk_export_id}/runs/{run_id}：读单次执行；
• GET /api/v1/bulk-exports/runs?source_bulk_export_id=...：按计划源 ID 列派生执行。

Run 状态为 Created|Running|Completed|Failed|TimedOut|Cancelled，带 retry number、errors、start/end/finished time 和 metadata。metadata 包含目标 prefix、时间窗、执行 backend 及 progress/result。对每个时间窗保存 (source export, run ID, start, end, prefix, status, retry)，校验窗口无缝、S3 object/manifest 完整和行数/校验和。

文档未明确时间窗边界是 inclusive 还是 exclusive；不要凭经验推断。首次上线用边界时刻的受控 Run 做 contract test，将实测规则固定在下游去重键中。v2_beta 格式要做 schema evolution 兼容，消费端忽略未知列、不假定列顺序。

幂等、重试与失败恢复

创建 Destination/Export 没有文档化 idempotency key，超时后先 list/get 按业务指纹查重，不盲目再创一个计划。执行失败后以时间窗 + export ID 去重，只重跑未完成窗口；下游使用临时 prefix 写入，校验完成后再发布 manifest/成功标记，防止消费半成品。

Restart Backfill 是独立的实例管理高风险接口

POST /api/v1/platform/ops/backfills/restart 需要 instance admin，body 中是 backfill_name。它会删除 backfill job 记录，使作业在下一次 cron tick 从头重启；这不是普通 Export Run 的局部 retry。

执行前必须确认精确 backfill name、影响数据集/时间窗、历史进度、剩余时间/存储和下游幂等性，获得审批并保存重启前快照。HTTP 200 只表示重启请求已处理，作业要到 cron 后才开始；监控新 job ID、进度、重复写入和错误。