跳转到内容
Telemetry
浏览文档
指南更新于 2026年7月30日由 Telemetry 编辑团队和产品团队审核阅读约需 4 分钟

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

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

本页内容
  1. 从示例事件开始
  2. 建立有针对性的结果
  3. 示例问题
  4. 查看生成的SQL
  5. 推广结果
  6. 验证清单

无需从 SQL 开始即可探索结构化事件

Explore 将一个结构化事件表转换为示例视图、分组结果或图表,而无需您从空白的 SQL 编辑器开始。它对于验证新仪器、调查有界操作问题以及创建第一个仪表板或告警非常有用。

生成的 SQL 仍然可见。将控件视为查询生成器,而不是单独的分析语言:检查结果、查看生成的查询,并在问题需要联接、多个公用表表达式或可重用指标定义时移至查询工作区。

探索操作流程示意图:运行、审核 SQL 和结果,然后添加到仪表板或创建告警。

流程示意图:先审核 SQL 查询和结果,再将结果添加到共享仪表板或创建告警。

从示例事件开始

在添加聚合之前,选择一个事件表并检查最近的行。确认:

  • 该表代表一个明确的工作单元,例如已完成的请求或代理运行;
  • 时间戳使用预期的发生时间和时区;
  • 数字字段是数字而不是看起来像数字的字符串;
  • 类别字段使用稳定的有界值;
  • 路由、发布、租户和相关字段按预期填充;
  • 敏感值不存在或根据您的隐私政策进行转换。

图表可以隐藏空值、混合单位、重复传递和意外稀疏的字段。样本会在这些问题成为误导性的比率或百分位数之前将其暴露出来。

建立有针对性的结果

Explore 支持示例和表格结果以及折线图、条形图和堆积面积图。选择能够回答问题的最小视图。

  1. 选择表和时间范围。
  2. 添加稳定字段(例如 environmentserviceoutcome)或路由模板的过滤器。
  3. 选择 countsumaverageminmax 或百分位数聚合。
  4. 当聚合需要数字字段时,选择数字字段。
  5. 仅按有助于解释结果的有界维度拆分系列。
  6. 检查生成的 SQL 和返回的行数。

当嵌套结构化字段出现在表架构中时,可以对其进行过滤。优先选择显式列和路由模板,而不是原始 URL 或任意对象内容。

示例问题

问题 建议的控制措施
API发布后故障是否增加? 按时间对事件进行计数,过滤失败的结果,按版本拆分
哪个作业队列重试最频繁? 计算事件数,过滤大于 1 的尝试,按队列拆分
一项功能的模型成本是否会上升? 按时间求和估计成本,按有界功能名称分割
浏览器性能有变化吗? 选择 Web Vital 的百分位数,按指标过滤,按版本拆分

将成交量放在比率和百分位数旁边。基于三个事件的看似严重的变化不应被解释为基于三百万个事件的相同变化。

查看生成的SQL

在保存结果之前,检查生成的查询:

  • 过滤预期的时间场和环境;
  • 使用正确的分母来计算比率;
  • 故意处理空值;
  • 与决策具有相同粒度的分组;
  • 不被高基数标识符分割;
  • 排除不完整的最新时间段,因为这会扭曲比较。

当您需要对交付进行重复数据删除、连接表、连接前预聚合、比较多个群组或在 SQL 中记录指标时,请在查询中打开结果。 Explore 有意以单表调查为中心。

推广结果

当团队成员重复需要相同的答案时,将经过审核的探索结果添加到仪表板。为小部件指定一个面向决策的名称,保留相关的时间范围和过滤器,并将成交量视图放置在任何百分比或百分位附近。

仅在检查几个代表性窗口后才创建告警。定义所有者、阈值、评估窗口和响应操作。由稀疏或不完整的最新数据构建的阈值会产生噪音。

验证清单

  1. 发送具有已知字段值的合成事件。
  2. 在示例视图中找到确切的事件。
  3. 添加一个包含它的过滤器,然后添加一个排除它的过滤器。
  4. 将计数或总和与手动已知的固定装置进行比较。
  5. 查看生成的 SQL。
  6. 保存结果并从目标仪表板或告警流中重新打开它。
  7. 确认另一位目标团队成员可以解释标题、过滤器、单位和响应操作。

继续使用 编写第一个 Telemetry SQL 查询创建仪表板告警

相关产品功能

对结构化事件表运行只读 DataFusion SQL 并重用结果。

内容责任与技术参考

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

查看编辑规范