Query Usage Analyzer

The Query Analyzer gives you insight into how metrics is used across your observability environment.

It helps you explore query patterns, track usage frequency, and identify where metrics is queried, so you can optimize cost, clean up unused data, and focus on what matters.

You can access Query Analyzer under Settings > Metric Data > Usage Analysis > Queries

Why it matters

Over time, organizations collect large numbers of metrics, many of which might never be queried again.

The Query Analyzer helps you:

Identify high-value metrics versus rarely used or unused ones.
Detect redundant queries that increase cost or cardinality.
Understand which dashboards, alerts, or APIs use a given metric.
Support data hygiene and cost optimization decisions.

Key capabilities

Feature	Description
Query pattern parsing	Normalizes queries by replacing variable values with `$var` to group similar queries and reduce label noise.
Usage frequency tracking	Displays the number of times each query pattern was executed.
Status tracking	Shows success and failure percentages for query executions, helping identify errors or invalid queries.
Query context	Lists where queries originated (for example, Alerts, Recording Rules, API).
Date selection	View query activity for a specific date using the date selector in the top-right corner.
Comprehensive search	Filter query patterns by keyword or location.

How It works

Each metric query run in the platform is parsed, normalized, and logged before execution.

This ensures every query, successful or failed, is counted.

Capture: The system intercepts PromQL queries before execution.

Parse: Variable values are replaced with $var placeholders. Example:

http_requests_total{job="apiserver", handler="/api/comments"}
→ http_requests_total{job=$var, handler=$var}

Aggregate: Query usage counts are rolled up daily by query pattern.
Display: The dashboard visualizes aggregated statistics like frequency, cardinality, and units.
Contextualize: (In future phases) the platform will capture the client source automatically (e.g., Dashboard, Alert, API).

Using the Query Analyzer

Navigate to Settings > Metric Data > Usage Analysis > Queries.
The Queries tab lists all query patterns run across your environment.
Use the date selector in the top-right corner to view activity for a specific day.
Review the table columns:

Column	Description
Query Pattern	Normalized query pattern with `$var` placeholders.
# Times Used	Shows how many times this query pattern runs on the selected date.
Last Run	The most recent timestamp for that query pattern.
Status	Success and failure rates for that pattern (for example, `100% (7,560)` success, `0% (0)` failed).
Location	The feature or component where the query ran (for example, Alerts, Recording Rules).
1. Use the search bar to find queries by name or label.
2. Use the location filter to narrow down results by query origin.
3. Hover over the Last Updated timestamp to confirm data freshness, or use Share to copy a link to your filtered view.

Example: from raw query to pattern

Raw Query	Parsed Pattern	Count	Location
`avg(cpu_usage{instance="server1"}[30m]) - avg(cpu_usage{instance="server2"}[30m] offset 1h)`	`avg(cpu_usage{instance=$var}[30m]) - avg(cpu_usage{instance=$var}[30m] offset $var)`	12,421	Alerts

This example groups two similar queries into one pattern, making total usage easier to see.

Interpreting results

Scenario	What It Means	Action
High usage count	Metric is actively queried and likely important.	Keep and monitor performance.
Low or zero usage	Metric is rarely or never used.	Review dashboards and alerts to confirm whether you can drop the metric.
Frequent queries from Alerts	Metric is operationally critical.	Prioritize retention and optimization.
High cardinality with low query frequency	Potentially wasteful metric.	Investigate label usage and aggregation strategies.

Limitations

Supports PromQL queries only.
Client context (for example, Dashboard, API, Alert) might not appear in all cases.
Can only analyze one day at a time, not a range of days.

Best practices

Use Query Usage Analyzer periodically to identify query patterns across different sources in one place, along with their usage and success rates, to help clean up unused metrics.
Correlate high-usage queries with ingestion data for cost analysis.
Before removing a metric, verify that no critical dashboards or alerts depend on it.

Troubleshooting

Issue	Possible Cause	Solution
Query not shown	Query hasn’t run on the selected day	Change the day.
Missing location data	Client context not yet captured in Phase 1.	Available in later releases.
high query counts	Same query pattern runs with many label variations.	Parsing is automatic; for now, infer details from the query pattern. Soon, you’ll be able to enable raw query logs for any selected pattern.

Previous Metric Usage Analysis

Next Metrics Cost Optimizer