Skip to content

fix(hints): shorten generic empty-query guidance - #1336

Open
jpdefo wants to merge 3 commits into
grafana:mainfrom
jpdefo:codex/concise-empty-query-hints
Open

jpdefo wants to merge 3 commits into
grafana:mainfrom
jpdefo:codex/concise-empty-query-hints

Conversation

@jpdefo

@jpdefo jpdefo commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

What this changes

Shorten generic empty-result guidance for Prometheus and Loki while preserving discovery-tool pointers, time-range advice, scrape target health, query-specific hints and debugging metadata. run_panel_query now reuses the same Prometheus/Loki generator while retaining its existing hints array and query preview.

The generic serialized hints shrink from 615 to 356 bytes for Prometheus and from 614 to 343 bytes for Loki, excluding optional debug metadata. Tests enforce a 400-byte budget for these two generic cases and a separate 650-byte allowance for representative query-specific guidance. Other datasource hint generators remain outside this PR's scope.

  • Keep target-health guidance through up{job="..."} and a generic Loki filter cause that also covers labels filtered after a parser.
  • Keep separate action entries and avoid repeating the Loki label-values tool for regex queries.
  • Consolidate budget tests into the existing hints test file and cover rate queries, parser/line filters, parsed label filters and regex selectors.
  • No tool schemas, backend requests or query semantics change.

Related to #1279, specifically item 2. Cause detection and machine-readable reasons remain follow-up work.

How you tested it

  • Full unit suite: go test -tags unit ./... on Windows with Go 1.26.9.
  • Go lint v2.14.0, JSON-schema and OpenAPI linters, formatting, diff checks and build pass.
  • Focused hint and panel-hint tests pass, including query-specific guidance and generic/enriched byte budgets.
  • The combined source of all four current contribution branches plus upstream main passes unit tests, Go lint and build.
  • Two independent final reviews found no actionable issues.
  • Token analysis with mcp-tokens v0.2.5 and tiktoken/gpt-4o: 20,714 to 20,714 (+0%). This measures tool declarations, separately from the response-byte savings above.

No live datasource or Docker integration tests were rerun for this response-text change. Validation used canonical LF checkout content to avoid the existing Windows CRLF README comparison failure.

Checklist

  • Local lint and unit checks pass
  • No new tools or permission changes
  • Existing response fields retained
  • Signed commit and CLA verified

@jpdefo
jpdefo requested a review from a team as a code owner October 14, 2026 03:47

@sd2k sd2k left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Thanks for trimming these. A few notes inline: mostly about diagnostics that got dropped along the way, plus test coverage.

One point that falls outside the diff: generatePanelQueryHints in tools/run_panel_query.go is a separate empty-result hint generator. It still returns the long multi-line Prometheus/Loki guidance, so run_panel_query doesn't benefit from this change, and its wording now differs from query_prometheus/query_loki_logs. It might be worth having it reuse GenerateEmptyResultHints so there's only one source.

Comment thread tools/hints.go Outdated
Comment thread tools/hints.go Outdated
Comment thread tools/hints.go Outdated
Comment thread tools/hints.go Outdated
Comment thread tools/hints_concise_test.go Outdated
Comment thread tools/hints_concise_test.go Outdated
Comment thread tools/hints_concise_test.go Outdated
Comment thread tools/hints_concise_test.go Outdated
@jpdefo

jpdefo commented Oct 19, 2026

Copy link
Copy Markdown
Contributor Author

cursor review

@cursor cursor Bot 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.

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit d2166dc. Configure here.

This branch has not been deployed

No deployments
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.

2 participants