---
title: "Prometheus Query"
description: "Integrate Prometheus metrics into Geneos effortlessly with the Prometheus Query plugin, enabling direct data ingestion through PromQL without redundancy."
url: "https://docs.itrsgroup.com/docs/geneos/7.9.0/collection/prometheus-query/index.html"
---## Overview

The Prometheus Query plugin is a Netprobe plugin that allows you to query metrics from existing Prometheus deployments using PromQL and ingest the results directly into Geneos. This enables you to bring selected Prometheus metrics into Geneos.

The plugin executes PromQL queries against a Prometheus server via the standard Prometheus HTTP API. Prometheus remains the single source of metrics, while Geneos processes only the required subset via PromQL. The plugin is designed to be lightweight, allowing for configurable PromQL queries.


**Note**

 This plugin is ideal for querying specific metrics from existing Prometheus deployments. For full integration with Remote Write, Alert Manager, and direct collection capabilities, see the [Prometheus Collection Agent plugin](https://docs.itrsgroup.com/docs/geneos/collection/prometheus/current/user-guide/prometheus/index.html). 


## Configuration

### Basic tab

This tab contains the following configurable fields:

![Prometheus Query plugin basic configuration](https://docscdn.itrsgroup.com/geneos/images/plug-ins/prometheus-query-basic-configuration-7-8.png)

| Field | Description |
|-------|-------------|
| Queries > Query name | Descriptive name of the query. This will also be used as the name of the dataview.
Mandatory: Yes |
| Queries > Prometheus Query | The PromQL query expression that will be executed. Each row in the configuration represents one query, and the result of each query will be mapped to a dataview. Queries can be for: - Single metric — query a specific metric only, for example `prometheus_http_request_duration_seconds_count`.
- Aggregation — query using an aggregate function, for example `rate(prometheus_http_request_duration_seconds_count[5m])`.
- Multiple metrics — query multiple metrics, for example `{__name__=~"prometheus_http_request_duration_seconds_count_[sc].*"}`. Entering an invalid query will result in an empty dataview. For more information about PromQL querying, refer to [Querying basics](https://prometheus.io/docs/prometheus/latest/querying/basics/).
Mandatory: Yes |
| Queries > Key column labels | The metric labels from the PromQL response which will form the key column of the dataview. Multiple labels are joined with `_`.
For example, in the metric below, you can define `handler` and `instance` in the **Key column labels** configuration to limit the key column to display only these labels. The key column header name will then be `handler_instance` following the order specified in the configuration, and the key value will be `/api/v1/query_localhost:9090`.
```
{
"metric": {
"app": "prometheus",
"handler": "/api/v1/query",
"instance": "localhost:9090",
"job": "prometheus"
},
"value": [
1767689874.668,
"1.9614103909136522"
]
}
```
All defined labels must exist in every query result. If a label is missing, the resulting row is skipped and a warning is logged.
If no labels are defined in the **Key column labels**, all labels will be concatenated with `_`.
Mandatory: No |
| Queries > Metric column name | The header name for the metric data column.
By default, the header name of the metric data column is derived from the Prometheus `__name__metric` label. However, when this label is not part of the response (for example, when the query uses PromQL functions to aggregate metrics), the column header name will default to `value`.
Mandatory: No |
| Queries > Max rows | The maximum number of rows to publish in the dataview. This limit applies per query.
Default: 200
Mandatory: No 
**Note**

You can override this setting with a Gateway-wide row limit that you can [configure in the Gateway Setup Editor](https://docs.itrsgroup.com/docs/geneos/7.9.0/processing/configuration/gateway_operating_environment/index.html#operatingenvironment--customdataviewmaxrows) under **Operating environment** > **Custom dataview max rows**. 
 |
| Host | Hostname of the Prometheus server.
Mandatory: Yes |
| Port | Port number of the Prometheus server.
Mandatory: Yes |
| Protocol | Determine whether to use `http` (unencrypted) or `https` (SSL encrypted). When using SSL connections, the server certificate can also be verified.
Mandatory: No
Default: `http`  |
| Protocol > https > certificate | Certificate file to use for SSL authentication. - Verify — whether to verify the server certificate.
- Client certificate — the certificate sent to the server for client authentication. This must be in PEM format and is required for client authentication.
- Client key — the private key that corresponds to the client certificate. This must be in PEM format and is required for client authentication.
- Client key passphrase — the passphrase used to decrypt the private key. Specify this only if the private key is passphrase-protected. Mandatory: No  |
| Protocol > https > certificate > verify | Specify what to verify in the certificate. - None — verification succeeds as long as any certificate is present.
- Against authority — verifies that the certificate has been signed by a trusted Certificate Authority, but does not verify that the hostname matches.
- Against authority and hostname — verifies that the certificate has been signed by a trusted Certificate Authority and that the hostname matches. When verifying the certificate against a Certificate Authority, a CA bundle in PEM format must be used. This file specifies the Certificate Authorities that are to be trusted. If the operating system does not include a CA bundle or it is out of date, a CA bundle should be specified.
You can either create your own CA bundle (useful when using self-signed certificates) or [download a standard CA bundle](http://curl.haxx.se/docs/caextract.html) containing trusted Certificate Authorities.
Mandatory: No
Default: None  |
| Protocol > https > tlsVersions > minTLSVersion | Minimum TLS Protocol version to be used.
Mandatory: No
Default: None  |
| Protocol > https > tlsVersions > maxTLSVersion | Maximum TLS Protocol version to be used.
Mandatory: No
Default: None |

### Advanced tab

This tab contains the following configurable fields:

![Prometheus Query plugin advanced configuration](https://docscdn.itrsgroup.com/geneos/images/plug-ins/prometheus-query-advanced-configuration-7-8.png)

| Field | Description |
|-------|-------------|
| Query timeout | Timeout for query execution in seconds.
Mandatory: No
Default: 30 seconds |
| Max columns | The maximum number of columns (excluding the key column) to publish in the dataview.
Mandatory: No
Default: 50 |

## Dataview

The metrics retrieved via PromQL queries are displayed in the Geneos dataview format. Each configured query produces a separate dataview, with the dataview name matching the query name specified in the configuration.

![Prometheus Query dataview sample](https://docscdn.itrsgroup.com/geneos/images/plug-ins/prometheus-query-dataview-7-8.png)

### Headline legend

| Name | Description |
|-------|-------------|
| Query status | The query execution status. Possible values: - initializing — the plugin is initializing.
- idle — the query is not currently executing.
- running — the query is executing and the plugin is processing results. The dataview displays data from the previous query execution. |
| Server base URL | The URL of the Prometheus server. |
| Result count | The total number of metrics. |

### Table legend

| Name | Description |
|-------|-------------|
| Key column | The metric labels from the PromQL response. Multiple labels are joined with `_`. |
| Metric columns | The metrics queried and their corresponding values. |

### Show Query command

The `Show Query` command displays the PromQL query executed for the dataview, as specified in the query configuration. Right-click any headline, including `samplingStatus`, to execute this command.

Example output:

![Show Query command output](https://docscdn.itrsgroup.com/geneos/images/plug-ins/prometheus-query-show-query-output-7-8.png)

