Prometheus Query

Overview Copied

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.

The Prometheus Query plugin is compatible with Prometheus servers that support the /api/v1/query endpoint.

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.

Configuration Copied

Basic tab Copied

This tab contains the following configurable fields:

Prometheus Query plugin basic configuration

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.

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
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 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 Copied

This tab contains the following configurable fields:

Prometheus Query plugin advanced configuration

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 Copied

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

Headline legend Copied

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 Copied

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 Copied

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

["Geneos"] ["Geneos > Netprobe"] ["Technical Reference"]

Was this topic helpful?