Database Monitoring for Amazon DocumentDB

Atatus Database Monitoring provides deep visibility into your Amazon DocumentDB (with MongoDB compatibility) databases by collecting key metrics, operation samples, explain plans, and replication state changes.

To enable Database Monitoring, the Agent gathers telemetry by connecting to your DocumentDB instances as a read-only user. Follow these steps to get started:

• Setup Database Access for the Agent
• Configure Atatus Infrastructure Agent

Before You Begin

Direct Connection Requirement

The Atatus Infra Agent must connect directly to each DocumentDB instance being monitored. Do not use connection strings or SRV endpoints, as automatic failover or load balancing can route the Agent to a different host, resulting in inaccurate metrics.

If you use Terraform, this is handled for you: give it the cluster identifier and it discovers the members and writes one entry per instance. See Replica sets.

Setup Database Access for the Agent

The Atatus Infra Agent requires read-only access to collect statistics and queries from your Amazon DocumentDB instances.

1. Connect to the primary node of your DocumentDB cluster using the Mongo shell and authenticate as the admin user:

   copy

   use admin
   db.auth("admin", "<YOUR_AMAZON_DOCUMENTDB_ADMIN_PASSWORD>")
   

2. Create a read-only monitoring user for the Atatus Infra Agent:

   copy

   db.createUser({
     "user": "atatus",
     "pwd": "<STRONG_PASSWORD>",
     "roles": [
       { role: "read", db: "admin" },
       { role: "read", db: "local" },
       { role: "clusterMonitor", db: "admin" }
     ]
   })
   

3. Grant read access to specific databases you want to monitor (Optional):

   copy

   db.grantRolesToUser("atatus", [
     { role: "read", db: "<DB_NAME>" }
   ])
   

   Alternatively, to monitor all databases, grant the readAnyDatabase role:

   copy

   db.grantRolesToUser("atatus", [
     { role: "readAnyDatabase", db: "admin" }
   ])
   

Configure Atatus Infrastructure Agent

1. To enable Database Monitoring for your databases, install the Atatus Infrastructure Agent on a host that has network access to your Amazon DocumentDB instances. This can be a Linux host, a Docker container, or a Kubernetes pod.

   Note:

   The Agent must connect consistently to the same DocumentDB host. Avoid connecting through load balancers, proxies, or rotating endpoints.

2. Copy the MongoDB example configuration file:

   copy

   cd /etc/atatus-infra-agent/conf.d/mongodb.d/
   sudo cp mongodb.yml.template mongodb.yml
   

3. Update the MongoDB configuration file.

   Add the following configuration to /etc/atatus-infra-agent/conf.d/mongodb.d/mongodb.yml.

   Single Instance:

   copy

   metrics:
     - hosts:
         - <HOST>:<PORT>
       username: atatus
       password: <REPLACE_PASSWORD>
       connection_scheme: "mongodb"
       db_name: "admin"
       options:
         tls: true
         tls_ca_file: <CERT_FILE_PATH>
       dbm: true
       cluster_name: <CLUSTER_NAME>
   

   Replica Set (1 Primary + 2 Secondaries):

   copy

   metrics:
     - hosts:
         - <HOST_REPLICA_1>:<PORT>   # Primary node
       username: atatus
       password: <REPLACE_PASSWORD>
       connection_scheme: "mongodb"
       db_name: "admin"
       options:
         tls: true
         tls_ca_file: <CERT_FILE_PATH>
       dbm: true
       cluster_name: <CLUSTER_NAME>
   
     - hosts:
         - <HOST_REPLICA_2>:<PORT>   # Secondary node
       username: atatus
       password: <REPLACE_PASSWORD>
       connection_scheme: "mongodb"
       db_name: "admin"
       options:
         tls: true
         tls_ca_file: <CERT_FILE_PATH>
       dbm: true
       cluster_name: <CLUSTER_NAME>
   
     - hosts:
         - <HOST_REPLICA_3>:<PORT>   # Secondary node
       username: atatus
       password: <REPLACE_PASSWORD>
       connection_scheme: "mongodb"
       db_name: "admin"
       options:
         tls: true
         tls_ca_file: <CERT_FILE_PATH>
       dbm: true
       cluster_name: <CLUSTER_NAME>
   

   Note:

   Amazon DocumentDB requires TLS. Ensure tls: true is set and provide the CA certificate path via tls_ca_file. Download the Amazon DocumentDB CA certificate from the AWS documentation.

   Placeholder	Replace With
   <HOST> / <HOST_REPLICA_*>	Your DocumentDB instance endpoint(s)
   <PORT>	Port number (default: 27017)
   <REPLACE_PASSWORD>	Password created for the atatus user
   <CERT_FILE_PATH>	Path to the downloaded CA certificate file
   <CLUSTER_NAME>	A descriptive name for your DocumentDB cluster

