• Log inStart now

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 and mongod instances, 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 and v4. MongoDB Atlas is supported for tiers M10 and above.

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

Install and activate

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

Additional notes:

Configuration

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

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

Tip

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.

    db.createRole({
    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.

    db.createUser({
        user: "username",
        pwd: "password",
        roles: [
            "clusterMonitor",
            "listCollections"
        ]
    })

While you wait for your data to come in...

Did this doc help you install?

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.

Important

If you are still using our legacy configuration/definition files, please refer to our documentation about 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.

Tip

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.

Setting

Description

Applies to

MONGODB_CLUSTER_NAME

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

Metrics/Inventory

HOST

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

Metrics/Inventory

PORT

Port on which MongoDB is listening. Default is 27017.

Metrics/Inventory

USERNAME

Username for accessing MongoDB server.

Metrics/Inventory

PASSWORD

Password for the given user.

Metrics/Inventory

AUTH_SOURCE

The database to authenticate against. Default is admin.

Metrics/Inventory

SSL

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

Metrics/Inventory

SSL_CA_CERTS

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

Metrics/Inventory

SSL_INSECURE_SKIP_VERIFY

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

Metrics/Inventory

PEM_KEY_FILE

Location of PEM file containing Private Key and Client Certificate.

Metrics/Inventory

PASSPHRASE

Passphrase to decrypt PEMKeyFile file.

Metrics/Inventory

CONCURRENT_COLLECTIONS

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

Metrics

FILTERS

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

Metrics

METRICS

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

INVENTORY

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.

labels:
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 © 2022 New Relic Inc.

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