跳转到内容
Telemetry
浏览文档
概念与 SQL 模式更新于 2026年7月27日由 Telemetry 编辑团队和产品团队审核阅读约需 2 分钟

让编程智能体使用这篇文档

打开 Claude Code、Codex、Cursor 或其他编码代理的集中提示包,然后将其适应此处介绍的工作流程。

本页内容
  1. 有用的高基数字段
  2. 偶然的基数
  3. 查询模式

高基数字段

基数是字段中不同值的数量。 status 字段可以具有三个值; request_id 每行可能有不同的值。高基数本质上并不是错误的,但它改变了字段的查询和可视化方式。

有用的高基数字段

请求、跟踪、作业、帐户和用户标识符在调查过程中可能至关重要。它们可以让您查找相关事件或确定谁受到了影响。当存在特定的查找或连接用例以及标识符可以安全存储时保留它们。

不要使用唯一标识符作为图表的默认分组维度。包含 100,000 个请求 ID 的条形图既不可读也不高效。筛选到特定标识符,或按有界类别进行分组并将标识符保留在详细信息表中。

偶然的基数

原始 URL、异常消息、SQL 文本、用户代理和自由格式标签通常会无意中创建基数。将 /projects/abc123 标准化为 route_template,例如 /projects/:id。将异常映射到受控的 error_type,同时在适当的日志系统中保留详细的诊断信息。切勿仅仅为了保留上下文而将秘密或原始用户内容放入事件中。

分区列值得格外小心。对过滤有用的字段并不一定是一个好的分区。过多的不同分区会创建小文件和规划开销。仅在测量代表性查询后才选择稳定的、经常过滤的维度。参见 选择分区列

查询模式

启动具有时间限制的聚合,按受控维度进行分组,并在对百分比进行排名之前施加最小量规则。对于调查,直接按高基数标识符进行过滤并请求一组狭窄的列。

SELECT timestamp_utc, status, error_type, latency_ms
FROM api_requests
WHERE request_id = 'req_example'
ORDER BY timestamp_utc;

查看 关联 ID 指南敏感数据指南 旁边的标识符。

相关产品功能

记录稳定的事件名称、类型明确的字段,以及经过隐私审核的上下文。

内容责任与技术参考

Telemetry 编辑团队负责维护本文;产品团队审核功能行为、示例和适用范围。

查看编辑规范