4. Restart the Atatus Infrastructure Agent:

   copy

   sudo service atatus-infra-agent restart
   

   Note:

   This restarts the agent on the host, not your database. It is safe to run at any time. The only effect is a gap in collection of a few seconds while the agent comes back, and your clusters keep serving throughout.

   Warning:

   Rebooting a DocumentDB instance is a different matter, and nothing on this page requires it. If you change a cluster parameter group, static parameters need an instance reboot before they take effect, and that reboot drops every open connection while the instance restarts:

   aws docdb reboot-db-instance --db-instance-identifier <INSTANCE_IDENTIFIER>
   

   Rebooting the primary triggers a failover to a replica, so which instance is the writer changes. Do it in a maintenance window.

Set it up with Terraform

The agent host, the TLS material, instance discovery and the $external user can all be provisioned instead of configured by hand. That has its own page, including how to monitor PostgreSQL from the same host:

• Set Up the Agent with Terraform for DocumentDB
• Set Up the Agent with Terraform for PostgreSQL

The working Terraform is at atatus-database-monitoring-sample.

Authenticating with IAM

Amazon DocumentDB can authenticate an IAM principal, so the agent needs no database password. Access is then revoked by editing IAM or dropping the mapped user, rather than by rotating a password every host holds a copy of.

This needs Atatus Infra Agent 4.3.0 or newer.

Map the agent's role to a database user

Instead of an IAM policy, you create a user inside the cluster whose name is the agent's role ARN. Connect to the primary as your admin user:

use $external
db.createUser({
  user: "arn:aws:iam::<ACCOUNT_ID>:role/<AGENT_ROLE_NAME>",
  mechanisms: ["MONGODB-AWS"],
  roles: [
    { role: "readAnyDatabase", db: "admin" },
    { role: "clusterMonitor",  db: "admin" }
  ]
})

The user name has to be the role ARN exactly. If you used the Terraform example, read it back with:

$ terraform output -raw agent_iam_role_arn

Configure the agent

Remove username and password, and add an aws block:

metrics:
  - hosts:
      - <INSTANCE_ENDPOINT>:27017
    connection_scheme: "mongodb"
    db_name: "admin"
    dbm: true
    cluster_name: <CLUSTER_NAME>
    options:
      tls: true
      tls_ca_file: <CERT_FILE_PATH>
    aws:
      region: <REGION>
      managed_authentication:
        enabled: true

Two keys behave differently here from the PostgreSQL integration:

TLS stays mandatory and always verifies both the certificate and the hostname. ssl_mode accepts require, verify-ca and verify-full, which all verify: the MongoDB driver has no weaker setting, and the modes permitting an unencrypted connection are rejected outright.

Monitoring a cluster in another AWS account

The agent's own credentials are used only to call sts:AssumeRole. The handshake is then signed with the temporary credentials that role returns, so it is that role's ARN you map to a $external user above:

    aws:
      region: <REGION>
      managed_authentication:
        enabled: true
        role_arn: "arn:aws:iam::<DB_ACCOUNT_ID>:role/AtatusDBMAccess"
        external_id: "<EXTERNAL_ID>"

Turning it on in Terraform

use_managed_authentication covers both engines, so one host can run PostgreSQL and DocumentDB on IAM together:

use_managed_authentication = true

databases = {
  orders = {
    identifier        = "prod-pg"
    security_group_id = "sg-0123456789abcdef1"
    kind              = "cluster"
  }
}

documentdb_clusters = {
  prod = {
    cluster_identifier = "docdb-prod"
    security_group_id  = "sg-0123456789abcdef0"
  }
}

The $external user has to exist before the agent can connect, and Terraform has no connection to the cluster, so the order is: apply, read agent_iam_role_arn, create the user, then restart the agent.

While you finish that mapping, keep DocumentDB on a password and PostgreSQL on IAM:

use_managed_authentication            = true
documentdb_use_managed_authentication = false

How instances are discovered

The agent must reach each instance directly, so Terraform expands a cluster into one config entry per instance. It resolves them by calling aws docdb describe-db-clusters at apply time, which means the AWS CLI has to be available wherever you run Terraform. If it is not, list the endpoints yourself with instance_endpoints on that cluster, and remember that a hand written list does not follow a scale out on its own.

Once verified, navigate to the Database Monitoring page in Atatus to view your Amazon DocumentDB performance data.