metrics-queries

在 Honeycomb 中查询指标

Honeycomb 中的指标数据集与追踪／事件数据集的行为不同。 适用于追踪数据的操作，在指标数据集上可能会失败或产生误导性结果。 本技能介绍这些差异，帮助你构建正确且实用的指标查询。

查找指标数据集

指标数据集并非通过名称中包含“metrics”来识别。许多事件数据集的 slug 中包含“metrics”（例如，kafka-metrics、refinery-metrics、 kubernetes-node-metrics）。这些是普通的事件数据集，而非指标数据集。

如何识别真正的指标数据集：

1. 调用 get_environment，查找 dataset_type = metrics 的行。 slug 通常为 metrics，但可能因环境而异。
2. 也可以对候选数据集调用 get_dataset_columns——指标数据集会返回一个 MetricInfo 列，其中显示类型元数据，例如 gauge、 sum(cumulative,monotonic) 或 histogram(delta)。事件数据集没有此列。

不要猜测数据集。 构建指标查询前，务必通过 get_environment 或 get_dataset_columns 进行验证。如果用户说“指标”，但指的是包含类似指标字段的事件数据集 （例如 telegraf、system_stats），则以下查询规则不适用——这些是事件数据集，应遵循 query-patterns 技能中的常规查询模式。

发现指标及其属性

指标数据集的架构与事件数据集有根本区别。每个指标都有自己的一组资源属性和数据点属性。同一数据集中的两个指标，在筛选和分组时可用的属性可能完全不同。

发现可查询内容的工作流：

1. 查找指标名称： 对指标数据集调用 get_dataset_columns（不带 metric_name）。这会在 MetricInfo 中返回指标名称及其类型。 使用 find_columns 和关键词搜索特定指标（例如“cpu”、“memory”、 “http request duration”）。

2. 查找特定指标的属性： 调用 get_dataset_columns，并将 metric_name 参数设为要查询的指标（例如， metric_name: "k8s.pod.memory.usage"）。这会返回与该指标同时出现的资源属性和 数据点属性，以及样例值。 这些属性可用于 WHERE 和 GROUP BY 子句。

3. 查询前验证： 并非所有指标都包含所有属性。添加属性到筛选条件或细分维度前，务必通过第 2 步确认可用属性。

指标数据集上允许与禁止的操作

以下操作不允许用于指标数据集：

禁止的操作	原因
COUNT（不带列）	统计的是指标事件，而非指标值——对指标而言毫无意义
RATE_SUM	指标数据集不支持
RATE_AVG	指标数据集不支持
RATE_MAX	指标数据集不支持
CONCURRENCY	需要 span 时长；指标没有时长

请改用以下操作：

目标	指标数据集上的用法
可视化 gauge 值	AVG(metric)、MAX(metric)、HEATMAP(metric)
可视化 counter／sum	SUM(metric)、AVG(metric)、MAX(metric)
查看值的分布	HEATMAP(metric)、P50(metric)、P99(metric)
跟踪每秒变化率	使用计算字段覆盖时间聚合（见下文）
百分位数分析	P50(metric)、P90(metric)、P99(metric)
统计非空值数量	COUNT(metric)（需指定列）

指标类型与时间聚合

Honeycomb 会自动应用时间聚合，将原始指标值对齐到查询的时间步长。所用函数取决于指标类型，可在 get_dataset_columns 返回的 MetricInfo 列中查看。

按指标类型应用的默认时间聚合

MetricInfo	类型	默认函数	作用
gauge	Gauge	LAST()	返回每个时间步中最近的值
sum(cumulative,monotonic)	单调累积和	INCREASE()	计算各时间步之间的变化，并处理计数器重置
sum(cumulative)	非单调累积和	LAST()	返回最近的值（可能增大或减小）
sum(delta) 或 sum(delta,monotonic)	Delta 和	SUMMARIZE()	对每个时间步中的所有值求和
histogram(cumulative)	累积直方图	INCREASE()	计算各时间步之间每个桶的变化
histogram(delta)	Delta 直方图	SUMMARIZE()	对每个时间步中的桶值求和

