• EnglishEspañol日本語한국어Português
  • Log inStart now

MongoDB monitoring integration (legacy)


This legacy integration is set to reach end-of-life in 2024: we'll add a specific EOL date when we know it. We recommend using our newer MongoDB integration. For information on switching from the legacy integration to the new one, see our migration docs.

Our legacy MongoDB integration collects and sends inventory and metrics from your MongoDB cluster to our platform, where you can aggregate and visualize key performance metrics. We collect data on mongos and mongod instances, config servers, as well as on databases and collections to help pinpoint performance bottlenecks.

Compatibility and requirements

This legacy integration is compatible with MongoDB v3 and v4. Our newer MongoDB integration supports newer versions.

Before installing this legacy integration, make sure that you meet the following requirements:

Install and activate

If you want to install our legacy MongoDB integration, follow the instructions for your environment:

Additional notes:


Enabling your MongoDB server

In the MongoDB shell, execute the following commands to create a listCollections role and a new user. Then, assign clusterMonitor and listCollections roles to the new user. Note: Replace username, password, and similar user-specific values.

See the MongoDB documentation for details on creating users and roles.


Complete these steps on the mongos to be monitored. If mongod-level metrics are to be collected, such as host or replica set statistics, create the role and user on each mongod as well.

  1. In the MongoDB shell, enter use admin.

  2. Use the following command to create the listCollections role.

    role: "listCollections",
    privileges: [{
    resource: {db:"",collection:""},
    actions: ["listCollections"]
    roles: []
  3. Use the following commands to create a new user, and assign clusterMonitor and listCollections roles to the user.

    user: "username",
    pwd: "password",
    roles: [

Did this doc help with your installation?

Configure the integration

There are several ways to configure the integration, depending on how it was installed:

An integration's YAML-format configuration is where you can place required login credentials and configure how data is collected. Which options you change depend on your setup and preference.

The configuration file has common settings applicable to all integrations, such as interval, timeout, inventory_source. To read all about these common settings, refer to our Configuration Format document.


If you're still using our legacy configuration/definition files, please see standard configuration format for help.

Specific settings related to MongoDB are defined using the env section of the configuration file. These settings control the connection to your MongoDB instance as well as other security settings and features. The list of valid settings is described in the next section of this document.

The MongoDB integration can be configured to monitor either a full MongoDB cluster or a standalone MongoDB instance. To monitor a cluster, the host and port arguments should point to one of the mongos instances in your cluster. If you want to monitor a standalone instance, make sure host and port point to the mongod running the database.


SCRAM authentication isn't supported.

MongoDB instance settings

The MongoDB integration collects both metrics and inventory information. In the following table, see the Applies To column for the settings available to each collection.

The values for these settings can be defined in several ways:

  • Adding the value directly in the config file. This is the most common way.
  • Replacing the values from environment variables using the {{}} notation. This requires infrastructure agent v1.14.0 or higher. For more information, see our documentation about passthrough, or see the replacement example.
  • Using secrets management. Use this to protect sensitive information, such as passwords that would be exposed in plain text on the configuration file. For more information, see Secrets management.



Applies to


User-defined name to uniquely identify the cluster being monitored. Required.



Hostname or IP where MongoDB is running. Default is localhost.



Port on which MongoDB is listening. Default is 27017.



Username for accessing MongoDB server.



Password for the given user.



The database to authenticate against. Default is admin.



Use SSL when communicating with the MongoDB server. Default is false.



Location of SSL certificate on the host. Only required if SSL is true.



Skip the verification of the server's certificate chain and hostname. Default is false.



Location of PEM file containing Private Key and Client Certificate.



Passphrase to decrypt PEMKeyFile file.



Number of entities to collect metrics for concurrently. Default is 50.



A JSON map of database names to an array of collection names. If empty, defaults to all databases and collections.



Set to true to enable metrics-only collection. Default is false.


Set to true to enable inventory-only collection. Default is false.

Labels and custom attributes

You can further decorate your metrics using labels. Labels allow you to add key/value pair attributes to your metrics, which you can then use to query, filter, or group your metrics on.

Our default sample config file includes examples of labels; however, as they are not mandatory, you can remove, modify, or add new ones of your choice.

env: production
role: load_balancer

Example configurations

Find and use data

Data from this service is reported to an integration dashboard.

Metrics are attached to these event types:

  • MongoCollectionSample
  • MongoConfigServerSample
  • MongoDatabaseSample
  • MongodTopSample
  • MongoSample
  • MongodSample
  • MongosSample

You can query this data for troubleshooting purposes or to create custom charts and dashboards.

For more on how to find and use your data, see Understand integration data.

Metric data

The MongoDB integration collects the following metric data attributes. Some metric name are prefixed with a category indicator and a period, such as asserts. or collection..

Different metrics are available depending on whether a cluster or a standalone instance is being monitored. For a standalone instance, only MongodSample, MongoDatabaseSample, MongodTopSample, and MongoCollectionSample are collected. For a cluster, all event types are collected.

Inventory data

The MongoDB integration captures all command line options and runtime-configured parameters from each host in the cluster.

The data is available on the Inventory page, under the config/mongodb source. For more about inventory data, see Understand integration data.

Check the source code

This integration is open source software. That means you can browse its source code and send improvements, or create your own fork and build it.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.