Prometheus

Connect Prometheus, Thanos, VictoriaMetrics, or Grafana Cloud for read-only PromQL queries, metric discovery, target health, and alert inspection

Connect your Prometheus-compatible monitoring backend to enable CloudThinker agents to run PromQL queries, discover metrics and labels, inspect scrape-target health, and correlate active alerts — all read-only.

The connector works with any backend that speaks the standard Prometheus HTTP API: self-hosted Prometheus, Thanos, VictoriaMetrics, and Grafana Cloud. Authentication supports None, Bearer Token, and Basic Auth.

---

Supported platforms

Platform	Support	Typical auth
Prometheus	Self-hosted, all recent releases	None or Bearer
Thanos	Querier behind an auth proxy	None, Bearer, or Basic
VictoriaMetrics	Single-node and cluster	None or Basic
Grafana Cloud	Prometheus / Mimir endpoint	Basic

Against managed, Mimir-backed endpoints (Grafana Cloud), the /api/v1/targets, /rules, and /alerts paths are not exposed and return 404. This is expected — the query API (instant queries, range queries, labels, and metadata) works normally.

---

Prerequisites

• A Prometheus-compatible endpoint reachable from CloudThinker over HTTPS — self-hosted Prometheus, Thanos, VictoriaMetrics, or Grafana Cloud.
• Credentials if the endpoint requires authentication: a bearer token (Bearer Token mode) or a username and password (Basic Auth mode).
• For Grafana Cloud, the numeric instance ID and an access-policy token with the metrics:read scope.

---

Choosing an auth mode

Pick the mode that matches how your endpoint is exposed:

Mode	When to use	Fields
None	Open or network-restricted endpoint (self-hosted Prometheus inside a private network)	URL only
Bearer Token	Endpoint behind a proxy or gateway that expects Authorization: Bearer <token>	URL + token
Basic Auth	Grafana Cloud, Thanos behind an auth proxy, or VictoriaMetrics with username/password	URL + username + password

For Grafana Cloud, the username is your numeric instance ID and the password is an access-policy token with metrics read scope.

---

Setup

1. Find your Prometheus URL

   Identify the base URL of your Prometheus HTTP API, e.g. https://prometheus.your-domain.com or your Grafana Cloud Prometheus query endpoint. CloudThinker appends the standard /api/v1/... paths.

2. Prepare credentials (if required)

   • None — nothing to prepare; the endpoint is reachable without auth.
   • Bearer Token — obtain the bearer token your proxy or gateway expects.
   • Basic Auth — obtain the username and password (for Grafana Cloud, the numeric instance ID and an access-policy token).
3. Add connection in CloudThinker

   Navigate to Connections → Prometheus and enter:

   • PROMETHEUS_URL: your endpoint, e.g. https://prometheus.your-domain.com
   • PROMETHEUS_AUTH_TYPE: select None, Bearer Token, or Basic Auth

   The credential fields appear based on your selection:

   • Bearer Token → PROMETHEUS_TOKEN
   • Basic Auth → PROMETHEUS_USERNAME and PROMETHEUS_PASSWORD

   Click Connect. CloudThinker verifies the endpoint and shows a Connected status.

---

Connection details

Field	Description	Example
PROMETHEUS_URL	Base URL of the Prometheus HTTP API	https://prometheus.your-domain.com
PROMETHEUS_AUTH_TYPE	Authentication mode: none, bearer, or basic	basic
PROMETHEUS_TOKEN	Bearer token (Bearer Token mode only)	eyJhbGci...
PROMETHEUS_USERNAME	Username, or numeric instance ID for Grafana Cloud (Basic Auth only)	1234567
PROMETHEUS_PASSWORD	Password or access-policy token (Basic Auth only)	glc_xxxxx...

---

Required permissions

The Prometheus connector is read-only — agents query and inspect but never write to your monitoring backend.

• For Grafana Cloud, create an access-policy token with the metrics:read scope only.
• For protected endpoints, ensure the credentials can reach the query, labels, targets, rules, and alerts API paths.

On Grafana Cloud, scope the access-policy token to metrics:read only — no other scope is needed for CloudThinker.

---

Agent capabilities

The Prometheus connector is read-only — agents query and inspect, but never modify your monitoring backend.

Capability	What the agent can do
Instant queries	Run a PromQL expression for a single point in time
Range queries	Run a PromQL expression over a time window with a step interval
Metric discovery	List available metric names, optionally filtered by prefix
Label enumeration	List label names and inspect the dimensions a metric is sliced by
Target health	Inspect scrape targets and spot ones that are down or unhealthy
Alert inspection	List active alerts and review configured alert rules
Health probe	Run the universal up query to confirm the backend and its targets are reachable

Verify the connection

@alex run the Prometheus health probe and confirm all scrape targets are reachable

Example prompts

@alex query node_cpu utilization across the cluster for the last hour and #report anything sustained above 85%
@kai list scrape targets that are currently down and #report which jobs they belong to
@alex show all active alerts and #recommend which to investigate first

Prometheus exposes no tool for label values — label enumeration returns label names only. Name the metric and the labels you care about so the agent can build an accurate PromQL selector.

---

Troubleshooting

Connection or query fails with 401 Unauthorized

• Confirm PROMETHEUS_AUTH_TYPE matches what the endpoint expects.
• For Bearer, verify the token is current and has not been revoked.
• For Basic, verify the username/password — on Grafana Cloud, the username is the numeric instance ID and the password is the access-policy token.

Targets, rules, or alerts return 404

• Expected on managed, Mimir-backed endpoints (Grafana Cloud) — these paths are not exposed.
• The query API (instant, range, labels, metadata) still works; use queries instead of target/rule inspection.

Connection fails to reach the endpoint

• Verify PROMETHEUS_URL is reachable from CloudThinker over HTTPS.
• For self-hosted or network-restricted endpoints, confirm there’s a network path from CloudThinker.
• Drop any trailing /api/v1 from the URL — enter only the base URL.

A query returns empty results

• Confirm the metric exists with a discovery query before slicing by labels.
• Widen the time window — the series may not have samples in the requested range.

---

Security

• Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
• Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
• Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
• Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.

• Read-only by design — the connector never writes to your monitoring backend; no write permissions are needed
• Least-privilege credentials — on Grafana Cloud, scope the access-policy token to metrics read only

---

Related

Grafana Connection

Dashboards and unified observability

Datadog Connection

Log search, metrics, and infrastructure monitoring