--- title: Setting Up Database Monitoring for Amazon RDS managed MariaDB description: Install and configure Database Monitoring for MariaDB managed on Amazon RDS. breadcrumbs: >- Docs > Database Monitoring > Setting up MariaDB > Setting Up Database Monitoring for Amazon RDS managed MariaDB --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Setting Up Database Monitoring for Amazon RDS managed 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 the AWS integration 1. Configure database parameters 1. Grant the Agent access to the database 1. Install and configure the Agent 1. Install the RDS integration ## 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, preferably through the instance endpoint. 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 the AWS integration{% #configure-the-aws-integration %} Enable Standard Collection in the Resource Collection section of your [Amazon Web Services integration tile](https://app.datadoghq.com/integrations/amazon-web-services). ## Configure MariaDB settings{% #configure-mariadb-settings %} Configure the following in the [DB Parameter Group](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithParamGroups.html) and then **restart the server** for the settings to take effect: | Parameter | Value | Description | | ---------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `performance_schema` | `1` | Required. Enables the [performance schema](https://mariadb.com/kb/en/performance-schema-overview/). MariaDB does not enable this by default. | | `max_digest_length` | `4096` | Required for collection of larger queries. Increases the size of SQL digest text in `events_statements_*` tables. 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`. | ## 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 %} With RDS, performance schema consumers can't be enabled permanently in a configuration. 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 and configure the Agent{% #install-and-configure-the-agent %} To monitor RDS hosts, install the Datadog Agent in your infrastructure and configure it to connect to each instance endpoint remotely. The Agent does not need to run on the database, it only needs to connect to it. For additional Agent installation methods not mentioned here, see the [Agent installation instructions](https://app.datadoghq.com/account/settings/agent/latest). {% tab title="Host" %} To configure this check for an Agent running on a host, for example when you provision a small EC2 instance for the Agent to collect from an RDS database: 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. 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. Add this configuration block to your `mysql.d/conf.yaml` to collect MariaDB metrics: ```yaml init_config: instances: - dbm: true host: '' port: username: datadog password: 'ENC[datadog_user_database_password]' # from the CREATE USER step earlier, stored as a secret # After adding your project and instance, configure the Datadog AWS integration to pull additional cloud data such as CPU and Memory. aws: instance_endpoint: '' region: ``` If you want to authenticate with IAM, specify the `region` and `instance_endpoint` parameters, and set `managed_authentication.enabled` to `true`. **Note**: Only enable `managed_authentication` if you want to use IAM authentication. IAM authentication takes precedence over the `password` field. IAM database authentication requires Agent 7.67.0 or later, and AWS doesn't support IAM database authentication on all RDS MariaDB versions. See the [IAM database authentication feature matrix](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RDS_Fea_Regions_DB-eng.Feature.IamDatabaseAuthentication.html) to confirm support for your RDS MariaDB version and region. ```yaml init_config: instances: - dbm: true host: '' port: username: datadog aws: instance_endpoint: '' region: managed_authentication: enabled: true ``` For information on configuring IAM authentication on your RDS instance, see [Connecting with Managed Authentication](https://docs.datadoghq.com/database_monitoring/guide/managed_authentication.md?tab=mysql#configure-iam-authentication). [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. {% /tab %} {% tab title="Docker" %} To configure the Database Monitoring Agent running in a Docker container such as in ECS or Fargate, you can set the [Autodiscovery Integration Templates](https://docs.datadoghq.com/agent/docker/integrations.md?tab=docker) as Docker labels on your agent container. **Note**: The Agent must have read permission on the Docker socket for Autodiscovery of labels to work. ### Command line{% #command-line %} Get up and running by executing the following command to run the agent from your command line. Replace the values to match your account and environment: ```bash export DD_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx export DD_AGENT_VERSION= docker run -e "DD_API_KEY=${DD_API_KEY}" \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -l com.datadoghq.ad.check_names='["mysql"]' \ -l com.datadoghq.ad.init_configs='[{}]' \ -l com.datadoghq.ad.instances='[{ "dbm": true, "host": "", "port": , "username": "datadog", "password": "", "aws": { "instance_endpoint": "", "region": "" } }]' \ registry.datadoghq.com/agent:${DD_AGENT_VERSION} ``` ### Dockerfile{% #dockerfile %} Labels can also be specified in a `Dockerfile`, so you can build and deploy a custom agent without changing any infrastructure configuration: ```Dockerfile FROM registry.datadoghq.com/agent: LABEL "com.datadoghq.ad.check_names"='["mysql"]' LABEL "com.datadoghq.ad.init_configs"='[{}]' LABEL "com.datadoghq.ad.instances"='[{"dbm": true, "host": "", "port": ,"username": "datadog","password": "ENC[datadog_user_database_password]", "aws": {"instance_endpoint": "", "region": ""}}]' ``` {% /tab %} {% tab title="Kubernetes" %} If you have a Kubernetes cluster, use the [Datadog Cluster Agent](https://docs.datadoghq.com/containers/cluster_agent/setup.md) for Database Monitoring. Follow the instructions to [enable the cluster checks](https://docs.datadoghq.com/containers/cluster_agent/clusterchecks.md) if not already enabled in your Kubernetes cluster. You can declare the MySQL configuration either with static files mounted in the Cluster Agent container or using service annotations: ### Operator{% #operator %} Using the [Operator instructions in Kubernetes and Integrations](https://docs.datadoghq.com/containers/kubernetes/integrations.md?tab=datadogoperator) as a reference, follow the steps below to set up the MySQL integration: 1. Create or update the `datadog-agent.yaml` file with the following configuration: ```yaml apiVersion: datadoghq.com/v2alpha1 kind: DatadogAgent metadata: name: datadog spec: global: clusterName: site: credentials: apiSecret: secretName: datadog-agent-secret keyName: api-key features: clusterChecks: enabled: true override: nodeAgent: image: name: agent tag: clusterAgent: extraConfd: configDataMap: mysql.yaml: |- cluster_check: true init_config: instances: - host: port: username: datadog password: 'ENC[datadog_user_database_password]' dbm: true aws: instance_endpoint: region: ``` 1. Apply the changes to the Datadog Operator using the following command: ```shell kubectl apply -f datadog-agent.yaml ``` ### Helm{% #helm %} 1. Complete the [Datadog Agent installation instructions](https://docs.datadoghq.com/containers/kubernetes/integrations.md?tab=helm) for Helm. 1. Update your YAML configuration file (`datadog-values.yaml` in the Cluster Agent installation instructions) to include the following: ```yaml clusterAgent: confd: mysql.yaml: |- cluster_check: true init_config: instances: - dbm: true host: port: username: datadog password: 'ENC[datadog_user_database_password]' aws: instance_endpoint: region: clusterChecksRunner: enabled: true ``` 1. Deploy the Agent with the above configuration file from the command line: ```shell helm install datadog-agent -f datadog-values.yaml datadog/datadog ``` {% alert level="info" %} For Windows, append `--set targetSystem=windows` to the `helm install` command. {% /alert %} ### Configure with mounted files{% #configure-with-mounted-files %} To configure a cluster check with a mounted configuration file, mount the configuration file in the Cluster Agent container on the path `/conf.d/mysql.yaml`: ```yaml cluster_check: true # Make sure to include this flag init_config: instances: - dbm: true host: '' port: username: datadog password: 'ENC[datadog_user_database_password]' aws: instance_endpoint: region: ``` ### Configure with Kubernetes service annotations{% #configure-with-kubernetes-service-annotations %} Rather than mounting a file, you can declare the instance configuration as a Kubernetes Service. To configure this check for an Agent running on Kubernetes, create a service using the following syntax: ```yaml apiVersion: v1 kind: Service metadata: name: mysql labels: tags.datadoghq.com/env: '' tags.datadoghq.com/service: '' annotations: ad.datadoghq.com/service.check_names: '["mysql"]' ad.datadoghq.com/service.init_configs: '[{}]' ad.datadoghq.com/service.instances: | [ { "dbm": true, "host": "", "port": , "username": "datadog", "password": "ENC[datadog_user_database_password]", "aws": { "instance_endpoint": "", "region": "" } } ] spec: ports: - port: protocol: TCP targetPort: name: mysql ``` The Cluster Agent automatically registers this configuration and begins running the MySQL check. To avoid exposing the `datadog` user's password in plain text, use the Agent's [secret management package](https://docs.datadoghq.com/agent/configuration/secrets-management.md) and declare the password using the `ENC[]` syntax. {% /tab %} ### 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! ## Install the RDS Integration{% #install-the-rds-integration %} To see infrastructure metrics from AWS, such as CPU, alongside the database telemetry in DBM, install the [RDS integration](https://docs.datadoghq.com/integrations/amazon_rds.md) (optional). ## 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) - [Amazon RDS Integration](https://docs.datadoghq.com/integrations/amazon_rds.md)