• /
  • English日本語
  • 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
EU 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.

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"
    ]
})

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 this document 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.

Tip

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.

MongoDB Instance Settings

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

Setting

Description

Default

Applies to

MONGODB_CLUSTER_NAME

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

N/A

Metrics/Inventory

HOST

Hostname or IP where MongoDB is running.

localhost

Metrics/Inventory

PORT

Port on which MongoDB is listening.

27017

Metrics/Inventory

USERNAME

Username for accessing MongoDB server.

N/A

Metrics/Inventory

PASSWORD

Password for the given user.

N/A

Metrics/Inventory

AUTH_SOURCE

The database to authenticate against.

admin

Metrics/Inventory

SSL

Use SSL when communicating with the MongoDB server.

false

Metrics/Inventory

SSL_CA_CERTS

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

N/A

Metrics/Inventory

SSL_INSECURE_SKIP_VERIFY

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

false

Metrics/Inventory

PEM_KEY_FILE

Location of PEM file containing Private Key and Client Certificate.

N/A

Metrics/Inventory

PASSPHRASE

Passphrase to decrypt PEMKeyFile file.

N/A

Metrics/Inventory

CONCURRENT_COLLECTIONS

Number of entities to collect metrics for concurrently.

50

Metrics

FILTERS

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

N/A

Metrics

METRICS

Set to true to enable metrics-only collection.

false

INVENTORY

Set to true to enable inventory-only collection.

false

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+. Read more here or see the example below.
  • 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.

Labels/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..

Tip

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.
CareersTerms of ServiceDCMA PolicyPrivacy NoticeCookie PolicyUK Slavery Act