> ## 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**. > [!NOTE] > > 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 > [!WARNING] > > 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. > [tab] Self-hosted > > 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 > ``` > [tab] Grafana Cloud > > 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. > [tab] Amazon Managed Prometheus > > 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. > [tab] Mimir / Cortex > > 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. > [!TIP] > > **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: > [tab] SSH tunnel (recommended) > > 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. > [tab] Allowlist the host > > 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. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.