MySQL Integration

Prerequisites

File-Based Authentication

1 Create Database Credentials

Create a .yaml file with your database credentials. If the DB isn’t password-protected, omit username/password.

Docker users: place the credentials file inside /var/log on the Agent host.

Example: /home/ubuntu/mysql-creds.yaml

1mysql:
2  endpoint: localhost:3306
3  username: <YOUR_USERNAME_FOR_MYSQL>
4  password: <YOUR_PASSWORD_FOR_MYSQL>

If you are using MariaDB, specify in the yaml like below:

1mysql/mariadb:
2  endpoint: localhost:3306
3  username: <YOUR_USERNAME_FOR_MARIADB>
4  password: <YOUR_PASSWORD_FOR_MARIADB>

Quick verify (optional): From the Agent host, confirm the DB is reachable with your creds:

1mysql -h <db-host> -P 3306 -u <user> -p'<pass>' -e "SELECT 1" && echo OK || echo FAIL

2 Access Integrations

In Middleware, go to Installations → All Integrations → MySQL.

MySQL Overview

3 Enable Integration

Select the host (where the Host Agent is running), paste the credential file path from Step 1, and Save.

MySQL Host

User-Based Authentication

MySQL metrics are gathered from performance_schema, sys_schema, and server status variables. Create a non-root user with the required permissions.

1 Create a user

1CREATE USER 'mw'@'%' IDENTIFIED BY '<PASSWORD>';
2-- or restrict to a specific host:
3-- CREATE USER 'mw'@'<hostaddr>' IDENTIFIED BY '<PASSWORD>';

Verify the user can connect:

1mysql -u mw --password='<PASSWORD>' -e "SHOW STATUS" | grep Uptime \
2&& echo "MySQL user - OK" || echo "Cannot connect to MySQL"

2 Grant mw permissions

1GRANT REPLICATION CLIENT ON *.* TO 'mw'@'%';
2ALTER USER 'mw'@'%' WITH MAX_USER_CONNECTIONS 5;
3GRANT PROCESS ON *.* TO 'mw'@'%';
4GRANT SELECT ON performance_schema.* TO 'mw'@'%';

If you are a MariaDB user, You may need one extra grant:

1GRANT SLAVE MONITOR ON *.* TO 'mw'@'%';

3 Check Permissions

1mysql -u mw --password='<PASSWORD>' -e "SHOW SLAVE STATUS" \
2&& echo "MySQL grant - OK" || echo "Missing REPLICATION CLIENT grant"

Visualize Analytics

  • Default MySQL Dashboard: A ready-to-use dashboard appears in Dashboard Builder after you enable the integration.
  • Create MySQL Widget: In any dashboard, choose Add New Widgetmysql to see the full list of available metrics.

Alerts

Create alerts on any MySQL metric: choose Detection Method: Database, Database Type: MySQL, then pick a metric and set thresholds (e.g., slow queries, replica lag, handler errors).

Metrics Collected

