--- title: Setting Up Database Monitoring for self hosted MariaDB description: Install and configure Database Monitoring for self-hosted MariaDB. breadcrumbs: >- Docs > Database Monitoring > Setting up MariaDB > Setting Up Database Monitoring for self hosted MariaDB --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Setting Up Database Monitoring for self hosted MariaDB Database Monitoring provides deep visibility into your MariaDB databases by exposing query metrics, query samples, explain plans, connection data, system metrics, and telemetry for the InnoDB storage engine. The Agent collects telemetry directly from the database by logging in as a read-only user. Do the following setup to enable Database Monitoring with your MariaDB database: 1. Configure database parameters 1. Grant the Agent access to the database 1. Install the Agent ## Before you begin{% #before-you-begin %} {% dl %} {% dt %} Supported MariaDB versions {% /dt %} {% dd %} 10.5, 10.6, 10.11, or 11.4 Database Monitoring for MariaDB is supported with [known limitations](https://docs.datadoghq.com/database_monitoring/setup_mariadb/troubleshooting.md#mariadb-known-limitations). {% /dd %} {% dt %} Supported Agent versions {% /dt %} {% dd %} 7.61.0+ {% /dd %} {% dt %} Performance impact {% /dt %} {% dd %} The default Agent configuration for Database Monitoring is conservative, but you can adjust settings such as the collection interval and query sampling rate to better suit your needs. For most workloads, the Agent represents less than 1% of query execution time on the database and less than 1% of CPU. Database Monitoring runs as an integration on top of the base Agent ([see benchmarks](https://docs.datadoghq.com/database_monitoring/agent_integration_overhead.md?tab=mysql)). {% /dd %} {% dt %} Proxies, load balancers, and connection poolers {% /dt %} {% dd %} The Datadog Agent must connect directly to the host being monitored. For self-hosted databases, `127.0.0.1` or the socket is preferred. The Agent should not connect to the database through a proxy, load balancer, or connection pooler. If the Agent connects to different hosts while it is running (as in the case of failover, load balancing, and so on), the Agent calculates the difference in statistics between two hosts, producing inaccurate metrics. {% /dd %} {% dt %} Data security considerations {% /dt %} {% dd %} See [Sensitive information](https://docs.datadoghq.com/database_monitoring/data_collected.md#sensitive-information) for information about what data the Agent collects from your databases and how to keep it secure. {% /dd %} {% /dl %} ## Configure MariaDB settings{% #configure-mariadb-settings %} To collect query metrics, samples, and explain plans, enable the [MariaDB performance schema](https://mariadb.com/kb/en/performance-schema-overview/) and configure the following [performance schema options](https://mariadb.com/docs/server/reference/system-tables/performance-schema/performance-schema-system-variables), either on the command line or in configuration files (for example, `mysql.conf`): **Note**: Unlike MySQL, MariaDB ships with `performance_schema` turned off by default. You must explicitly enable it. | Parameter | Value | Description | | ------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `performance_schema` | `ON` | Required. Enables the performance schema. MariaDB does not enable this by default. | | `max_digest_length` | `4096` | Required for collection of larger queries. If left at the default value, queries longer than `1024` characters aren't collected. | | `performance_schema_max_digest_length` | `4096` | Must match `max_digest_length`. | | `performance_schema_max_sql_text_length` | `4096` | Must match `max_digest_length`. | | `performance-schema-consumer-events-statements-current` | `ON` | Required. Enables monitoring of running queries. | | `performance-schema-consumer-events-waits-current` | `ON` | Required. Enables the collection of wait events. | | `performance-schema-consumer-events-statements-history-long` | `ON` | Recommended. Enables tracking of a larger number of recent queries across all threads. If enabled it increases the likelihood of capturing execution details from infrequent queries. | | `performance-schema-consumer-events-statements-history` | `ON` | Optional. Enables tracking recent query history per thread. If enabled it increases the likelihood of capturing execution details from infrequent queries. | **Note**: A recommended practice is to allow the agent to enable the `performance-schema-consumer-*` settings dynamically at runtime, as part of granting the Agent access. See Runtime setup consumers. ## Grant the Agent access{% #grant-the-agent-access %} The Datadog Agent requires read-only access to the database to collect statistics and queries. The following instructions grant the Agent permission to login from any host using `datadog@'%'`. You can restrict the `datadog` user to be allowed to login only from localhost by using `datadog@'localhost'`. See the [MariaDB documentation](https://mariadb.com/docs/server/reference/sql-statements/account-management-sql-statements/create-user) for more info. Create the `datadog` user and grant basic permissions: ```sql CREATE USER datadog@'%' IDENTIFIED by ''; ALTER USER datadog@'%' WITH MAX_USER_CONNECTIONS 5; GRANT REPLICATION CLIENT ON *.* TO datadog@'%'; GRANT PROCESS ON *.* TO datadog@'%'; GRANT SELECT ON performance_schema.* TO datadog@'%'; ``` Blocking-query collection uses `information_schema.INNODB_LOCK_WAITS` and `INNODB_TRX`, together with `performance_schema`, so the `PROCESS` and `SELECT ON performance_schema.*` grants above are sufficient; no additional grant is required. Blocking-query collection is disabled by default. Enable it with `query_activity.collect_blocking_queries: true` in your instance configuration. Create the following schema: ```sql CREATE SCHEMA IF NOT EXISTS datadog; GRANT EXECUTE ON datadog.* to datadog@'%'; ``` Create the `explain_statement` procedure to enable the Agent to collect explain plans: ```sql DELIMITER $$ CREATE PROCEDURE datadog.explain_statement(IN query TEXT) SQL SECURITY DEFINER BEGIN SET @explain := CONCAT('EXPLAIN FORMAT=json ', query); PREPARE stmt FROM @explain; EXECUTE stmt; DEALLOCATE PREPARE stmt; END $$ DELIMITER ; ``` Additionally, create this procedure **in every schema** from which you want to collect explain plans. Replace `` with your database schema: ```sql DELIMITER $$ CREATE PROCEDURE .explain_statement(IN query TEXT) SQL SECURITY DEFINER BEGIN SET @explain := CONCAT('EXPLAIN FORMAT=json ', query); PREPARE stmt FROM @explain; EXECUTE stmt; DEALLOCATE PREPARE stmt; END $$ DELIMITER ; GRANT EXECUTE ON PROCEDURE .explain_statement TO datadog@'%'; ``` To collect index metrics, grant the `datadog` user an additional privilege: ```sql GRANT SELECT ON mysql.innodb_index_stats TO datadog@'%'; ``` ### Runtime setup consumers{% #runtime-setup-consumers %} Datadog recommends that you create the following procedure to give the Agent the ability to enable `performance_schema.events_*` consumers at runtime. ```SQL DELIMITER $$ CREATE PROCEDURE datadog.enable_events_statements_consumers() SQL SECURITY DEFINER BEGIN UPDATE performance_schema.setup_consumers SET enabled='YES' WHERE name LIKE 'events_statements_%'; UPDATE performance_schema.setup_consumers SET enabled='YES' WHERE name = 'events_waits_current'; END $$ DELIMITER ; GRANT EXECUTE ON PROCEDURE datadog.enable_events_statements_consumers TO datadog@'%'; ``` ### Securely store your password{% #securely-store-your-password %} Store your password using secret management software such as [Vault](https://www.vaultproject.io/). You can then reference this password as `ENC[]` in your Agent configuration files: for example, `ENC[datadog_user_database_password]`. See [Secrets Management](https://docs.datadoghq.com/agent/configuration/secrets-management.md) for more information. The examples on this page use `datadog_user_database_password` to refer to the name of the secret where your password is stored. It is possible to reference your password in plain text, but this is not recommended. ## Collecting schemas{% #collecting-schemas %} Starting with Agent 7.65, the Datadog Agent can collect schema information from MariaDB databases. Enable it with `collect_schemas.enabled: true` in your instance configuration (use `schemas_collection` instead on Agent 7.68 and earlier). Schema collection is disabled by default. ```yaml instances: - dbm: true ... collect_schemas: enabled: true ``` On MariaDB 10.5 and later (like MySQL), `INFORMATION_SCHEMA` only exposes a table to a user that holds a privilege on it, so without a grant the `datadog` user sees no tables. Grant the `REFERENCES` privilege to make table metadata visible without giving the Agent the ability to read table data: ```sql GRANT REFERENCES ON *.* TO datadog@'%'; ``` `REFERENCES` is also required to collect foreign-key `delete_rule` and `update_rule` values from `INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS`; the table-level `SELECT` privilege does not expose that view. See [Exploring Database Schemas](https://docs.datadoghq.com/database_monitoring/schema_explorer.md) for the available `collect_schemas` tuning options. ## Install the Agent{% #install-the-agent %} Installing the Datadog Agent also installs the MySQL check, which is used to monitor MariaDB and is required for Database Monitoring on MariaDB. If you haven't already installed the Agent for your MariaDB database host, see the [Agent installation instructions](https://app.datadoghq.com/account/settings/agent/latest). To configure this check for an Agent running on a host: Edit the `mysql.d/conf.yaml` file, in the `conf.d/` folder at the root of your [Agent's configuration directory](https://docs.datadoghq.com/agent/configuration/agent-configuration-files.md#agent-configuration-directory) to start collecting your MariaDB metrics and logs. See the [sample mysql.d/conf.yaml](https://github.com/DataDog/integrations-core/blob/master/mysql/datadog_checks/mysql/data/conf.yaml.example) for all available configuration options, including those for custom metrics. ### Metric collection{% #metric-collection %} Add this configuration block to your `mysql.d/conf.yaml` to collect MariaDB metrics: ```yaml init_config: instances: - dbm: true host: 127.0.0.1 port: 3306 username: datadog password: 'ENC[datadog_user_database_password]' # from the CREATE USER step earlier ``` **Note**: The `datadog` user should be set up in the MySQL integration configuration as `host: 127.0.0.1` instead of `localhost`. Alternatively, you may also use `sock`. Metrics and events are tagged with `dbms_flavor:mariadb` so you can distinguish MariaDB data from MySQL data. [Restart the Agent](https://docs.datadoghq.com/agent/configuration/agent-commands.md#start-stop-and-restart-the-agent) to start sending MariaDB metrics to Datadog. ### Log collection (optional){% #log-collection-optional %} In addition to telemetry collected from the database by the Agent, you can also choose to send your database logs directly to Datadog. 1. By default MariaDB logs everything in `/var/log/syslog` which requires root access to read. To make the logs more accessible, follow these steps: 1. Edit `/etc/mysql/conf.d/mysqld_safe_syslog.cnf` and comment out all lines. 1. Edit `/etc/mysql/my.cnf` to enable the desired logging settings. For example, to enable general, error, and slow query logs, use the following configuration: ```gdscript3 [mysqld_safe] log_error = /var/log/mysql/mysql_error.log [mysqld] general_log = on general_log_file = /var/log/mysql/mysql.log log_error = /var/log/mysql/mysql_error.log slow_query_log = on slow_query_log_file = /var/log/mysql/mysql_slow.log long_query_time = 3 ``` Save the file and restart MariaDB.Make sure the Agent has read access to the `/var/log/mysql` directory and all of the files within. Double-check your `logrotate` configuration to make sure these files are taken into account and that the permissions are correctly set. In `/etc/logrotate.d/mysql-server` there should be something similar to: ```text /var/log/mysql.log /var/log/mysql/mysql.log /var/log/mysql/mysql_slow.log { daily rotate 7 missingok create 644 mysql adm Compress } ``` 1. Collecting logs is disabled by default in the Datadog Agent, enable it in your `datadog.yaml` file: ```yaml logs_enabled: true ``` 1. Add this configuration block to your `mysql.d/conf.yaml` file to start collecting your MariaDB logs: ```yaml logs: - type: file path: "" source: mysql service: "" - type: file path: "" source: mysql service: "" log_processing_rules: - type: multi_line name: new_slow_query_log_entry pattern: "# Time:" # If mysqld was started with `--log-short-format`, use: # pattern: "# Query_time:" - type: file path: "" source: mysql service: "" # For multiline logs, if they start by the date with the format yyyy-mm-dd uncomment the following processing rule # log_processing_rules: # - type: multi_line # name: new_log_start_with_date # pattern: \d{4}\-(0?[1-9]|1[012])\-(0?[1-9]|[12][0-9]|3[01]) # If the logs start with a date with the format yymmdd but include a timestamp with each new second, rather than with each log, uncomment the following processing rule # log_processing_rules: # - type: multi_line # name: new_logs_do_not_always_start_with_timestamp # pattern: \t\t\s*\d+\s+|\d{6}\s+\d{,2}:\d{2}:\d{2}\t\s*\d+\s+ ``` 1. [Restart the Agent](https://docs.datadoghq.com/agent/configuration/agent-commands.md#start-stop-and-restart-the-agent). ## Validate{% #validate %} [Run the Agent's status subcommand](https://docs.datadoghq.com/agent/configuration/agent-commands.md#agent-status-and-information) and look for `mysql` under the Checks section, or see the [Databases](https://app.datadoghq.com/databases) page to get started. ## Troubleshooting{% #troubleshooting %} If you have installed and configured the integrations and Agent as described and it is not working as expected, see [Troubleshooting](https://docs.datadoghq.com/database_monitoring/setup_mariadb/troubleshooting.md). ## Further reading{% #further-reading %} Additional helpful documentation, links, and articles: - [Basic MySQL Integration](https://docs.datadoghq.com/integrations/mysql.md)