How to Install and Configure Prometheus MySQL Exporter on Linux

The Prometheus MySQL exporter (mysqld_exporter) periodically queries your MySQL server and exposes the results as Prometheus gauge metrics (for example query-related metrics and InnoDB buffer pool metrics).

Prometheus is an open-source monitoring and alerting platform. It can be used with a visualization tool like Grafana to build dashboards, query metrics, and set alerts.

You will configure Prometheus to scrape the exporter metrics, and optionally visualize them in Grafana.

Prerequisites

Before proceeding, you need:

A working MySQL server
A working Prometheus server (if you don’t have one yet):
- How to run Prometheus with Docker and Docker Compose
- How to install and configure Prometheus on a Linux server

Install and configure `mysqld_exporter`

Download the exporter binary and install it into /usr/local/bin.

Releases: https://github.com/prometheus/mysqld_exporter/releases

1
2
3
4
5
6
7
8
# Download and install mysqld_exporter (example: v0.14.0)
VERSION="0.14.0"
curl -LO "https://github.com/prometheus/mysqld_exporter/releases/download/v${VERSION}/mysqld_exporter-${VERSION}.linux-amd64.tar.gz"

tar -xvf "mysqld_exporter-${VERSION}.linux-amd64.tar.gz"

sudo mv "mysqld_exporter-${VERSION}.linux-amd64/mysqld_exporter" /usr/local/bin/mysqld_exporter
sudo chmod +x /usr/local/bin/mysqld_exporter

Confirm the installation by checking mysqld_exporter version:

1
2
3
4
5
6
$ mysqld_exporter --version
mysqld_exporter, version 0.14.0 (branch: HEAD, revision: ca1b9af82a471c849c529eb8aadb1aac73e7b68c)
  build user:       root@401d370ca42e
  build date:       20220304-16:25:15
  go version:       go1.17.8
  platform:         linux/amd64

Create a dedicated system user

Create a non-login system user for the exporter:

1
2
sudo groupadd --system mysql_exporter
sudo useradd --system -s /sbin/nologin -g mysql_exporter mysql_exporter

Create a MySQL user for scraping

Create a MySQL user that can query the metrics:

1
2
3
4
5
CREATE USER 'exporter'@'localhost' IDENTIFIED BY 'CHANGE_ME'
  WITH MAX_USER_CONNECTIONS 3;

GRANT PROCESS, REPLICATION CLIENT, SELECT ON *.* TO 'exporter'@'localhost';
FLUSH PRIVILEGES;

The MAX_USER_CONNECTIONS setting limits connections so monitoring scrapes don’t overload your MySQL server under heavy load.

Configure exporter credentials (`/etc/mysqld_exporter.cnf`)

Create the credentials file:

1
2
3
4
[client]
user=exporter
password=CHANGE_ME
host=127.0.0.1

Then lock down permissions and ownership:

1
2
sudo chown mysql_exporter:mysql_exporter /etc/mysqld_exporter.cnf
sudo chmod 600 /etc/mysqld_exporter.cnf

Run `mysqld_exporter` with systemd

Create the systemd unit:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
sudo tee /etc/systemd/system/mysql_exporter.service >/dev/null <<'EOF'
[Unit]
Description=Prometheus MySQL Exporter Service
After=network.target

[Service]
Type=simple
User=mysql_exporter
Group=mysql_exporter

# Recommended: bind locally and only allow Prometheus to reach it.
Environment=LISTEN_ADDRESS=127.0.0.1:9104
Restart=on-failure

ExecStart=/usr/local/bin/mysqld_exporter \
  --config.my-cnf=/etc/mysqld_exporter.cnf \
  --collect.global_status \
  --collect.global_variables \
  --collect.info_schema.innodb_metrics \
  --collect.auto_increment.columns \
  --collect.info_schema.processlist \
  --collect.binlog_size \
  --collect.info_schema.tablestats \
  --collect.info_schema.query_response_time \
  --collect.info_schema.userstats \
  --collect.info_schema.tables \
  --collect.perf_schema.tablelocks \
  --collect.perf_schema.file_events \
  --collect.perf_schema.eventswaits \
  --collect.perf_schema.indexiowaits \
  --collect.perf_schema.tableiowaits \
  --collect.slave_status \
  --web.listen-address=${LISTEN_ADDRESS}

[Install]
WantedBy=multi-user.target
EOF

Reload systemd and start:

1
2
sudo systemctl daemon-reload
sudo systemctl enable --now mysql_exporter

Confirm the exporter is running:

1
sudo systemctl status mysql_exporter --no-pager

And test the metrics endpoint:

1
curl -s http://127.0.0.1:9104/metrics | rg -m1 'mysql_'

Configure Prometheus scraping

Edit prometheus.yml and add a scrape job for the exporter. Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: mysql-exporter
    static_configs:
      - targets:
          - "127.0.0.1:9104"
        labels:
          alias: my-mysql

Notes:

In the example, Prometheus scrapes the exporter from the same host (127.0.0.1).
If Prometheus is on a different host, set targets to the exporter host/IP and make sure the exporter is reachable over the network.
For security, the exporter in this guide binds to 127.0.0.1. If Prometheus is remote, you can either:
- change LISTEN_ADDRESS to a non-loopback interface and open firewall rules, or
- run Prometheus on the same host, or
- use a reverse proxy/VPN network to restrict access.

Grafana dashboards (optional)

Add Prometheus as a data source:
- Name: Prometheus
- Type: Prometheus
- URL: http://localhost:9090 (or http://PROMETHEUS_HOST:9090)
Create dashboards from metrics, or import a ready-made one:
- Percona Grafana dashboards: https://github.com/percona/grafana-dashboards

Security best practices

Keep /etc/mysqld_exporter.cnf private (chmod 600)
Bind the exporter to 127.0.0.1 by default
Use least-privilege MySQL grants
Monitor exporter impact under load (reduce scrape frequency or collection flags if needed)

Troubleshooting

Exporter can’t connect to MySQL

Check service logs:

1
sudo journalctl -u mysql_exporter -n 200 --no-pager

Verify the credentials file:

1
sudo ls -l /etc/mysqld_exporter.cnf

Confirm the MySQL user exists and is allowed to connect from localhost.

Prometheus target is down

From the Prometheus host, verify you can reach the exporter endpoint:

1
curl -s http://EXPORTER_HOST:9104/metrics | rg -m1 'mysql_'

Verify firewall/security group rules and that the exporter LISTEN_ADDRESS matches your target connectivity.

Summary

You now have mysqld_exporter running on Linux, Prometheus scraping MySQL metrics, and a path to visualize them in Grafana with ready-made dashboards.