• /
  • Log in

MongoDB monitoring integration

Our 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, mongods, and config servers, as well as on databases and collections to help pinpoint performance bottlenecks.

Read on to install the integration, and to see what data we collect.

Compatibility and requirements

Our integration is compatible with MongoDB v3.0+. MongoDB Atlas is supported for tiers M10 and above.

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

Quick start

Instrument your MongoDB cluster quickly and send your telemetry data with guided install. Our guided install creates a customized CLI command for your environment that downloads and installs the New Relic CLI and the infrastructure agent.

A screenshot of the guided install CLI.

Ready to get started? Click one of these button to try it out.

Guided install

Our guided install uses the infrastructure agent to set up the MongoDB integration. Not only that, it discovers other applications and log sources running in your environment and then recommends which ones you should instrument.

The guided install works with most setups. But if it doesn't suit your needs, you can find other methods below to get started monitoring your MongoDB database.

MongoDB users and privileges

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: username, password, and similar user-specific values must be replaced.

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: [

Install and activate

To install the MongoDB integration, follow the instructions for your environment:

Additional notes:

Configure the integration

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.

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

Config options are below. For an example configuration, see Example config file.


With secrets management, you can configure on-host integrations with New Relic infrastructure's agent to use sensitive data (such as passwords) without having to write them as plain text into the integration's configuration file. For more information, see Secrets management.


The configuration accepts the following configuration commands:

  • all: captures inventory and metrics for each node in the Mongo cluster.
  • inventory: captures only the inventory for each node in the cluster.
  • metrics: captures only the metrics for each node in the cluster.


The commands accept the following arguments:

  • cluster_name: A user-defined name to uniquely identify the cluster being monitored. Required.
  • username: The username for the MongoDB connection. Note: this should be the user entered above.
  • password: The password for the MongoDB connection. Note: this should be the password entered above.
  • authSource: The database to authenticate against. Default: admin.
  • host: The hostname on which a MongoDB instance is running. Default: localhost.
  • port: The port on which a MongoDB instance is running. Default: 27017.
  • ssl: Indicates whether SSL is enabled. Default: false.
  • ssl_ca_certs: Path to a Certificate Authority (CA) file, if SSL is enabled.
  • ssl_insecure_skip_verify: Skip verification of the certificate sent by the host. This can make a connection susceptible to man-in-the-middle attacks and should only be used for testing. Default: false.
  • filters: A JSON map of database names to an array of collection names. If empty, defaults to all databases and collections. If the list of collections is null, collects all collections for the database. Example: {"db1":null,"db2":["collection1","collection2"],"db3":[]}.
  • concurrent_collections: The number of entities to collect metrics for concurrently. Used to tune down CPU and memory requirements. Default: 50.


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 instead monitor a standalone instance, host and port should point to the mongod running the database.

Example configuration

Example mongodb-config.yml file configuration:

For more about the general structure of on-host integration configuration, see Configuration.

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.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.