Skip to content

Add bounded privacy-aware Prometheus diagnostics - #13

Merged
YangYuS8 merged 25 commits into
mainfrom
agent/prometheus-readonly-diagnostics
Jul 16, 2026
Merged

Add bounded privacy-aware Prometheus diagnostics#13
YangYuS8 merged 25 commits into
mainfrom
agent/prometheus-readonly-diagnostics

Conversation

@YangYuS8

@YangYuS8 YangYuS8 commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

What changed

  • adds a lazy standard-library Prometheus /api/v1 client without adding third-party dependencies
  • adds prometheus_server_info for bounded build and runtime diagnostics
  • adds prometheus_target_list for bounded active-target health summaries
  • adds prometheus_metric_snapshot for constrained instant metric snapshots
  • exposes all three tools through the shared Registry, CLI, Ark Agent, and MCP server
  • keeps OpsPilot on Go 1.26.5

Query boundary

prometheus_metric_snapshot does not accept arbitrary PromQL. OpsPilot generates the expression from:

  • one validated ASCII metric name
  • up to eight exact-match labels from a fixed diagnostic allowlist
  • optional sum, avg, min, max, or count aggregation
  • up to five allowlisted grouping labels
  • a hard series limit

Regular expressions, range vectors, subqueries, offsets, functions, arbitrary labels, arbitrary paths, and user-supplied PromQL are not interfaces. Metric queries use Prometheus's URL-encoded POST form so matcher values do not appear in request URLs.

Configuration and transport safety

  • initialization is lazy, so missing Prometheus configuration does not block MCP startup or unrelated tools
  • HTTPS is required by default; HTTP requires OPSPILOT_PROMETHEUS_ALLOW_HTTP=true
  • URL user information, query strings, fragments, redirects, and ambient proxies are rejected or disabled
  • HTTPS requires TLS 1.2 or newer
  • optional bearer authentication uses a bounded absolute token file that is read for every request to support rotation
  • only fixed build-info, runtime-info, active-target, and instant-query endpoints are implemented
  • configuration, flags, rules, alerts, label/series enumeration, administration, and arbitrary API paths are not exposed

Privacy boundary

Raw Prometheus API data is never returned. The projection omits:

  • scrape and global URLs
  • discovered labels
  • arbitrary target and metric labels
  • target error text
  • runtime hostname and working directory
  • API warning and info text
  • raw API and HTTP error bodies
  • bearer-token values

Target errors are represented by error_present. API warnings and infos are represented by counts only. Metric labels are restricted to job, instance, cluster, namespace, pod, container, node, service, and endpoint.

Bounds and response validation

  • request timeout, Prometheus query timeout, response bytes, target count, and series count are bounded
  • target and series limits are enforced locally even if the server returns more data
  • only instant vector results are accepted
  • malformed values, unexpected result types, oversized responses, non-finite timestamps, and timestamps outside the RFC3339 year range are rejected
  • explicit zero and out-of-range tool limits are rejected rather than silently treated as defaults

Validation

  • clean go mod tidy with no module-file changes
  • clean gofmt
  • go vet ./...
  • go test -race -coverprofile=coverage.out ./...
  • go build ./cmd/opspilot
  • HTTP tests cover fixed endpoints, GET/POST method selection, POST form encoding, token headers, redirects, timeouts, cancellation, response limits, status errors, API errors, and safe URL prefixes
  • privacy tests inject scrape URLs, credentials, discovered labels, arbitrary labels, target errors, runtime host paths, warnings, infos, and raw error details and verify they never enter results
  • query tests cover deterministic selector generation, escaping, allowlists, aggregations, grouping, limits, label filtering, vector sorting, and invalid shapes
  • timestamp tests cover fractional seconds, NaN, infinities, and out-of-range values
  • Registry tests verify Prometheus tools remain lazily discoverable without configured credentials

YangYuS8 and others added 25 commits July 16, 2026 14:37
@YangYuS8
YangYuS8 marked this pull request as ready for review July 16, 2026 07:58
@YangYuS8
YangYuS8 merged commit 9bde1e7 into main Jul 16, 2026
1 check passed
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.

1 participant