Ubuntu

1. Install mongosh

Advanced collection requires mongosh on the agent's host. Without it the agent silently falls back to basic metrics only.

mongosh --version

If it is missing:

sudo apt-get install -y mongodb-mongosh

2. Create a monitoring user

mongosh --host 127.0.0.1 --port 27017

use admin
db.createUser({
  user: "watchlog_monitor",
  pwd: "your_password",
  roles: [
    { role: "clusterMonitor", db: "admin" },
    { role: "readAnyDatabase", db: "admin" }
  ]
})

clusterMonitor covers server status and replication; readAnyDatabase adds per-collection storage and index usage. Grant read per database instead if you prefer — the databases you do not grant simply do not appear.

3. Configure the agent

Navigate to the agent configuration directory:

cd /opt/watchlog-agent
sudo vim integration.json

Locate the MongoDB object:

{ "service": "mongodb", "monitor": false, "host": "localhost", "port": "27017", "username": "", "password": "", "authDatabase": "admin", "tls": false }

3. Change `"monitor"` from `false` to `true`:
```diff
-  "monitor": false
+  "monitor": true

Set username, password and authDatabase.

authDatabase is where the user is defined, not the database you want to monitor — for the user created above that is admin. This is the single most common misconfiguration.

{
  "service": "mongodb",
  "monitor": true,
  "host": "localhost",
  "port": "27017",
  "username": "watchlog_monitor",
  "password": "your_password",
  "authDatabase": "admin",
  "tls": false
}

Save the file and reload the agent:
```
sudo pm2 reload watchlog-agent
```

Verify

Check that the credentials work the way the agent will use them:

mongosh --host localhost --port 27017 \
  -u watchlog_monitor -p 'your_password' \
  --authenticationDatabase admin \
  --quiet --eval 'db.adminCommand({ serverStatus: 1 }).ok'

1 means the agent will connect. Then confirm the richer commands are permitted:

mongosh --host localhost --port 27017 \
  -u watchlog_monitor -p 'your_password' \
  --authenticationDatabase admin \
  --quiet --eval 'db.adminCommand({ listDatabases: 1 }).databases.length'

TLS

Set "tls": true and the agent adds --tls to the shell invocation:

{
  "service": "mongodb",
  "monitor": true,
  "host": "mongo.internal",
  "port": "27017",
  "username": "watchlog_monitor",
  "password": "your_password",
  "authDatabase": "admin",
  "tls": true
}

The agent uses the system trust store. If your deployment uses a private CA, make sure it is installed on the agent's host (/usr/local/share/ca-certificates/ then update-ca-certificates).

Slow queries (optional)

MongoDB writes slow operations to system.profile only when the profiler is enabled, and it is off by default. Watchlog never enables it for you — profiling has a real write cost.

Enable it on the databases you want traced:

use myapp
db.setProfilingLevel(1, { slowms: 100 })

Then in integration.json:

"slowQuery": {
  "enabled": true,
  "threshold": 100,
  "maxPerScrape": 100
}

Query text is normalized before it leaves your host — literal values become placeholders, so the stored shape is { userId: "?" } rather than your customers' data.

To turn profiling back off:

use myapp
db.setProfilingLevel(0)

Replica sets

Point the agent at any member. replSetGetStatus returns the whole set, so one entry covers every member's state, health and lag.

Running the agent on each member is also fine — each reports the same set from its own perspective, which is how you tell a member that has lost contact with the primary from one that is merely lagging.