MongoDB

How to set up PMM to monitor a MongoDB or Percona Server for MongoDB database instance.

Summary

• Create PMM account and set permissions.
• Configure profiling.
• Add service.
• Check service.

Before you start

Check that:

• PMM Server is installed and running with a known IP address or hostname accessible from the client node.
• PMM Client is installed and the node is registered with PMM Server.
• You have superuser (root) access on the client host.
• You have adminUserAnyDatabase or superuser role privilege to any database servers that you want to monitor.
• Your MongoDB server is version 4.0 or higher.

Create PMM account and set permissions

We recommend using a dedicated account to connect PMM Client to the monitored database instance.

This example creates a new custom role with the privileges needed by the Query Analyzer, and adds a database user with that role plus the built-in clusterMonitor role.

Values for username (user) and password (pwd) are examples. Replace them before using this code.

Run this in a mongo session.

db.getSiblingDB("admin").createRole({
    role: "explainRole",
    privileges: [{
        resource: {
            db: "",
            collection: ""
            },
        actions: [
            "listIndexes",
            "listCollections",
            "dbStats",
            "dbHash",
            "collStats",
            "find"
            ]
        }],
    roles:[]
})

db.getSiblingDB("admin").createUser({
   user: "pmm_mongodb",
   pwd: "password",
   roles: [
      { role: "explainRole", db: "admin" },
      { role: "clusterMonitor", db: "admin" },
      { role: "read", db: "local" }
   ]
})

Profiling

To use PMM Query Analytics, you must turn on MongoDB’s profiling feature.

You can set profiling:

• permanently, by editing the MongoDB configuration file and restarting the database instance (recommended);
• when starting MongoDB, by passing arguments to mongod on the command line;
• until the next database instance restart, by running a command in a mongo session.

Profiling is turned off by default as it can adversely affect the performance of the database server.

Set profiling in the configuration file

1. Edit the configuration file (usually /etc/mongod.conf).

2. Create or add this to the operationProfiling section. (Read more.)

   operationProfiling:
     mode: all
     slowOpThresholdMs: 200
     rateLimit: 100 # (Only available with Percona Server for MongoDB.)
   

   Important

   This is a YAML file. Indentation matters.

3. Restart the mongod service. (Example for systemd.)

   systemctl restart mongod
   

Set profiling on the command Line

mongod --dbpath=DATABASEDIR --profile 2 --slowms 200 --rateLimit 100

• --dbpath: The path to database files (usually /var/lib/mongo).
• --profile: The MongoDB profiling level. A value of 2 tells the server to collect profiling data for all operations. To lower the load on the server, use a value of 1 to only record slow operations.
• --slowms: An operation is classified as slow if it runs for longer than this number of milliseconds.

• --rateLimit: (Only available with Percona Server for MongoDB.) The sample rate of profiled queries. A value of 100 means sample every 100^th fast query. (Read more.)

  Caution

  Smaller values improve accuracy but can adversly affect the performance of your server.

Set profiling in a mongo session

In a mongo session, the profiler should be enabled per database. For example, to enable the profiler in the testdb, run this:

use testdb
db.setProfilingLevel(2, {slowms: 0})

If you have already added a service, you should remove it and re-add it after changing the profiling level.

Add service

When you have configured your database server, you can add a MongoDB service with the user interface or on the command line.

With the user interface

1. Select Configuration → PMM Inventory → Add Instance.

2. Select MongoDB – Add a remote instance.

3. Enter or select values for the fields.

4. Click Add service.

On the command line

Use pmm-admin to add the database server as a service using one of these example commands.

When successful, PMM Client will print MongoDB Service added with the service’s ID and name. Use the --environment and -custom-labels options to set tags for the service to help identify them.

Tips

• When adding nodes of a sharded cluster, add each node separately using the --cluster mycluster option for the MongoDB Cluster Summary dashboard to populate correctly.
• Atlas doesn’t support direct connections. When connecting to an Atlas instance, use the pmm-admin option --direct-connection=false. (Doing so will prevent replicaset status from working and the MongoDB Overview dashboard widget will show invalid values.)

Examples

pmm-admin add mongodb \
--username=pmm_mongodb --password=password \
--query-source=profiler --cluster=mycluster

pmm-admin add mongodb \
--username=pmm_mongodb --password=password \
mongo 127.0.0.1:27017

pmm-admin add mongodb \
--username=pmm_mongodb --password=password \
--service-name=mymongosvc --host=127.0.0.1 --port=27017

Connect via UNIX socket

pmm-admin add mongodb --socket=/tmp/mongodb-27017.sock

Connecting via SSL/TLS

pmm-admin add mongodb --tls \
--tls-certificate-key-file=PATHTOCER \
--tls-certificate-key-file-password=IFPASSWORDTOCERTISSET \
--tls-ca-file=PATHTOCACERT
--authentication-mechanism=AUTHENTICATION-MECHANISM
--authentication-database=AUTHENTICATION-DATABASE

where:

• PATHTOCERT: Path to TLS certificate file.
• IFPASSWORDTOCERTISSET: Password for TLS certificate file.
• PATHTOCACERT: Path to certificate authority file.
• AUTHENTICATION-MECHANISM: Authentication mechanism. Default is empty. Use MONGODB-X509 for SSL certificates.
• AUTHENTICATION-DATABASE: Authentication database. Default is empty. Use $external for SSL certificates.

Check the service

With the user interface

1. Select Configuration → PMM Inventory → Inventory list.
2. Look in the Services tab for a matching Service Type (MongoDB), Service name, Addresses, and any other values used when adding the service.
3. Look in the Agents tab to check the desired data source is being used.
4. If your MongoDB instance is configured to use TLS, click on the Use TLS for database connection check box and fill in TLS certificates and keys.
   1. If you use TLS, the authentication mechanism is automatically set to MONGODB-X509.

On the command line

Look for your service in the output of this command.

pmm-admin inventory list services --service-type=mongodb

Check data

1. Open the MongoDB Instances Overview dashboard.
2. Set the Service Name to the newly-added service.

Query Analytics

1. Open PMM Query Analytics.
2. In the Filters panel:
   1. Under Service Name, select your service.
   2. Under Service Type select mongodb.

Remove service

With the user interface

1. Select Configuration → PMM Inventory → Inventory List.
2. In the first column, click the tick box for the service you want to remove.
3. Click Delete.
4. On the Confirm action dialog window:
   1. (Optional) Select Force mode to also delete associated agents.
   2. Click Proceed.

On the command line

pmm-admin remove mongodb SERVICE_NAME

• SERVICE_NAME: The name the service was added as. (Find it with pmm-admin list.)

See also

• pmm-admin add mongodb
• Troubleshooting connection difficulties

---

Last update: 2022-05-23