这些默认设置会自动应用，无需配置。 在指标数据集中看到的 AVG、MAX、P99 等结果，已经先应用了时间聚合。

覆盖时间聚合

如需覆盖默认设置（例如，为累积计数器查看 RATE 而非 INCREASE）， 请使用查询范围内的计算字段，将指标名称包装在时间聚合 函数中，然后在 calculations 中对该字段应用空间聚合。

{
  "calculated_fields": [
    { "name": "req_rate", "expression": "RATE($http.server.requests, 300)" }
  ],
  "calculations": [
    { "op": "AVG", "column": "req_rate" }
  ]
}

计算字段支持的时间聚合函数：

• LAST($metric) — 每个时间步中最近的数据点（仪表盘、非单调和）
• SUMMARIZE($metric) — 使用插值对每个时间步中的所有值求和（Delta 指标）
• INCREASE($metric[, range_interval_seconds]) — 计算区间内的值变化，并处理计数器重置
• RATE($metric[, range_interval_seconds]) — 每秒变化率（INCREASE / time）

可选参数 range_interval_seconds（以秒为单位的整数）用于控制计算变化时的回溯 窗口。可用它平滑结果，或补偿稀疏数据。 如果省略此参数，则使用查询的粒度作为区间。

重要： 仍必须在 calculations 中对计算字段应用空间聚合（AVG、SUM、P99、HEATMAP 等）。 仅使用时间聚合函数不会生成可视化结果——它会转换原始指标值，然后由空间聚合 汇总各个时间序列。

有关时间聚合函数、计数器重置处理和 range_interval_seconds 的详细参考，请参阅： ${CLAUDE_PLUGIN_ROOT}/skills/metrics-queries/references/temporal-aggregation.md

查询直方图指标

OpenTelemetry 直方图以一组子字段的形式存储。对于名为 http.server.duration 的直方图，Honeycomb 会创建：

字段	含义
http.server.duration.count	数据点总数
http.server.duration.sum	所有值的总和
http.server.duration.avg	平均值（sum/count）
http.server.duration.p50	中位数（第 50 百分位数）
http.server.duration.p99	第 99 百分位数
http.server.duration.p001 到 .p999	完整的百分位数范围

查询直方图的两种方式：

1. 直接使用父列名称进行百分位数或分布运算。 推荐使用此方法：

   { "op": "P99", "column": "http.server.duration" }
   

   { "op": "HEATMAP", "column": "http.server.duration" }
   

2. 对需要的子字段使用 MAX，以获取某个时间步中所有时间序列里的最坏情况预计算百分位数：

   { "op": "MAX", "column": "http.server.duration.p99" }
   

   这会返回该时间步中任一单独时间序列报告的最高 p99 值， 与 P99(http.server.duration) 不同，后者会计算所有数据中的第 99 百分位数。

如何选择：

• 对于大多数分析：使用 P99(parent_column) 或 HEATMAP(parent_column)
• 对于跨主机／Pod 的最坏情况边界：使用 MAX(parent_column.p99)
• 对于直方图的吞吐量：使用 SUM(parent_column.count) 或 AVG(parent_column.count)

使用指标进行查询数学运算

查询数学运算（包含命名计算和公式的复合查询）在指标数据集上的工作方式与在事件数据集上的相同。为计算命名，根据需要添加单项计算的筛选条件，并定义公式将它们组合起来。

常见指标公式模式：

利用率百分比

{
  "calculations": [
    { "op": "AVG", "column": "k8s.pod.memory.usage", "name": "used" },
    { "op": "AVG", "column": "k8s.pod.memory.available", "name": "available" }
  ],
  "formulas": [
    { "name": "utilization_pct", "expression": "$used / ($used + $available) * 100" }
  ],
  "breakdowns": ["k8s.pod.name"],
  "orders": [{ "column": "utilization_pct", "order": "descending" }],
  "limit": 20
}

