Prometheus exporter

ProxySQL includes a built in Prometheus exporter. This exporter let’s you expose and consume relevant system metrics through a friendly interface.

Admin variables

• admin-restapi_enabled:
  • Description: Enable or disables the metrics endpoint.
  • Default value: false
• admin-restapi_port:
  • Description: Port in which metrics endpoint is going to be exposed.
  • Default value: 6070
• admin-prometheus_memory_metrics_interval:
  • Description: Internal interval in which memory metrics are going to be collected.
  • Default value: 61

Configuration

ProxySQL is always collecting metrics since startup, but metrics endpoint is disabled by default, to enable it and expose this metrics you need to log into the admin console and:

``` SET admin-restapi_enabled='true';

LOAD ADMIN VARIABLES TO RUNTIME;

</p>

Optionally you can also change the other default values in case of need:

<p>

SET admin-restapi_port=‘6070’; SET admin-prometheus_memory_metrics_interval=‘60’;

LOAD ADMIN VARIABLES TO RUNTIME;

</p>

Or place the following lines in your config file:

admin_variables= { … restapi_enabled=true restapi_port=6070 prometheus_memory_metrics_interval=60 … }

### Important Notes

#### `admin-restapi_port` collision:

Multiple instances of ProxySQL should have different `restapi_ports` otherwise ProxySQL won't
be able to start the service responsible for exposing the metrics endpoint, this will be reflected
in the logs with the following message:

<p>

Unable to start ‘ProxySQL_RestAPI_Server’, port ‘%port_number%’ already in use.\n

</p>

In case this event happened, for re-activating the service at runtime, the user should:

1. Switch the service off: `SET admin-restapi_enabled='false'; LOAD ADMIN VARIABLES TO RUNTIME;`.
2. Change the port to a new desired free one: `SET admin-restapi_port='new_free_port_number'`.
3. Switch the service on again: `SET admin-restapi_enabled='true'; LOAD ADMIN VARIABLES TO RUNTIME;`.


#### Performance considerations:

Most of metrics are collected by ProxySQL in each of it's modules in the form of local counters during
regular operation, as it was previously done. In this sense, internal metrics harvest hasn't change at all.

On the other hand, the actual Prometheus counters exposed through the 'RestAPI' or the 'Admin Interface'
are updated 'on-demand', essentially, internal counters are scrapped and exposed when either endpoint is queried.
This is done for all metrics, with the exception of `memory_metrics`, which defines their own internal,
through the 'admin-variable' `admin-prometheus_memory_metrics_interval` due to their higher performance hit.

Metrics polling should be very fast, and shouldn't affect normal ProxySQL operation at all or being noticeable.
With all this, due to the potential increase in size on the Prometheus end of the time series exposed, and
the nature of the metrics being exposed we **do not recommend** sub-second `scrapping_intervals`.

#### Frontend ping metric:

The MySQL status counter `Com_frontend_ping` is exported as:

```text
proxysql_com_frontend_ping_total{protocol="mysql"}

It is a counter of regular frontend MySQL COM_PING packets received from clients. Each successful ping on the normal idle/command-ready path increments both Com_frontend_ping in stats_mysql_global and this Prometheus series once. The protocol="mysql" label distinguishes the protocol while the _total suffix identifies a cumulative counter.

Naming:

Prometheus metrics names used by ProxySQL follow several conventions recommended by Prometheus style guide, and are also verified against promtool checker. This ensures that all ProxySQL metrics are compatible with OpenMetrics format.

Released metric catalog

The catalog below is the complete metric-family union audited at releases v3.0.10, v3.1.10, and v4.0.10. The two GenAI families are registered only when the v4.0.10 GenAI plugin is loaded. A family appears once even when ProxySQL registers several child series for fixed label values. The Labels and values column lists all fixed values established by source plus dynamic label keys added when a backend, cluster node, error, or build is observed. Type is the type declared at family registration; it is authoritative even where a historical metric name or help text suggests another shape.

Connection pools and hostgroups

Query processing and sessions

MySQL Monitor

Query cache

Query-event loggers

Admin, process, and memory

Cluster

Diagnostic messages

GenAI

The dynamic connection-pool labels use endpoint=host:port and the numeric hostgroup. Error series use backend address, port, numeric hostgroup, and error code. Cluster-node series use the node hostname and port; checksum series also use the configuration-module name. The family marked without a child-series producer, proxysql_servers_metrics_weight, is registered in the released source, but the same source contains no active Add(...) path for it, so it does not produce samples. PostgreSQL thread metric definitions are not in this released catalog because their registration is commented out.