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

Component	Supported Versions
Amazon DocumentDB	4.0.0, 5.0.0
Amazon DocumentDB Cluster Types	Instance-based clusters
Atatus Infra Agent	4.1.0 or higher

Amazon DocumentDB Elastic Clusters are not supported.

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.

Connect to the primary node of your DocumentDB cluster using the Mongo shell and authenticate as the admin user:
use admin db.auth("admin", "<YOUR_AMAZON_DOCUMENTDB_ADMIN_PASSWORD>")

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

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

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

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

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

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

Configure Atatus Infrastructure Agent

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.
The Agent must connect consistently to the same DocumentDB host. Avoid connecting through load balancers, proxies, or rotating endpoints.

Copy the MongoDB example configuration file:

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

Update the MongoDB configuration file. Add the following configuration to /etc/atatus-infra-agent/conf.d/mongodb.d/mongodb.yml. Single Instance:

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):

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>

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

Restart the Atatus Infrastructure Agent:
sudo service atatus-infra-agent restart
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.
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:

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.

This is not the same mechanism PostgreSQL uses. RDS PostgreSQL mints a short lived rds-db:connect token and presents it as the password, which is why it needs an IAM policy naming a dbuser ARN. DocumentDB has no such token: the driver signs each handshake itself using the MONGODB-AWS SASL mechanism. There is no IAM policy to attach for DocumentDB.

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

On ECS this must be the task role, not the execution role. The execution role is used by ECS before your container starts, to pull the image and read secrets. The process inside the container picks up the task role, so that is the identity that signs the handshake. Mapping the wrong one fails authentication with nothing naming the role as the cause.

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

Remove username and password when you turn this on. An IAM principal has no database password, and the agent rejects a config carrying both at startup rather than preferring one silently.

Two keys behave differently here from the PostgreSQL integration:

Key	Behaviour with DocumentDB
`region`	Required. It is signed into the request.
`instance_endpoint`	Has no effect. Nothing is signed for a host, so there is no endpoint to bind a token to. The agent warns if you set it.

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.

​Before You Begin

​Direct Connection Requirement

​Setup Database Access for the Agent

​Configure Atatus Infrastructure Agent

​Set it up with Terraform

​Authenticating with IAM

​Map the agent’s role to a database user

​Configure the agent

​Monitoring a cluster in another AWS account

​Turning it on in Terraform

​How instances are discovered

Before You Begin

Direct Connection Requirement

Setup Database Access for the Agent

Configure Atatus Infrastructure Agent

Set it up with Terraform

Authenticating with IAM

Map the agent’s role to a database user

Configure the agent

Monitoring a cluster in another AWS account

Turning it on in Terraform

How instances are discovered