Skip to content
logo
Percona Monitoring and Management
MongoDB
Initializing search
    percona/pmm-doc
    percona/pmm-doc
    • Welcome
        • Network
        • Docker
        • Podman
        • Helm
        • Virtual Appliance
        • AWS Marketplace
        • Easy-install script
        • MySQL
        • MongoDB
          • Before you start
          • Create PMM account and set permissions
            • Create roles with privileges for backups and QAN
            • Create/update user and assign created roles
            • Permissions for advanced metrics
          • Profiling
            • Set profiling in the configuration file
            • Set profiling on the command Line
            • Set profiling in a mongo session
          • Add service
            • With the user interface
            • On the command line
            • Examples
              • Connect via UNIX socket
              • Connecting via SSL/TLS
          • Check the service
            • With the user interface
            • On the command line
            • Check data
              • Query Analytics
          • Remove service
            • With the user interface
            • On the command line
        • PostgreSQL
        • ProxySQL
        • Amazon RDS
        • Microsoft Azure
        • Google Cloud Platform
        • Linux
        • External Services
        • HAProxy
        • Remote instances
      • User Interface
      • Percona Alerting
        • Prepare a storage location
          • MongoDB backup prerequisites
          • Create MongoDB on-demand and scheduled backups
          • Create MongoDB PITR backups
          • Restore a MongoDB backup
          • MongoDB Backup and Restore support matrix
          • MySQL backup prerequisites
          • Create a MySQL backup
          • Restore a MySQL backup
        • Edit a scheduled backup
        • Delete a backup
        • Configure access control
        • Labels for access control
        • Create access roles
        • Manage access roles
        • Assign roles to users
        • Use Case
      • Query Analytics
      • Working with Advisors
      • Configure
      • Manage users
      • Upgrade
      • Secure
      • Optimize
      • Annotate
      • Share dashboards and panels
      • Extend Metrics
      • Resolve issues
        • Check Percona Portal account information
      • Architecture
      • UI components
      • PMM components and versions
      • Data handling in PMM
      • Develop Advisor checks
      • PMM Inventory
        • Manage dashboards
            • Advanced Data Exploration
            • VictoriaMetrics
            • VictoriaMetrics Agents Overview
            • Environment Summary
            • Kubernetes Pods Status
            • Kubernetes Volumes
          • DBaas
            • Disk Details
            • Network Details
            • Memory Details
            • Node Temperature Details
            • Nodes Compare
            • Nodes Overview
            • Node Summary
            • NUMA Details
            • Processes Details
            • Prometheus Exporters Overview
            • MySQL Command/Handler Counters Compare
            • MySQL InnoDB Compression Details
            • MySQL InnoDB Details
            • MySQL MyISAM/Aria Details
            • MySQL MyRocks Details
            • MySQL Instance Summary
            • MySQL Instances Compare
            • MySQL Instances Overview
            • MySQL Wait Event Analyses Details
            • MySQL Performance Schema Details
            • MySQL Query Response Time Details
            • MySQL Replication Summary
            • MySQL Group Replication Summary
            • MySQL Table Details
            • MySQL User Details
            • MySQL TokuDB Details
            • Experimental MongoDB Collection Details
            • Experimental MongoDB Oplog Details
            • MongoDB Cluster Summary
            • MongoDB Instance Summary
            • MongoDB Instances Overview
            • MongoDB Instances Compare
            • MongoDB ReplSet Summary
            • MongoDB InMemory Details
            • MongoDB MMAPv1 Details
            • MongoDB WiredTiger Details
            • PostgreSQL Instance Summary
            • PostgreSQL Instances Compare
            • Experimental PostgreSQL Vacuum Monitoring
          • ProxySQL Dashboards
            • PXC/Galera Cluster Summary
            • Experimental PXC/Galera Cluster Summary
            • PXC/Galera Nodes Compare
            • HAProxy Instance Summary
        • pmm-admin - PMM Administration Tool
        • pmm-agent - PMM Client agent
      • API
      • VictoriaMetrics
      • ClickHouse
      • PostgreSQL
      • Glossary
      • Introduction
      • DBaaS architecture
        • Setting up DBaaS
        • Create a Kubernetes Cluster
        • Deleting Kubernetes clusters
        • Activating DBaaS
        • Add a Kubernetes cluster automatically
        • Add a Kubernetes cluster manually
        • Manage allowed component versions
          • OLM installation
          • Operators installation
        • Add a DB Cluster
        • Manage a DB Cluster
        • Delete a DB Cluster
        • Create a database cluster from a template
      • Backup and restore
    • FAQ
      • PMM 2.39.0
      • PMM 2.38.1
      • PMM 2.38.0
      • PMM 2.37.1
      • PMM 2.37.0
      • PMM 2.36.0
      • PMM 2.35.0
      • PMM 2.34.0
      • PMM 2.33.0
      • PMM 2.32.0
      • PMM 2.31.0
      • PMM 2.30.0
      • PMM 2.29.1
      • PMM 2.29.0
      • PMM 2.28.0
      • PMM 2.27.0
      • PMM 2.26.0
      • PMM 2.25.0
      • PMM 2.24.0
      • PMM 2.23.0
      • PMM 2.22.0
      • PMM 2.21.0
      • PMM 2.20.0
      • PMM 2.19.0
      • PMM 2.18.0
      • PMM 2.17.0
      • PMM 2.16.0
      • PMM 2.15.1
      • PMM 2.15.0
      • PMM 2.14.0
      • PMM 2.13.0
      • PMM 2.12.0
      • PMM 2.11.1
      • PMM 2.11.0
      • PMM 2.10.1
      • PMM 2.10.0
      • PMM 2.9.1
      • PMM 2.9.0
      • PMM 2.8.0
      • PMM 2.7.0
      • PMM 2.6.1
      • PMM 2.6.0
      • PMM 2.5.0
      • PMM 2.4.0
      • PMM 2.3.0
      • PMM 2.2.2
      • PMM 2.2.1
      • PMM 2.2.0
      • PMM 2.1.0
      • PMM 2.0.1
      • PMM 2.0.0
      • Copyright and licensing information
      • Trademark policy

    • Before you start
    • Create PMM account and set permissions
      • Create roles with privileges for backups and QAN
      • Create/update user and assign created roles
      • Permissions for advanced metrics
    • Profiling
      • Set profiling in the configuration file
      • Set profiling on the command Line
      • Set profiling in a mongo session
    • Add service
      • With the user interface
      • On the command line
      • Examples
        • Connect via UNIX socket
        • Connecting via SSL/TLS
    • Check the service
      • With the user interface
      • On the command line
      • Check data
        • Query Analytics
    • Remove service
      • With the user interface
      • On the command line

    MongoDB¶

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

    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.

    Run the example codes below in a mongo session to:

    • create custom roles with the privileges required for creating/restoring backups and working with Query Analytics (QAN)
    • create/update a database user with these roles above, plus the built-in clusterMonitor role

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

    Create roles with privileges for backups and QAN¶

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

    Create/update user and assign created roles¶

     db.getSiblingDB("admin").createUser({
        user: "pmm",
        pwd: "pmm",
        roles: [
            { role: "explainRole", db: "admin" },
            { role: "clusterMonitor", db: "admin" },
            { role: "read", db: "local" },
            { "db" : "admin", "role" : "readWrite", "collection": "" },
            { "db" : "admin", "role" : "backup" },
            { "db" : "admin", "role" : "clusterMonitor" },
            { "db" : "admin", "role" : "restore" },
            { "db" : "admin", "role" : "pbmAnyAction" }
        ]
    })
     db.getSiblingDB("admin").updateUser("pmm", {
        roles: [
            { role: "explainRole", db: "admin" },
            { role: "clusterMonitor", db: "admin" },
            { role: "read", db: "local" },
            { "db" : "admin", "role" : "readWrite", "collection": "" },
            { "db" : "admin", "role" : "backup" },
            { "db" : "admin", "role" : "clusterMonitor" },
            { "db" : "admin", "role" : "restore" },
            { "db" : "admin", "role" : "pbmAnyAction" }
        ]
    })
    

    Permissions for advanced metrics¶

    To fetch advanced metrics, use the following to provide additional privileges to an existing PMM user:

    {
    resource : {
        db : "",
        collection : "system.profile"
        },
    actions : [
        "collStats",
        "dbStats",
        "indexStats"
       ]
    }
    

    If the role explainRole already exists, then you can use the following command to provide additional privileges:

     db.runCommand({
        grantPrivilegesToRole: "explainRole",
        privileges: [{
            "resource": {
                "db": "",
                "collection": "system.profile"
            },
            "actions": [
                "indexStats",
                "dbStats",
                "collStats"
            ]
        }]
    })
    

    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 100th 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 → Inventory.

    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 → Inventory.
    2. In the Services tab, verify the Service name, Addresses, and any other relevant values used when adding the service.
    3. In the Options column, expand the Details section and check that the Agents are using the desired data source.
    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. 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 → Inventory.
    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

    Contact us

    For free technical help, visit the Percona Community Forum.

    To report bugs or submit feature requests, open a JIRA ticket.

    For paid support and managed or consulting services , contact Percona Sales.


    Last update: 2023-09-22
    Percona LLC, © 2023
    Made with Material for MkDocs

    Cookie consent

    We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better. Read more about Percona Cookie Policy.