批处理、背压与优雅关闭
批处理可以减少请求开销，但也会改变故障影响和交付延迟。无限制地对事件进行排队的进程可能会在中断期间消耗内存。不考虑待处理工作而退出的进程可能会默默地丢失其最新事件。
Telemetry 的日志 API 接受一个 JSON 对象或一组 JSON 对象。 API 功能并不要求每个生产者都维护内存中的后台队列。
从直接等待交付开始
对于低容量工作流程，发送一个紧凑的结果事件并在有限的超时时间内等待请求。这是最容易推理和测试的交付路径。
当测量显示请求开销很大或现有工作人员已经拥有持久收集缓冲区时进行批量处理。优先选择小型、有时间限制的批次，而不是无限期等待大小阈值的大型队列。
await telemetry.log("api_request_completed", [
{
event_id: "evt_101",
route_template: "/api/projects/:id",
status: "success",
latency_ms: 84,
},
{
event_id: "evt_102",
route_template: "/api/projects/:id",
status: "failed",
latency_ms: 912,
error_type: "database_timeout",
},
]);
保持批次中的每个对象与相同的表模式兼容。一项无效或不兼容的项目可能会使整个请求的结果变得复杂。
绑定每个队列
如果应用程序缓冲事件，请定义：
- 最大排队事件计数和序列化字节。
- 发送部分批次之前的最长期限。
- 最大批量大小。
- 请求超时并重试预算。
- 溢出行为。
- 关闭行为。
溢出行为必须是明确的。丢弃最旧的低优先级诊断事件、对嘈杂的成功路径进行采样、阻止专用遥测工作人员以及坚持持久发件箱会产生不同的操作后果。不要让无界队列通过耗尽进程内存来决定。
通过安全的诊断路径记录队列深度、最早的事件年龄、发送的批次、接受的事件、丢弃的事件以及永久传送失败。避免通过同一失败队列递归发送遥测队列自己的失败事件。
将背压与客户工作分开
对于大多数产品分析，遥测交付不应消耗客户请求的全部延迟预算。使用短有界切换或应用程序拥有的工作线程。如果队列已满，请应用记录的溢出策略，而不是无限期等待。
对于计费或批准的审核事件，请使用耐用的发件箱并对发件箱工作人员施加背压，而不是丢失业务事件。 事件传递和幂等性指南 解释了跨尝试的稳定事件标识。
故意处理关机
在正常关闭信号上：
- 停止接受新工作。
- 允许运行中的应用程序工作达到定义的边界。
- 发送或保留剩余的遥测批次。
- 强制执行关闭期限。
- 记录无法交付的数量。
除非特定的 SDK 公开并记录了这一保证，否则请勿要求客户冲洗保证。当客户端立即发送每个调用时，等待所有跟踪的调用与刷新内部队列不同。无服务器和边缘运行时可能会在响应后冻结执行，因此请使用运行时支持的后台工作机制或在需要事件时在返回之前传递。
验证过载行为
测试完整批次、部分时间触发批次、429、503、连接超时、队列溢出以及带有挂起事件的进程终止。确认重试尝试保留事件 ID，并且没有故障路径打印凭据或原始负载。
使用 事件摄取故障排除指南 验证响应，使用 遥测音量指南 衡量是否确实需要分批或采样。