> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Prometheus Connector
> Query your Prometheus metrics in Ana using native PromQL.
### **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](#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.
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
```
1. Go to [grafana.com](https://grafana.com) and sign in.
2. Open your stack, then **Details** on the Prometheus tile.
3. Copy the **Query endpoint**, which looks like:
```
https://prometheus-prod-01-eu-west-0.grafana.net/api/prom
```
4. 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.
1. Open the [AMP console](https://console.aws.amazon.com/prometheus) and select your workspace.
2. Copy the **Endpoint - query URL**, then remove the trailing `/api/v1/query`:
```
https://aps-workspaces.us-east-1.amazonaws.com/workspaces/ws-abc123
```
3. 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
1. In TextQL, go to **Connectors** and click **New Connector**.
2. Choose **Prometheus**.
3. Fill in the name, server URL, and authentication.
4. Add your metric selectors.
5. 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(, -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:
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](#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. |