Prometheus Connector

1. Overview

The Ana x Prometheus integration connects your metrics backend to Ana, giving you natural language access to your time series. Prometheus is not a SQL database, so Ana queries it with native PromQL rather than SQL — metrics appear as tables, their labels appear as columns, and results come back as one row per timestamp and series. Because the query API is a shared standard, one connector covers Prometheus, Thanos, Grafana Mimir, Cortex, VictoriaMetrics, Grafana Cloud, and Amazon Managed Prometheus.

Connect Prometheus to Ana to investigate incidents, track SLOs, and correlate infrastructure metrics with your business data using natural language.

2. Prerequisites

You’ll need:

A Prometheus-compatible server that Ana can reach over HTTP or HTTPS
Credentials for it, if it sits behind authentication
A TextQL account with permission to add connectors

Ana must be able to reach your server over the network. Metrics endpoints on private networks are blocked by default — see Reaching a private server below before you start.

Which authentication method should I use?

	When to use it	What you provide
None	A server already protected by network policy or a mesh	Nothing
Basic auth	Grafana Cloud, or a reverse proxy with htpasswd	Username and password. For Grafana Cloud the username is your numeric instance ID and the password is an API token
Bearer token	Most authenticating proxies, and Kubernetes service-account tokens	The token
AWS SigV4	Amazon Managed Prometheus	AWS region, and an IAM role ARN to assume

3. Capabilities

Once configured, Ana can:

Answer questions about any metric in plain language and return the results as a table.
Run range queries over any window, picking a sensible resolution automatically.
Read each metric’s type, so it knows a counter needs rate() and a histogram needs histogram_quantile().
Explore what exists — list metrics, labels, and label values — without you knowing the names up front.
Load the results into Python, so metrics can be joined against warehouse data in the same thread.

4. Setup Instructions

Step 1: Find your server URL

The URL is the base of the query API, including any path prefix. Ana appends /api/v1/... to it.

Self-hosted
Grafana Cloud
Amazon Managed Prometheus
Mimir / Cortex

Use the address your Prometheus UI is served from, with no trailing path:

https://prometheus.example.com

If Prometheus runs behind a proxy at a sub-path, include it:

https://observability.example.com/prometheus

Go to grafana.com and sign in.
Open your stack, then Details on the Prometheus tile.

Copy the Query endpoint, which looks like:

https://prometheus-prod-01-eu-west-0.grafana.net/api/prom

Note the Username / Instance ID shown next to it, and create an API token for the password.

Choose Basic auth in the connector form, and use the instance ID as the username.

Open the AMP console and select your workspace.

Copy the Endpoint - query URL, then remove the trailing /api/v1/query:

https://aps-workspaces.us-east-1.amazonaws.com/workspaces/ws-abc123

Create an IAM role Ana can assume that grants aps:QueryMetrics, aps:GetLabels, aps:GetSeries, and aps:GetMetricMetadata on the workspace.

Choose AWS SigV4 in the connector form and supply the region and role ARN.

Use your query frontend address, and set Tenant ID to the value you would send as X-Scope-OrgID:

https://mimir.example.com/prometheus

Step 2: Scope the connector with metric selectors

This is the single most important setting. A production Prometheus can expose tens of thousands of metric names, and discovering all of them is slow and floods Ana’s context with metrics nobody asks about. In Metric Selectors, add one PromQL selector per line:

{job="api"}
{__name__=~"http_.*"}
{namespace="checkout"}

Only metrics matching at least one selector are discovered. Leave it empty only on small servers.

Discovery Window works alongside this. It defaults to 24 hours, and metrics with no samples in that window are hidden — which quietly removes metrics from decommissioned services.

Step 3: Create the connector

In TextQL, go to Connectors and click New Connector.
Choose Prometheus.
Fill in the name, server URL, and authentication.
Add your metric selectors.
Click Test Connection, then Save.

5. How Ana queries Prometheus

Ana writes PromQL, not SQL. It has a few extra verbs for things PromQL alone cannot express:

What Ana writes	What it does
`sum(rate(http_requests_total[5m]))`	A single point at the current time
`query_range(<promql>, -6h, now, 1m)`	A series over a window, which is what charts and trends need
`rate(x[5m])[6h:1m]`	Same as above — Ana rewrites this into an efficient range query
`show metrics`	Lists every discovered metric with its type, unit, and description
`label_values(job)`	Lists the values of a label
`series({job="api"})`	Lists the label sets of matching series

Results always come back with a timestamp column, a metric column, one column per label, and a value column.

Reaching a private server

Most Prometheus deployments listen on a private address — a Kubernetes ClusterIP such as prometheus-operated.monitoring.svc, or an internal load balancer. TextQL refuses connections to private, loopback, and link-local addresses by default, because a connector that accepts an arbitrary URL is otherwise an easy way to reach cloud metadata endpoints. You have two options:

SSH tunnel (recommended)
Allowlist the host

Enable Connect via SSH tunnel in the connector form and point it at a bastion host that can reach Prometheus. Ana connects to the bastion and forwards from there, so nothing needs to be exposed publicly.Paste the bastion’s host public key as well. Without it the host’s identity is not verified.

For self-hosted TextQL, an administrator can add the hostname to SSRF_TRUSTED_HOSTS, or its network to SSRF_ALLOWED_CIDRS, in the compute engine’s environment. Both accept comma-separated values, and SSRF_TRUSTED_HOSTS accepts wildcards such as *.monitoring.svc.This applies to the whole deployment, not one connector, so prefer the tunnel when only one connector needs it.

6. Troubleshooting

Symptom	Cause and fix
`connection to "..." blocked`	The server resolves to a private address. See Reaching a private server.
`prometheus url must not embed credentials`	The URL contains `user:password@`. Remove it and use the username and password fields, which are stored encrypted.
`refusing redirect ... to another host`	Your server redirects elsewhere. Point the connector at the final address directly — credentials are never followed across hosts.
`SigV4 without a role ARN ...`	Supply an IAM role ARN. Ana only signs with the deployment’s own AWS identity when the target is an AWS endpoint.
`result exceeded 50000 rows`	Widen the step, shorten the range, or aggregate over fewer labels.
Ana can’t find a metric it should see	It is outside your metric selectors, or has had no samples inside the discovery window.
Schema looks truncated	More than 200 metrics matched. Narrow the selectors.
A metric or label is missing from the schema	Prometheus names must match its own charset (`[a-zA-Z_:][a-zA-Z0-9_:]` for metrics, `[a-zA-Z_][a-zA-Z0-9_]` for labels). Anything else is dropped rather than passed to the model.

Get Started

How It Works

Set Up Your Data

Integrations

Ontology

Get Better Results

Admin & Security

FAQ

Legacy Features

1. Overview

2. Prerequisites

Which authentication method should I use?

3. Capabilities

4. Setup Instructions

Step 1: Find your server URL

Step 2: Scope the connector with metric selectors

Step 3: Create the connector

5. How Ana queries Prometheus

Reaching a private server

6. Troubleshooting

​1. Overview

​2. Prerequisites

​Which authentication method should I use?

​3. Capabilities

​4. Setup Instructions

​Step 1: Find your server URL

​Step 2: Scope the connector with metric selectors

​Step 3: Create the connector

​5. How Ana queries Prometheus

​Reaching a private server

​6. Troubleshooting

1. Overview

2. Prerequisites

Which authentication method should I use?

3. Capabilities

4. Setup Instructions

Step 1: Find your server URL

Step 2: Scope the connector with metric selectors

Step 3: Create the connector

5. How Ana queries Prometheus

Reaching a private server

6. Troubleshooting