Database Monitoring for MongoDB Atlas

Atatus Database Monitoring provides deep visibility into your MongoDB Atlas clusters by collecting key metrics, slow queries, operation samples, explain plans, and replication health data.

This guide walks you through enabling monitoring for MongoDB Atlas and configuring secure access for the Atatus Infra Agent.

Before You Begin

Component	Supported Versions
MongoDB	4.4, 5.0, 6.0, 7.0, 8.0
MongoDB Atlas Cluster Tiers	M10 and higher
Atatus Infra Agent	4.1.0 or higher

Note: MongoDB Atlas Serverless and shared clusters (M0, M2, M5) are not supported.

Grant Access to Your MongoDB Atlas Cluster

The Atatus Infra Agent requires read-only permissions to collect operational statistics and query metrics from MongoDB Atlas.

Step 1: Create a Custom Monitoring Role

Log in to the MongoDB Atlas UI.
Navigate to Database Access → Custom Roles.
Click Add New Custom Role.
Enter a role name (example: atatus-monitor).
Add the following privileges:

read on the admin database
read on the local database
read on the config database (for sharded clusters only)
clusterMonitor on the admin database
read on specific application databases or use readAnyDatabase to monitor all databases

6. Save the custom role.

Step 2: Create a Monitoring User

In the MongoDB Atlas UI, go to Database Access → Database Users.
Click Add New Database User.
Choose Password Authentication.
Enter a username and strong password.
Under Database User Privileges, assign the custom role created earlier.
Click Add User.
Save the username and password. You will use them when configuring the Atatus Agent.

Install and Configure the Atatus Agent

The Atatus Infra Agent must run on a host that can network-connect to your MongoDB Atlas cluster.

Resolve Individual MongoDB Host and Port

MongoDB Atlas applications usually connect using an SRV connection string. However, the Atatus Agent must connect directly to individual MongoDB hosts to avoid inaccurate metrics during failover or load balancing.

Use DNS tools to resolve the SRV record and extract hostnames.

Resolve Replica Set Nodes

For an SRV connection string like mongodb+srv://cluster.example.mongodb.net/, use the following commands:

Linux:

copy

dig +short SRV _mongodb._tcp.cluster.example.mongodb.net

Example output:

copy

0 0 27017 node-00.mongodb.net.
0 0 27017 node-01.mongodb.net.
0 0 27017 node-02.mongodb.net.

Windows:

copy

nslookup -type=SRV _mongodb._tcp.cluster.example.mongodb.net

Example output:

copy

_mongodb._tcp.XXXXX.XXX.mongodb.net service = 0 0 27017 XXXXX-00-00.4zh9o.mongodb.net.
_mongodb._tcp.XXXXX.XXX.mongodb.net service = 0 0 27017 XXXXX-00-01.4zh9o.mongodb.net.
_mongodb._tcp.XXXXX.XXX.mongodb.net service = 0 0 27017 XXXXX-00-02.4zh9o.mongodb.net.

Use these resolved values as host and port combinations:

copy

node-00.mongodb.net:27017
node-01.mongodb.net:27017
node-02.mongodb.net:27017

Configure the Agent using one of these host and port combinations.

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

Resolve Mongos Routers

For an SRV connection string like mongodb+srv://cluster.example.mongodb.net/, use the following commands:

Linux:

copy

dig +short SRV _mongodb._tcp.cluster.example.mongodb.net

Example output:

copy

0 0 27016 router-00.mongodb.net.
0 0 27016 router-01.mongodb.net.
0 0 27016 router-02.mongodb.net.

Windows:

copy

nslookup -type=SRV _mongodb._tcp.cluster.example.mongodb.net

Example output:

copy

_mongodb._tcp.cluster.example.mongodb.net service = 0 0 27016 router-00.mongodb.net.
_mongodb._tcp.cluster.example.mongodb.net service = 0 0 27016 router-01.mongodb.net.
_mongodb._tcp.cluster.example.mongodb.net service = 0 0 27016 router-02.mongodb.net.

Use these router addresses:

copy

router-00.mongodb.net:27016
router-01.mongodb.net:27016
router-02.mongodb.net:27016

Discovering Shard Members

To identify individual MongoDB instances within each shard, connect to a mongos router and execute:

copy

use admin
db.runCommand("getShardMap")

Example output:

copy

{
  "map": {
    "shard-0": "shard-0/router-00.mongodb.net:27017,router-01.mongodb.net:27017,router-02.mongodb.net:27017",
    "shard-1": "shard-1/router-10.mongodb.net:27017,router-11.mongodb.net:27017,router-12.mongodb.net:27017"
  },
  "hosts": {
    "router-00.mongodb.net:27017": "shard-0",
    "router-01.mongodb.net:27017": "shard-0",
    "router-02.mongodb.net:27017": "shard-0",
    "router-10.mongodb.net:27017": "shard-1",
    "router-11.mongodb.net:27017": "shard-1",
    "router-12.mongodb.net:27017": "shard-1",
    "config-00.mongodb.net:27017": "config",
    "config-01.mongodb.net:27017": "config",
    "config-02.mongodb.net:27017": "config"
  },
  "ok": 1
}

