metrics-queries
How to query OpenTelemetry metrics datasets in Honeycomb correctly. Metrics datasets follow different rules from trace/event datasets — many operations (bare COUNT, RATE_SUM, RATE_AVG, RATE_MAX, CONCURRENCY) are forbidden, temporal aggregation is automatic, and each metric has its own attributes. Use this skill when querying a metrics dataset (gauges, counters, histograms, sums), asking about temporal aggregation (RATE, INCREASE, SUMMARIZE, LAST), finding the metrics dataset or discovering metric names and attributes, debugging unexpected metrics query results, or querying infrastructure metrics like CPU, memory, disk I/O, or network stats. Do NOT use for instrumenting metrics (use otel-instrumentation), querying event datasets with "metrics" in their name, or conceptual questions (use observability-fundamentals).
honeycombio · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add honeycombio/agent-skill --skill metrics-queries技能说明
name: metrics-queries description: > How to query OpenTelemetry metrics datasets in Honeycomb correctly. Metrics datasets follow different rules from trace/event datasets — many operations (bare COUNT, RATE_SUM, RATE_AVG, RATE_MAX, CONCURRENCY) are forbidden, temporal aggregation is automatic, and each metric has its own attributes. Use this skill when querying a metrics dataset (gauges, counters, histograms, sums), asking about temporal aggregation (RATE, INCREASE, SUMMARIZE, LAST), finding the metrics dataset or discovering metric names and attributes, debugging unexpected metrics query results, or querying infrastructure metrics like CPU, memory, disk I/O, or network stats. Do NOT use for instrumenting metrics (use otel-instrumentation), querying event datasets with "metrics" in their name, or conceptual questions (use observability-fundamentals). metadata: version: "1.0.0"
Querying Metrics in Honeycomb
Metrics datasets in Honeycomb behave differently from tracing/event datasets. Operations that work on traces may fail or produce misleading results on metrics. This skill covers those differences so you construct correct, useful metrics queries.
Finding the Metrics Dataset
Metrics datasets are not identified by having "metrics" in their name. Many event
datasets contain "metrics" in their slug (e.g., kafka-metrics, refinery-metrics,
kubernetes-node-metrics). These are ordinary event datasets, not metrics datasets.
How to identify the real metrics dataset:
- Call
get_environmentand look for rows wheredataset_type=metrics. The slug is typicallymetricsbut may differ per environment. - Alternatively, call
get_dataset_columnson a candidate dataset — metrics datasets return aMetricInfocolumn showing type metadata likegauge,sum(cumulative,monotonic), orhistogram(delta). Event datasets do not have this.
Do not guess the dataset. Always verify via get_environment or get_dataset_columns
before constructing a metrics query. If the user says "metrics" but means an event dataset
with metrics-like fields (e.g., telegraf, system_stats), the query rules below do not apply —
those are event datasets and follow normal query patterns from the query-patterns skill.
Discovering Metrics and Their Attributes
Metrics datasets have a fundamentally different schema from event datasets. Each metric has its own set of resource and data point attributes. Two metrics in the same dataset may have completely different attributes available for filtering and grouping.
Workflow for discovering what to query:
-
Find metric names: Call
get_dataset_columnson the metrics dataset (withoutmetric_name). This returns metric names with their types inMetricInfo. Usefind_columnswith keywords to search for specific metrics (e.g., "cpu", "memory", "http request duration"). -
Find attributes for a specific metric: Call
get_dataset_columnswith themetric_nameparameter set to the metric you want to query (e.g.,metric_name: "k8s.pod.memory.usage"). This returns the resource attributes and data point attributes that co-occur with that metric, along with sample values. These are what you can use in WHERE and GROUP BY clauses. -
Validate before querying: Not all attributes exist on all metrics. Always use step 2 to confirm available attributes before adding them to filters or breakdowns.
Allowed vs. Forbidden Operations on Metrics Datasets
The following operations are NOT allowed on metrics datasets:
| Forbidden Operation | Why |
|---|---|
COUNT (without column) | Counts metric events, not metric values — meaningless for metrics |
RATE_SUM | Not supported on metrics datasets |
RATE_AVG | Not supported on metrics datasets |
RATE_MAX | Not supported on metrics datasets |
CONCURRENCY | Requires span duration; metrics have no duration |
Use these instead:
| Goal | Use on Metrics |
|---|---|
| Visualize a gauge value | AVG(metric), MAX(metric), HEATMAP(metric) |
| Visualize a counter/sum | SUM(metric), AVG(metric), MAX(metric) |
| See distribution of values | HEATMAP(metric), P50(metric), P99(metric) |
| Track per-second rate of change | Override temporal aggregation with a calculated field (see below) |
| Percentile analysis | P50(metric), P90(metric), P99(metric) |
| Count of non-null values | COUNT(metric) (with a column specified) |
Metric Types and Temporal Aggregation
Honeycomb automatically applies temporal aggregation to align raw metric values into
query time steps. The function it applies depends on the metric type, visible in the
MetricInfo column from get_dataset_columns.
Default Temporal Aggregation by Metric Type
| MetricInfo | Type | Default Function | What It Does |
|---|---|---|---|
gauge | Gauge | LAST() | Returns most recent value per time step |
sum(cumulative,monotonic) | Monotonic cumulative sum | INCREASE() | Change between steps, handles counter resets |
sum(cumulative) | Non-monotonic cumulative sum | LAST() | Most recent value (can go up or down) |
sum(delta) or sum(delta,monotonic) | Delta sum | SUMMARIZE() | Sums all values in each step |
histogram(cumulative) | Cumulative histogram | INCREASE() | Change per bucket between steps |
histogram(delta) | Delta histogram | SUMMARIZE() | Sums bucket values in each step |
These defaults are applied automatically — you do not need to configure them.
The results you see from AVG, MAX, P99, etc. on a metrics dataset already
reflect temporal aggregation having been applied first.
Overriding Temporal Aggregation
To override the default (e.g., to see RATE instead of INCREASE for a cumulative counter), use a query-scoped calculated field wrapping the metric name in a temporal aggregati
阅读完整来源 ↗