MongoDB

Supported versions

Currently supported versions are 3.2 to 3.7 and 4.0 to 4.2. This includes support for metrics collection, configuration data collection, and manual tracing.

Configuration

Required Server/Database Permissions

To monitor MongoDB, you must have access to the following:

  • list databases.
  • serverStatus command.

If clustered:

  • local.system.replset
  • admin.replSetGetStatus on the primary node.

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

Authenticate as the admin user.

use admin
db.auth("admin", "YOUR_MONGODB_ADMIN_PASSWORD")

On MongoDB >= 3.x, use the createUser command.

db.createUser({
  "user":"stan",
  "pwd": "UNIQUEPASSWORD",
  "roles" : [
    {role: 'read', db: 'admin' },
    {role: 'clusterMonitor', db: 'admin'},
    {role: 'read', db: 'local' }
  ]
})

To enable in-depth metric monitoring, the agent requires user credentials to access monitoring information. You can configure it in the agent here <agent_install_dir>/etc/instana/configuration.yaml:

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

Note: source refers to the database or authentication source the user is defined. Please refer to the MongoDB documentation for more details.

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'

Keys need to be in Java Keystore format (JKS), those can be created using keytool.

Note: This will enable the Instana agent to connect to MongoDB server via SSL. Once it is connected, credentials (user/password) will be used to access the auth-database.

Metrics collection

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

Clients

Metric Description
Connections Number of current active clients connected to MongoDb server.

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)

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.