直方图尾部比率

{
  "calculations": [
    { "op": "P50", "column": "http.server.duration", "name": "median" },
    { "op": "P99", "column": "http.server.duration", "name": "tail" }
  ],
  "formulas": [
    { "name": "tail_ratio", "expression": "$tail / $median" }
  ],
  "breakdowns": ["service.name"]
}

计数器的错误率（覆盖时间聚合）

{
  "calculated_fields": [
    { "name": "error_rate", "expression": "RATE($http.server.errors)" },
    { "name": "request_rate", "expression": "RATE($http.server.requests)" }
  ],
  "calculations": [
    { "op": "SUM", "column": "error_rate", "name": "errors_per_sec" },
    { "op": "SUM", "column": "request_rate", "name": "requests_per_sec" }
  ],
  "formulas": [
    { "name": "error_pct", "expression": "$errors_per_sec / $requests_per_sec * 100" }
  ]
}

如需查看更多查询示例，请参阅： ${CLAUDE_PLUGIN_ROOT}/skills/metrics-queries/references/metrics-query-examples.md

指标的粒度

指标以已知的固定间隔（例如每 10s、30s 或 60s）上报。与跟踪相比，粒度对指标的影响更大：

• 让粒度与上报间隔保持一致。 如果指标每 60 秒上报一次，请使用能被 60 整除的粒度（例如 60、120、300）。粒度不匹配会导致数据桶大小不均，从而产生嘈杂的结果。
• 图表看起来有尖峰通常意味着粒度小于上报间隔。增大粒度，或在 UI 中启用“Omit Missing Values”，以生成连续的线条。
• RATE 操作与粒度：RATE_SUM（用于事件数据集）对粒度的选择尤其敏感——每个数据桶中的数据点数量不一致会导致结果不稳定。

常见问题

1. 在指标上使用 COUNT。COUNT 统计的是指标事件的数量，而非指标值。请改用 AVG、SUM、MAX 或 HEATMAP。
2. **在指标数据集上使用 RATE_AVG/RATE_SUM/RATE_MAX。**这些函数不允许使用。要获取速率，请使用包含 RATE($metric) 的计算字段，然后应用 AVG 或 SUM 等空间聚合。
3. **假设所有指标都具有相同的属性。**每个指标都有各自的资源属性和数据点属性。添加筛选条件或细分之前，请务必调用 get_dataset_columns 并传入 metric_name，以查明特定指标可用的属性。
4. **混淆事件数据集与指标数据集。**名为 kafka-metrics、refinery-metrics 等的数据集都是事件数据集。请检查 get_environment 返回的 dataset_type。
5. **在父列可用时查询直方图子字段。**请使用 P99(http.server.duration)，而不是 AVG(http.server.duration.p99)，除非你确实需要最坏情况边界。
6. **未指定聚合函数。**如果 SELECT 中没有空间聚合，指标查询默认使用 COUNT，这对指标没有意义。

其他资源

参考文件

• ${CLAUDE_PLUGIN_ROOT}/skills/metrics-queries/references/metrics-query-examples.md — 指标查询手册，包含适用于常见场景的 run_query 示例
• ${CLAUDE_PLUGIN_ROOT}/skills/metrics-queries/references/temporal-aggregation.md — 关于时间聚合函数、计数器重置和 range_interval_seconds 的深入参考
• ${CLAUDE_PLUGIN_ROOT}/skills/metrics-queries/references/metric-types.md — OpenTelemetry 指标类型、它们如何映射到 Honeycomb，以及 MetricInfo 值的含义

交叉引用

• 有关通用查询构建模式（计算字段、关系字段、结果解读）：query-patterns 技能
• 有关结合指标与跟踪调查生产问题：production-investigation 技能
• 有关 SLO 解读和燃烧告警设计：slos-and-triggers 技能
• 有关为应用程序添加检测以发送指标：otel-instrumentation 技能