Shard Members Identified:

Choose one host from each shard for monitoring.

copy

--Shard 0 nodes
router-00.mongodb.net:27017
router-01.mongodb.net:27017
router-02.mongodb.net:27017

--Shard 1 nodes
router-10.mongodb.net:27017
router-11.mongodb.net:27017
router-12.mongodb.net:27017

--Config server nodes
config-00.mongodb.net:27017
config-01.mongodb.net:27017
config-02.mongodb.net:27017

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

Create the configuration file

For a MongoDB replica set, the Atatus Agent must connect to all replica members (primary, secondary, and arbiter if present). Update the configuration file by adding the following configuration to /etc/atatus-infra-agent/conf.d/mongodb.d/mongodb.yml:

copy

metrics:
  - hosts:
      - <HOST_REPLICA_1>:<PORT>   # Primary node
    username: atatus
    password: <REPLACE_PASSWORD>
    connection_scheme: "mongodb"
    db_name: "admin"
    options:
      connectTimeoutMS: 3000
      serverSelectionTimeoutMS: 2000
    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:
      connectTimeoutMS: 3000
      serverSelectionTimeoutMS: 2000
    dbm: true
    cluster_name: <CLUSTER_NAME>

Restart the Atatus Infra Agent to apply the changes:

copy

sudo service atatus-infra-agent restart

For a MongoDB sharded cluster, the Atatus Agent must connect to all mongos routers and config servers. Update the configuration file by adding the following configuration to /etc/atatus-infra-agent/conf.d/mongodb.d/mongodb.yml:

copy

metrics:
  ## Mongos router
  - hosts: 
      - <HOST_MONGOS>:<PORT>
    username: atatus
    password: <REPLACE_PASSWORD>
    connection_scheme: "mongodb"
    db_name: "admin"
    options: 
      connectTimeoutMS: 3000
      serverSelectionTimeoutMS: 2000
    dbm: true
    cluster_name: <CLUSTER_NAME>

  ## Shard 1
  - hosts: 
      - <HOST_SHARD1_1>:<PORT>  # Primary node
    username: atatus
    password: <REPLACE_PASSWORD>
    connection_scheme: "mongodb"
    db_name: "admin"
    options: 
      connectTimeoutMS: 3000
      serverSelectionTimeoutMS: 2000
    dbm: true
    cluster_name: <CLUSTER_NAME>

  - hosts: 
      - <HOST_SHARD1_2>:<PORT>  # Secondary node
    username: atatus
    password: <REPLACE_PASSWORD>
    connection_scheme: "mongodb"
    db_name: "admin"
    options: 
      connectTimeoutMS: 3000
      serverSelectionTimeoutMS: 2000
    dbm: true
    cluster_name: <CLUSTER_NAME>

  ## Shard 2
  - hosts: 
      - <HOST_SHARD2_1>:<PORT>  # Primary node
    username: atatus
    password: <REPLACE_PASSWORD>
    connection_scheme: "mongodb"
    db_name: "admin"
    options: 
      connectTimeoutMS: 3000
      serverSelectionTimeoutMS: 2000
    dbm: true
    cluster_name: <CLUSTER_NAME>

  - hosts: 
      - <HOST_SHARD2_2>:<PORT>  # Secondary node
    username: atatus
    password: <REPLACE_PASSWORD>
    connection_scheme: "mongodb"
    db_name: "admin"
    options: 
      connectTimeoutMS: 3000
      serverSelectionTimeoutMS: 2000
    dbm: true
    cluster_name: <CLUSTER_NAME>

  ## Config server
  - hosts: 
      - <HOST_CONFIG_1>:<PORT>  # Primary node
    username: atatus
    password: <REPLACE_PASSWORD>
    connection_scheme: "mongodb"
    db_name: "config"  # Specific database for config servers
    options: 
      connectTimeoutMS: 3000
      serverSelectionTimeoutMS: 2000
    dbm: true
    cluster_name: <CLUSTER_NAME>

  - hosts: 
      - <HOST_CONFIG_2>:<PORT>  # Secondary node
    username: atatus
    password: <REPLACE_PASSWORD>
    connection_scheme: "mongodb"
    db_name: "config"  # Specific database for config servers
    options: 
      connectTimeoutMS: 3000
      serverSelectionTimeoutMS: 2000
    dbm: true
    cluster_name: <CLUSTER_NAME>

Restart the Atatus Infra Agent to apply the changes:

copy

sudo service atatus-infra-agent restart