MetricDescription
mysql.buffer_pool.pagesNumber of pages in the InnoDB buffer pool
mysql.buffer_pool.data_pagesNumber of data pages in the InnoDB buffer pool
mysql.buffer_pool.page_flushesNumber of requests to flush pages from the InnoDB buffer pool
mysql.buffer_pool.operationsNumber of operations on the InnoDB buffer pool
mysql.buffer_pool.limitConfigured size of the InnoDB buffer pool
mysql.buffer_pool.usageNumber of bytes in the InnoDB buffer pool
mysql.commandsCount of commands executed, per command type
mysql.prepared_statementsCount of prepared statements executed, per statement type
mysql.handlersNumber of requests to MySQL handlers
mysql.double_writesNumber of writes to the InnoDB doublewrite buffer
mysql.log_operationsNumber of InnoDB log operations
mysql.operationsNumber of InnoDB operations
mysql.page_operationsNumber of InnoDB page operations
mysql.table.io.wait.countTotal count of I/O wait events for a table
mysql.table.io.wait.timeTotal time of I/O wait events for a table
mysql.index.io.wait.countTotal count of I/O wait events for an index
mysql.index.io.wait.timeTotal time of I/O wait events for an index
mysql.row_locksNumber of InnoDB row blocks
mysql.row_operationsNumber of InnoDB row operations
mysql.locksNumber of MySQL locks
mysql.sortsNumber of MySQL sorts
mysql.threadsState of MySQL threads
mysql.locked_connectsNumber of attempts to connect to locked user accounts
mysql.opened_resourcesNumber of opened resources
mysql.mysqlx_connectionsNumber of mysqlx connections
mysql.tmp_resourcesNumber of created temporary resources
mysql.table.lock_wait.read.countCount of lock wait read events
mysql.table.lock_wait.read.timeTotal lock wait read event time
mysql.table.lock_wait.write.countCount of lock wait write events
mysql.table.lock_wait.write.timeTotal lock wait write event time
mysql.locked_connectsNumber of attempts to connect to locked user accounts
mysql.connection.countTotal number of connection attempts to the MySQL server (includes successful and unsuccessful attempts)
mysql.connection.errorsClient connection process errors
mysql.mysqlx_connectionsNumber of mysqlx connections
mysql.joinsNumber of joins that perform table scans
mysql.replica.time_behind_sourceActual replica delay, in seconds
mysql.replica.sql_delayConfigured replica delay, in seconds
mysql.statement_event.countCount of statement events
mysql.statement_event.wait.timeTotal wait time of summarized timed events
mysql.mysqlx_worker_threadsNumber of worker threads available
mysql.table_open_cacheTotal number of hits, misses, and overflows for open table cache lookups
mysql.query.client.countNumber of client statements executed by the server
mysql.query.countTotal number of statements executed by the server
mysql.query.slow.countNumber of slow queries
mysql.statement_event.countSummary of current and recent statement events
mysql.statement_event.wait.timeThe total wait time of the summarized timed events
mysql.statement_event.count_starsThe total count of executed queries per normalized query and schema
mysql.innodb.buffer_pool_pages_flushedRate of pages being flushed from the InnoDB buffer pool
mysql.innodb.buffer_pool_read_requestsRate of read requests made to the InnoDB buffer pool
mysql.innodb.os_file_readsRate at which files are read by InnoDB
mysql.innodb.data_readRate at which data is read from disk by InnoDB
mysql.innodb.dblwr_pages_writtenRate of pages written to the doublewrite buffer to prevent partial page writes
mysql.innodb.ibuf_merged_delete_marksRate of delete marks merged from the insert buffer to the buffer pool
mysql.innodb.ibuf_merged_deletesRate of delete operations merged from the insert buffer
mysql.innodb.os_log_writtenTotal bytes written to the log by InnoDB
mysql.innodb.row_lock_waitsRate at which operations wait for row locks, indicative of contention on row-level data
mysql.innodb.buffer_pool_readsRate of read operations that required actual disk I/O in the InnoDB buffer pool
mysql.innodb.dblwr_writesRate of operations writing to the doublewrite buffer
mysql.innodb.s_lock_os_waitsRate at which OS waits for shared locks occur
mysql.innodb.s_lock_spin_waitsRate at which spin waits for shared locks occur
mysql.innodb.rows_deletedRate at which rows are being deleted in InnoDB
mysql.innodb.mutex_os_waitsRate at which InnoDB operations need to wait for operating system level mutexes
mysql.innodb.row_lock_timeTotal time spent waiting for row locks by operations in InnoDB
mysql.innodb.buffer_pool_wait_freeNumber of waits for a free page in the buffer pool
mysql.innodb.data_fsyncsRate of fsync operations by InnoDB to disk
mysql.innodb.lsn_flushedLog sequence number of the last flushed log
mysql.innodb.os_log_fsyncsRate at which fsync() operations are issued to the InnoDB log file
mysql.innodb.rows_insertedRate at which rows are being inserted in InnoDB
mysql.innodb.rows_readRate at which rows are being read in InnoDB
mysql.innodb.x_lock_os_waitsRate at which OS waits for exclusive locks occur
mysql.innodb.x_lock_spin_roundsRate at which spin rounds for exclusive locks occur
mysql.innodb.x_lock_spin_waitsRate at which spin waits for exclusive locks occur
mysql.innodb.pages_createdRate at which pages are created by InnoDB
mysql.innodb.data_readsRate of data read operations performed by InnoDB
mysql.innodb.ibuf_mergedRate at which records are merged from the insert buffer
mysql.innodb.ibuf_mergesRate of operations merging data from the insert buffer to the buffer pool
mysql.innodb.log_writesRate of actual log writes
mysql.innodb.os_file_fsyncsRate at which InnoDB performs fsync() operations on files
mysql.innodb.pages_readRate at which pages are read by InnoDB
mysql.innodb.s_lock_spin_roundsRate at which spin rounds for shared locks occur
mysql.innodb.buffer_pool_write_requestsRate of write requests to the InnoDB buffer pool
mysql.innodb.lsn_currentCurrent log sequence number
mysql.innodb.data_writesRate of data write operations performed by InnoDB
mysql.innodb.buffer_pool_read_aheadRate of pages read into the buffer pool by read-ahead
mysql.innodb.data_writtenRate at which data is written to disk by InnoDB
mysql.innodb.lsn_last_checkpointLog sequence number of the last checkpoint
mysql.innodb.mutex_spin_waitsRate of mutex spin waits in InnoDB, indicating contention within internal data structures
mysql.innodb.buffer_pool_read_ahead_evictedRate of pages read by read-ahead and then evicted without being accessed
mysql.innodb.ibuf_merged_insertsRate of insert operations merged from the insert buffer
mysql.innodb.os_file_writesRate at which files are written by InnoDB
mysql.innodb.mutex_spin_roundsRate of spin rounds per mutex spin in InnoDB, showing the effort needed to acquire a mutex
mysql.innodb.log_write_requestsNumber of write requests made to the log
mysql.innodb.pages_writtenRate at which pages are written by InnoDB
mysql.innodb.lock_structsRate at which lock structures are being used or created
mysql.innodb.log_waitsNumber of waits due to log buffer being too small
mysql.innodb.rows_updatedRate at which rows are being updated in InnoDB
mysql.innodb.mem_thread_hashMemory used by InnoDB for thread hash
mysql.innodb.locked_transactionsNumber of transactions that have acquired locks
mysql.innodb.mem_file_systemMemory used by InnoDB for file system data structures
mysql.innodb.buffer_pool_dataTotal number of bytes of data in the InnoDB buffer pool
mysql.innodb.pending_ibuf_aio_readsNumber of pending insert buffer asynchronous I/O reads
mysql.innodb.read_viewsNumber of 'read view' structures currently active; these are used to manage consistent read views
mysql.innodb.buffer_pool_pages_dirtyNumber of dirty pages in the InnoDB buffer pool
mysql.innodb.buffer_pool_totalTotal number of bytes within the InnoDB buffer pool
mysql.innodb.active_transactionsCurrent number of active transactions in InnoDB
mysql.innodb.data_pending_readsCurrent number of pending read operations in InnoDB
mysql.innodb.data_pending_writesCurrent number of pending write operations in InnoDB
mysql.innodb.pending_aio_sync_iosNumber of pending asynchronous I/O operations that need synchronization
mysql.innodb.buffer_pool_freeNumber of bytes currently free within the InnoDB buffer pool
mysql.innodb.os_log_pending_fsyncsNumber of pending fsyncs for logs
mysql.innodb.pending_normal_aio_readsNumber of pending normal asynchronous I/O read operations
mysql.innodb.row_lock_current_waitsCurrent number of operations waiting for row locks in InnoDB
mysql.innodb.ibuf_sizeTotal size of the insert buffer
mysql.innodb.mem_adaptive_hashMemory used by InnoDB for the adaptive hash index
mysql.innodb.buffer_pool_dirtyCurrent number of bytes held in dirty pages in the InnoDB buffer pool
mysql.innodb.buffer_pool_usedNumber of bytes currently used within the InnoDB buffer pool
mysql.innodb.locked_tablesNumber of tables currently locked by InnoDB
mysql.innodb.pending_aio_log_iosNumber of pending asynchronous I/O operations on the log
mysql.innodb.pending_normal_aio_writesNumber of pending normal asynchronous I/O write operations.
mysql.innodb.mem_page_hashMemory used by InnoDB for page hash
mysql.innodb.mem_lock_systemMemory used by InnoDB for lock system data structures
mysql.innodb.mem_totalTotal memory allocated to InnoDB
mysql.innodb.queries_queuedNumber of queries waiting to be processed by InnoDB
mysql.innodb.semaphore_waitsNumber of semaphore waits
mysql.innodb.buffer_pool_pages_dataNumber of data pages in the InnoDB buffer pool
mysql.innodb.buffer_pool_utilizationPercentage of the InnoDB buffer pool currently being utilized
mysql.innodb.hash_index_cells_totalTotal number of cells in the adaptive hash index
mysql.innodb.mem_additional_poolMemory allocated to InnoDB's additional pool
mysql.innodb.mem_dictionaryMemory used by InnoDB for dictionary information
mysql.innodb.pending_log_writesNumber of pending writes to the log file
mysql.innodb.queries_insideNumber of queries currently being processed inside InnoDB
mysql.innodb.tables_in_useNumber of tables currently in use by InnoDB
mysql.innodb.ibuf_segment_sizeSize of the segment available for the insert buffer
mysql.innodb.pending_checkpoint_writesNumber of pending writes to establish a new checkpoint
mysql.innodb.buffer_pool_read_ahead_rndNumber of random read-aheads in the InnoDB buffer pool
mysql.innodb.current_row_locksCurrent number of row locks held by operations in InnoDB
mysql.innodb.data_pending_fsyncsCurrent number of pending fsync operations in InnoDB
mysql.innodb.pending_buffer_pool_flushesNumber of pending buffer pool flush operations
mysql.innodb.current_transactionsCurrent number of transactions happening in InnoDB
mysql.innodb.semaphore_wait_timeTotal wait time for semaphores
mysql.innodb.history_list_lengthLength of the history list, indicating the number of pages consumed by transactions not yet flushed
mysql.innodb.ibuf_free_listNumber of pages in the insert buffer free list
mysql.innodb.mem_recovery_systemMemory used by InnoDB for transaction recovery
mysql.innodb.checkpoint_ageAge of the last checkpoint in InnoDB
mysql.innodb.hash_index_cells_usedNumber of used cells in the adaptive hash index
mysql.innodb.os_log_pending_writesNumber of pending log writes
mysql.innodb.buffer_pool_pages_freeNumber of free pages in the InnoDB buffer pool
mysql.innodb.pending_log_flushesNumber of pending flush operations for the log buffer
mysql.innodb.buffer_pool_pages_totalTotal number of pages in the InnoDB buffer pool

Troubleshooting

Integrations menu is missing:

  • Your account likely lacks Installation permissions. Ask an admin to grant the Installation permission in Settings.

Host Agent can’t read the credentials file (Docker)

  • Ensure the YAML is inside /var/log on the Agent host and reference that exact path in Step 3.

Connection/authentication failures:

Test from the Agent host with the same creds:

1mysql -h <db-host> -P 3306 -u <user> -p'<pass>' -e "SELECT 1"
  • Fix DNS/firewall/port or credentials if it fails.

User-based auth: grants incomplete

  • Re-run the Check permissions command. If it prints “Missing REPLICATION CLIENT grant,” apply the grants in Step 2, and for MariaDB, also apply GRANT SLAVE MONITOR.

Only one node appears (replica setups)

  • Add each instance you want to monitor (or ensure your endpoint points at the intended node). Metrics are collected per instance.

Need assistance or want to learn more about Middleware? Contact our support team at [email protected] or join our Slack channel.