Skip to content

feat(metrics): metrics query runs an ad-hoc timeseries query - #244

Merged
Severin Neumann (svrnm) merged 2 commits into
mainfrom
feat/metrics-query
Nov 11, 2026
Merged

Severin Neumann (svrnm) merged 2 commits into
mainfrom
feat/metrics-query

Conversation

@svrnm

Copy link
Copy Markdown
Contributor

Completes the remaining half of #189: ad-hoc POST /timeseries/search. The per-metric half (GET /timeseries/{id}) shipped in #205. Nothing from the issue is left, so:

Closes #189

Command

bronto metrics query --select 'p95(Span:duration_nano)' -d .traces/checkout-service \
  --where "Span:kind = 'SPAN_KIND_SERVER'" --group-by Span:name --since 1h
bronto metrics query --select duration_ms --agg max -d prod/checkout-service
bronto metrics query --input body.json      # {"queries": [...], "formulas": [...]}
  • Why metrics query: it sits next to metrics definitions query and metrics top-keys, and it runs the same kind of query unsaved. Its flags are the fields one manifest/definition query holds (--select, -d/--from-expr, --where, --group-by, --agg), with the names search already uses. --input takes a full body for several queries or formulas. That is the same queries/formulas a metric definition holds, so a definition JSON works as-is.
  • Reused code, not new machinery:
    • The flags fill a manQuery, and manQuery.resolve (the code dashboard manifests use) builds the API query: the dataset becomes from_expr, and the aggregation defaults from the select.
    • The time flags are timeseriesFlags, and the output goes through printTimeseries.
    • Formula range values come from queryDefinition's one-slice logic, which now sits in a shared querySeries behind a fetch func.
    • printTimeseries takes the window string and a "what to check" hint, so the all-zero warning doesn't point ad-hoc users at definitions get.
  • Precedence with --input: time flags you set override the body's time_range/num_of_slices/limit, and the body's values beat the flag defaults. This is the same rule as search --saved.
  • Errors teach the fix (usage_invalid_flags, exit 2), for a missing --select, a missing dataset, -d together with --from-expr, a bare field without --agg, an unknown --agg, or more than 5 group keys. Each error names the flag that fixes it. Combining --input with the query flags gives usage_conflicting_flags, and an --input body with no queries gives usage_invalid_body.
  • --dry-run: the query still runs under --dry-run, as in dashboards validate --live, because the POST saves nothing.

Spec / #233

#233 re-vendors the spec. For this endpoint it adds only error-response examples, and MetricQuery.from_expr loses its maxLength: 255. SearchTimeseries, the request body and the 200 response are unchanged, so this PR builds on main, not on chore/spec-revendor-2702ae33.

Tests

  • Unit tests (internal/cli/metricdefs_test.go, fake server via runResource):
    • The exact request body built from the flags.
    • --input precedence and the formula range-value second call.
    • Every usage error, with no request made.
  • Inventories updated: endpoint probe, /logs and /timeseries/search mappings, and the telemetry class for --agg.
  • go test ./... passes and make lint reports 0 issues.
  • Live: TestMetricDefinitionsLive now also runs metrics query over the seeded spans once they are visible, and asserts a count of 2. That adds one request to the suite and seeds nothing new. It runs in CI's integration job.

Docs

  • A paragraph and examples in the dashboards guide.
  • A row in the resources guide's command table.
  • skill.md.
  • The regenerated metrics.mdx reference.

🤖 Generated with Claude Code

bronto metrics query runs POST /timeseries/search once, saving nothing,
and prints the same series table as metrics definitions query. One
query from --select, -d/--from-expr, --where, --group-by and --agg (built
by the manifest's query resolver), or a whole body with --input. Formula
range values reuse the definition query's one-slice request.

Assisted-By: Claude
Copilot AI balanced review requested due to automatic review settings November 11, 2026 06:58
@svrnm
Severin Neumann (svrnm) enabled auto-merge (squash) November 11, 2026 07:02

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Explicit --limit 0 can send an invalid request, and conflicting --select and --agg values can silently return the wrong aggregation.

2 open issues
What changed in this PR

Adds bronto metrics query for ad-hoc timeseries queries without saving a metric definition, completing the remaining scope of #189 alongside the saved-definition queries introduced in #205.

Changes:

  • Supports flag-based queries and JSON request bodies, with explicit time flags overriding body values.
  • Reuses timeseries output and formula range-value handling across query commands.
  • Adds unit and integration coverage, endpoint mappings, telemetry classification, and documentation.
File Description
skill.md Documents ad-hoc queries and output behavior for agents.
internal/​cli/​telemetryargs.go Classifies the new --agg flag for telemetry.
internal/​cli/​root.go Registers metrics query.
internal/​cli/​metricdefs.go Implements ad-hoc queries and shares timeseries processing.
internal/​cli/​metricdefs_test.go Tests request construction, precedence, formulas, and validation.
internal/​cli/​endpoints.go Maps endpoints to the new command.
internal/​cli/​endpoints_test.go Adds an endpoint probe for metrics query.
integration/​metric_definitions_test.go Checks ad-hoc queries against seeded trace data.
docs/​cli/​reference/​commands/​metrics.mdx Adds generated command help, flags, and examples.
docs/​cli/​guides/​resources.mdx Lists the new query command.
docs/​cli/​guides/​monitors-and-dashboards.mdx Explains querying before saving a definition.

Review effort: Balanced

Comment thread internal/cli/metricdefs.go Resolved
Comment thread internal/cli/metricdefs.go Resolved
@svrnm
Severin Neumann (svrnm) merged commit 1726607 into main Nov 11, 2026
25 of 26 checks passed
@svrnm
Severin Neumann (svrnm) deleted the feat/metrics-query branch November 11, 2026 07:15

This branch was successfully deployed

1 active deployment
bronto-it — 7a902ea1 Deployed Nov 11, 2026 by svrnm via integration #457
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Timeseries queries: ad-hoc and per-metric

2 participants