Monitoring MongoDB

The MongoDB sensor is automatically deployed and installed after you install the Instana agent.

Supported information

Supported operating systems

The supported operating systems of the MongoDB sensor are consistent with host agent requirements, which can be checked in the Supported operating systems section of each host agent, such as Supported operating systems for Unix.

Supported versions

Instana supports the following versions of MongoDB and MongoDB Atlas for metrics collection and configuration data collection:

  • MongoDB 3.2.x
  • MongoDB 3.4.x
  • MongoDB 3.6.x
  • MongoDB 4.0.x
  • MongoDB and MongoDB Atlas 4.2.x
  • MongoDB and MongoDB Atlas 4.4.x
  • MongoDB and MongoDB Atlas 5.0.x
  • MongoDB and MongoDB Atlas 6.0.x
  • MongoDB Rapid release 5.1.x for Atlas
  • MongoDB Rapid release 5.2.x for Atlas
  • MongoDB Rapid release 5.3.x for Atlas
  • MongoDB Rapid release 6.3.x for Atlas

Supported client-side tracing

For this technology, Instana supports client-side tracing for the following languages and runtimes:

Configuration

MongoDB with disabled authentication

No actions are required. Monitoring of MongoDB with disabled authentication happens automatically without providing any configurations in the configuration.yaml file.

MongoDB with enabled authentication

To monitor MongoDB, you need to create a user with the following minimum roles:

  • read - on admin database
  • clusterMonitoer - on admin database
  • read - on local database

In a mongo shell, create a user for the Instana Agent in the admin database:

  1. Authenticate as the admin user:
    use admin
db.auth("admin", "YOUR_MONGODB_ADMIN_PASSWORD")
  2. For MongoDB 3.x and later versions, run the createUser command:
    db.createUser({
  "user":"stan",
  "pwd": "UNIQUEPASSWORD",
  "roles" : [
    {role: 'read', db: 'admin' },
    {role: 'clusterMonitor', db: 'admin'},
    {role: 'read', db: 'local' }
  ]
})

Note

  • If you are using MongoDB Atlas, the user (with all the assigned roles) can be created only through MongoDB Atlas management console.

    After the user is created, you can configure it in the agent configuration file:

    com.instana.plugin.mongodb:
  user: 'stan'
  source: 'admin'
  password: 'UNIQUEPASSWORD'

  • source refers to the database or authentication source the user is defined. Refer to the MongoDB documentation for more details.

MongoDB Atlas support

Instana agent supports remote monitoring of MongoDB Atlas clusters residing in different projects and organizations. For the Instana agent to be able to monitor your MongoDB Atlas organizations, it needs to be configured here <agent_install_dir>/etc/instana/configuration.yaml:

com.instana.plugin.mongodb:
  user: 'stan'
  source: 'admin'
  password: 'UNIQUEPASSWORD'
  atlas:
    - publicKey: 'your public key'
      privateKey: 'your private key'
    - publicKey: 'your public key'
      privateKey: 'your private key'

Note

  • The API key that consists of a public and private key needs to be defined on the MongoDB Atlas organization level. The minimum required Organization Permission is Organization Read Only.
  • If you are using MongoDB Atlas, the user with all the assigned roles can be created only through MongoDB Atlas management console.

SSL/TLS support

For the Instana agent to securely connect to your MongoDB server, it needs to be configured here <agent_install_dir>/etc/instana/configuration.yaml:

com.instana.plugin.mongodb:
  ...
  sslTrustStore: '/path/to/truststore.jks'
  sslTrustStorePassword: 'mongoTsPassword'
  sslKeyStore: '/path/to/sslKeyStoreFile.jks'
  sslKeyStorePassword: 'mongoKsPassword'

To enable the SSL/TLS support feature, keys need to be in the Java Keystore format (JKS). The keytool can be used to create these keys.

Note

This feature will enable the Instana Agent to connect to MongoDB server by using SSL/TLS. Once it is connected, credentials (user/password) will be used to access the auth-database.

Metrics collection

To view the metrics, select Infrastructure in the sidebar of the Instana User interface, click a specific monitored host, and then you can see a host dashboard with all the collected metrics and monitored processes.

Configuration data

  • Version
  • Port
  • Storage engine
  • Databases

Performance metrics

Database Activity

Metric Description
Read Number of documents read
Inserted Number of documents inserted
Uploaded Number of documents uploaded
Deleted Number of documents deleted

Opcounters

Metric Description
Update The total number of update operations that are received after the mongod instance last started.
Insert The total number of insert operations that are received after the mongod instance last started.
Query The total number of queries that are received after the mongod instance last started.
Delete The total number of the delete operations after the mongod instance last started.
getMore The total number of the getMore operations after the mongod instance last started.

Memory

Metric Description
Virtual This includes the virtual memory for the entire MongoDB process. If you have journaling turned on, this will typically be twice the size of your mapped memory.
Mapped This is the amount of virtual memory used by the MongoDB progress to map your database into memory. This will typically be the size of your database.

Clients

Metric Description
Connections Number of current active clients that are connected to MongoDB server.
ActiveClients writers The number of active client connections that perform write operations.
ActiveClients readers The number of the active client connections that perform read operations.

Databases (per database)

Metric Description
Database Size Database size

Replica Set (if exists)

Metric Description
Apply Ops Number of internal apply operations
Apply Batches Number of internal apply batches
Apply Batches Total (ms) Duration of apply batches in milliseconds
Buffer Count Number of buffers
Buffer Size Buffer size
Network Ops Number of network operations
Network Bytes Size of network operations
Preload Docs Number of preload docs operation
Preload Docs Total (ms) Duration of preload docs in milliseconds
Preload Idx Number of preload idx operation
Preload Idx Total (ms) Duration of preload idx in milliseconds
Replication Lag Delay between a write operation on the primary and its copy to a secondary (milliseconds)

Atlas Cluster (if exists)

Metric Description
Read Number of documents read
Inserted Number of documents inserted
Uploaded Number of documents uploaded
Deleted Number of documents deleted
Connections Number of clients currently connected
Network Ops Number of network operations
Network Bytes Size of network operations

Health Signatures

For each sensor, there is a curated knowledgebase of health signatures that are evaluated continuously against the incoming metrics and are used to raise issues or incidents depending on user impact.

Built-in events trigger issues or incidents based on failing health signatures on entities, and custom events trigger issues or incidents based on the thresholds of an individual metric of any given entity.

For information about built-events for the MongoDB sensor, see the Built-in events reference.