MongoDB

The MongoDB integration requires CXDOT Collector 1.12.0 or greater. MongoDB is a document database. Use the MongoDB integration to collect operation, connection, lock, cache, replication, and storage metrics from MongoDB servers running in your environment. The MongoDB integration supports MongoDB 6.0 or greater.

​

Supported telemetry types

The MongoDB integration supports these telemetry types:

​

Prerequisites

The MongoDB integration has the following prerequisites:

• Run MongoDB 6.0 or greater. To find the version of a server, run db.version() in mongosh.
• Create a monitoring user in MongoDB for the CXDOT Collector. Connect to the server with mongosh as a user that can create users. On a replica set, connect to the primary. Grant the monitoring user the clusterMonitor role on the admin database and the read role on the local database:
  db.getSiblingDB("admin").createUser({
    user: "cxdot",
    pwd: passwordPrompt(),
    roles: [
      { role: "clusterMonitor", db: "admin" },
      { role: "read", db: "local" }
    ]
  })
  
  Replace cxdot with the username for your environment. The clusterMonitor role grants read-only access to server, replication, and database statistics. The read role on local lets the Collector read the replication operations log.
• On a sharded cluster, create the monitoring user in two places. Create it through a mongos router, which stores the user on the config servers, so that the Collector can authenticate to each mongos and each config server member. Then create the same user on each shard’s replica set by connecting directly to that shard’s primary. The Collector connects directly to each shard member, and a direct connection authenticates against the shard’s own shard-local users.
• Make port 27017, or your custom MongoDB port, reachable from the CXDOT Collector.

​

Configure

The MongoDB integration is enabled by default and collects from pods and Services that carry autodiscovery annotations for MongoDB. For more information, see autodiscovery. The integration supports standalone servers, replica sets, and sharded clusters. Each server is a target of its own: every mongod, including each replica set member, shard member, and config server member, and every mongos router. The Collector connects directly to each target and reports that server’s own metrics. Some metrics come only from servers in certain roles:

• Storage statistics for each database come from a standalone server, from the primary of a replica set that isn’t part of a sharded cluster, and from each mongos router. Other replica set members, shard members, and config server members report these statistics for their local database only.
• Connection pool metrics come from each mongos router and from each shard member and config server member.
• The logical session count comes from each mongos router.
• Replication metrics come from replica set members.

To configure the integration, follow these steps:

1. Add autodiscovery annotations to every pod that runs a mongod or a mongos. The annotations supply each target’s endpoint and the monitoring user’s credentials. Metrics from discovered pods arrive with that pod’s Kubernetes metadata attached.
2. Optional: Configure static targets, for example MongoDB servers outside your Kubernetes cluster, instead of discovered targets. List every server as its own entry. One elected replica of the cluster-tier CXDOT Collector collects from static targets, so provide the password to that tier through a Kubernetes Secret. For more information, see architecture. To add the mongodb.cluster.name attribute to every metric from a target, set that entry’s cluster_name. For example, add the following to the Helm values file for your CXDOT Collector:
   clusterCollector:
     extraEnv:
       - name: MONGODB_PASSWORD
         valueFrom:
           secretKeyRef:
             name: mongodb-credentials
             key: password
   
   config:
     integrations:
       mongodb:
         instances:
           - endpoint: mongodb-0.example.com:27017
             cluster_name: orders
           - endpoint: mongodb-1.example.com:27017
             cluster_name: orders
         username: cxdot
         password: "${env:MONGODB_PASSWORD}"
   
   When you configure static targets, this integration instance collects from exactly those targets and stops collecting from discovered targets.
3. Optional: Collect from discovered targets and static targets at the same time by configuring a second instance of the integration. For example, add the following to the Helm values file for your CXDOT Collector:
   config:
     integrations:
       mongodb: {}
       mongodb/static:
         instances:
           - endpoint: mongodb.example.com:27017
         username: cxdot
         password: "${env:MONGODB_PASSWORD}"
   
   The mongodb key is the default instance, which collects from discovered targets. The mongodb/static key defines a named instance that collects from the static targets and reads its password from the MONGODB_PASSWORD environment variable that the previous step defines. Keep the mongodb key: after you configure any MongoDB instance, the CXDOT Collector runs only the instances that you configure.
4. Optional: Collect additional metric groups. By default, the integration collects none of them. These settings apply to static targets. Discovered targets take the matching settings from their autodiscovery annotations. For example, add the settings to the mongodb/static instance from the previous step in the Helm values file for your CXDOT Collector:
   config:
     integrations:
       mongodb: {}
       mongodb/static:
         instances:
           - endpoint: mongodb.example.com:27017
         username: cxdot
         password: "${env:MONGODB_PASSWORD}"
         additional_metrics:
           - metrics.commands
           - tcmalloc
           - top
           - collection
         collection_stats:
           databases:
             - shop
           collections:
             - orders
             - customers
   
   The groups differ in what they cost your servers:
   • metrics.commands and tcmalloc read the server status the Collector already reads at every collection interval, so they add no load.
   • top runs one top command on every mongod that isn’t an arbiter at every collection interval. For each collection the server has run an operation on since it started, it produces a count and a time series for each operation type, and a count and a time series for each kind of lock access.
   • collection runs on a standalone server, on the primary of a replica set that isn’t part of a sharded cluster, and on every mongos router you configure as a target. Each router reports the statistics of every collection in the sharded cluster, so enable the group on an instance that lists one router, or the Collector reads the same statistics once per router and reports each collection once per router. It runs every collection_stats.interval and reads each collection’s statistics with one aggregation per collection. Set collection_stats.databases and collection_stats.collections to limit which databases and collections it reads. When collection_stats.collections is empty, the Collector lists the collections of each database and reads at most collection_stats.max_collections_per_database of them.
5. Optional: Collect index access counts. The integration doesn’t collect them by default, because collecting them adds load on a server with many collections: at every collection interval, the Collector lists the collections of each database and reads the index statistics of each collection. This setting applies to static targets. Discovered targets take it from their autodiscovery annotations. For example, add the setting to the mongodb/static instance in the Helm values file for your CXDOT Collector:
   config:
     integrations:
       mongodb: {}
       mongodb/static:
         instances:
           - endpoint: mongodb.example.com:27017
         username: cxdot
         password: "${env:MONGODB_PASSWORD}"
         collect_index_stats: true
   
6. Optional: Collect the CPU usage of the mongod and mongos processes. The MongoDB integration doesn’t report it. Enable per-process metrics in the Host integration on the nodes that run your servers. For example, add the following to the Helm values file for your CXDOT Collector:
   config:
     integrations:
       host:
         process:
           enabled: true
           config:
             include:
               match_type: strict
               names:
                 - mongod
                 - mongos
             metrics:
               process.cpu.utilization:
                 enabled: true
   
7. Optional: Disable the integration. For example, add the following to the Helm values file for your CXDOT Collector:
   config:
     integrations:
       mongodb:
         enabled: false
   

​

Validate

To validate the MongoDB integration, follow these steps:

1. In the Live Telemetry Analyzer, add the following filters:
   • __name__=cxdot.integration.target.health
   • cxdot.integration.name=mongodb
   Confirm that each target reports 1, identified by its server.address and server.port attributes. A value of 0 means that the CXDOT Collector couldn’t connect to the target or authenticate to it, for example because the server rejected the monitoring user’s credentials.
2. In Metrics Explorer, run the following query while clients send operations to the MongoDB servers:
   sum by ("server.address", "server.port") (rate({"mongodb.operation.count"}[$__rate_interval]))
   
   Confirm that the query returns a value greater than 0 for each target.

​

Troubleshooting

• Replication metrics are missing: MongoDB reports these metrics only on replica set members, so a standalone server doesn’t produce them. On a replica set member, confirm that the monitoring user holds the read role on the local database, which the operations log metrics require.
• Storage statistics are missing for some databases: The Collector reads these statistics for at most 100 databases on each server. Only the servers in the roles that the Configure section lists report them for your databases.
• A shard member reports 0 for cxdot.integration.target.health: The monitoring user exists only on the config servers. Create it on the shard’s replica set, as described in the prerequisites.
• An arbiter reports 0 for cxdot.integration.target.health and no other metrics: An arbiter keeps no users, so it rejects connections that authenticate. Configure the arbiter’s target without credentials, for example in a separate integration instance that sets no username.

​

Configuration reference

Configure one MongoDB integration instance with the following settings. In Helm values, place these settings under config.integrations.mongodb. In a Collector configuration file, place them under cxdot.integrations.mongodb.

​

Optional settings

• enabled Type: boolean. Optional. Default: true. Whether to run the MongoDB integration. If true, the Collector collects MongoDB metrics. If false, the Collector doesn’t run this integration.
• username Type: string. Optional. Default: empty string. MongoDB username for connections to statically configured targets. Set username and password together. The Collector authenticates when username or auth_mechanism is set. Otherwise, it connects without authenticating.
• password Type: string. Optional. MongoDB password for connections to statically configured targets. Set username and password together. The Collector masks this value in diagnostic output, logs, and errors.
• auth_source Type: string. Optional. Default: admin. Database that holds the credentials for statically configured targets.
• auth_mechanism Type: string. Optional. Default: empty string. Authentication mechanism for statically configured targets. When empty, the Collector negotiates a SCRAM mechanism with the server. Allowed values: empty string, SCRAM-SHA-1, SCRAM-SHA-256, MONGODB-X509, MONGODB-AWS, GSSAPI, PLAIN.
• scheme Type: string. Optional. Default: mongodb. Connection string scheme for statically configured targets. With mongodb+srv, each instance’s endpoint is a DNS name, without a port, whose DNS service record lists the servers to connect to, and direct_connection must be false. Allowed values: mongodb, mongodb+srv.
• replica_set Type: string. Optional. Default: empty string. Replica set name that statically configured targets must belong to. When empty, the Collector doesn’t verify the replica set name.
• direct_connection Type: boolean. Optional. Default: true. If true, connects to each target as a single server, without discovering the rest of its replica set, so each replica set member reports its own metrics. If false, the connection follows the replica set topology, and the Collector reads replication operation counts from each secondary over a connection without TLS, so a replica set that requires TLS reports the primary’s counts instead. Must be false when scheme is mongodb+srv.
• collection_interval Type: duration. Optional. Default: 15s. Time between metric collections from each statically configured MongoDB target.
• timeout Type: duration. Optional. Default: 15s. Maximum time to wait when connecting to each statically configured MongoDB target and for each metric collection from it.
• collect_index_stats Type: boolean. Optional. Default: false. Whether to collect mongodb.index.access.count, the number of index accesses for each collection, summed over the collection’s indexes. If true, at every collection interval the Collector lists the collections of every database except local and reads the index statistics of every collection, on every target. This adds load in proportion to the number of collections on the server. If false, the Collector doesn’t list collections or read index statistics. Applies to statically configured targets. Targets discovered through annotations use the setting in their annotations instead. When their annotations turn it on, the Collector reads every collection of every database except local on those targets, regardless of which databases and collections the annotations name.
• additional_metrics Type: array of string. Optional. Default: []. Optional metric groups to collect in addition to the default metrics. By default, no group is collected. The metrics.commands group counts how many times the server ran the count, createIndexes, delete, findAndModify, insert, and update commands, split by whether each run succeeded or failed, as mongodb.command.count. The tcmalloc group reports memory allocator readings, such as the bytes allocated, the heap size, and the free bytes the allocator holds, as the mongodb.tcmalloc.* metrics. The top group counts how many operations of each kind ran on each collection and the time they took, as mongodb.collection.operation.count and mongodb.collection.operation.time, and the same split by whether each operation held a read or a write lock, as mongodb.collection.access.count and mongodb.collection.access.time. It’s collected from every mongod that isn’t an arbiter, for every collection the server has run an operation on since it started. The collection group reports each collection’s storage statistics, operation latencies, and full collection scans, such as mongodb.collection.data.size, mongodb.collection.operation.latency.time, and mongodb.collection.scan.count. It’s collected from a standalone server, from the primary of a replica set that isn’t part of a sharded cluster, and from every mongos router configured as a target. Each router reports every collection in the sharded cluster, with each shard’s statistics separately, so list one router in an instance that enables the group to read them once. It’s collected every collection_stats.interval, for the databases and collections that collection_stats selects. metrics.commands and tcmalloc read the server status the Collector already reads at every collection interval, so they add no load on the server. top runs one top command at every collection interval. collection runs one listCollections command per database, unless collection_stats.collections names the collections, and one $collStats aggregation per collection, at every collection_stats.interval. Applies to statically configured targets. Targets discovered through annotations use the setting in their annotations instead.
• collection_stats Type: object. Optional. Settings for the collection group of additional_metrics: which databases and collections it reads, how many collections per database, and how often. Applies to statically configured targets. Targets discovered through annotations take the matching settings from their annotations instead.
• collection_stats.databases Type: array of string. Optional. Default: []. Databases whose collections the collection group reads. When empty, the Collector reads every database on the target, up to 100. On targets discovered through annotations, the group reads every database when the annotations turn on database autodiscovery, and otherwise only the database the annotations name, admin by default.
• collection_stats.collections Type: array of string. Optional. Default: []. Collections the collection group reads in each database. When empty, the Collector reads every collection the monitoring user is authorized to list in each database, up to max_collections_per_database. On targets discovered through annotations, the collections the annotations name apply only while database autodiscovery is off.
• collection_stats.max_collections_per_database Type: integer. Optional. Default: 100. Minimum: 1. Maximum number of collections the collection group reads in each database when collections is empty. Targets discovered through annotations use the setting in their annotations instead.
• collection_stats.interval Type: duration. Optional. Default: 5m. Time between reads of the collection group. Each read costs one $collStats aggregation per collection, so it runs less often than collection_interval by default. When it’s no longer than collection_interval, the group is read at every collection interval. A read that doesn’t finish within timeout stops there, and the next read continues from where it stopped. Targets discovered through annotations use the setting in their annotations instead.
• instances Type: array of object. Optional. Default: []. Static MongoDB targets. When this list isn’t empty, this integration instance collects from exactly these targets and stops discovering targets through autodiscovery annotations.
• instances[].endpoint Type: string. Required. Network address of the MongoDB server in host:port format, for example, mongodb.default.svc:27017. With the mongodb+srv scheme, a DNS name without a port.
• instances[].cluster_name Type: string. Optional. Name of the MongoDB cluster the target belongs to. When set, the Collector adds it as the mongodb.cluster.name resource attribute to every metric from this target. When unset, metrics from this target don’t carry the attribute. Targets discovered through annotations use the cluster name in their annotations.
• tls Type: object. Optional. Default: {"insecure":true}. TLS settings for connections to statically configured MongoDB targets. By default, the connection is unencrypted. The Collector connects with TLS when insecure is false or when ca_file or ca_pem is set, and verifies the server certificate unless insecure_skip_verify is true. The default applies only when you set no tls option: if you set any, also set insecure: true to keep the connection unencrypted. With the mongodb+srv scheme, the Collector always connects with TLS, and when insecure is true and no certificate authority is set it verifies the server certificate against the system certificate authorities.
• tls.ca_file Type: string. Optional. Path to a PEM-encoded certificate authority (CA) certificate file used to verify the MongoDB server certificate. Setting it enables TLS even when insecure is true. If omitted, the Collector uses the system certificate authority pool.
• tls.ca_pem Type: string. Optional. PEM-encoded certificate authority certificate content used to verify the MongoDB server certificate. Setting it enables TLS even when insecure is true.
• tls.cert_file Type: string. Optional. Path to the PEM-encoded client certificate file to present when the MongoDB server requires mutual TLS or MONGODB-X509 authentication.
• tls.cert_pem Type: string. Optional. PEM-encoded client certificate content to present when the MongoDB server requires mutual TLS or MONGODB-X509 authentication.
• tls.cipher_suites Type: array of string. Optional. TLS cipher suites that the Collector can use, in preference order. If omitted, the Collector uses the secure defaults from the Go TLS library. For supported names, see https://go.dev/src/crypto/tls/cipher_suites.go.
• tls.curve_preferences Type: array of string. Optional. Elliptic curves that the Collector can use for an elliptic curve Diffie-Hellman ephemeral handshake, in preference order. If omitted, the Collector uses the Go TLS library defaults.
• tls.include_system_ca_certs_pool Type: boolean. Optional. Whether to also trust the system certificate authority pool when ca_file or ca_pem is set. If true, the Collector trusts both sources. If false, it trusts only the configured certificate authorities. With neither ca_file nor ca_pem set, the Collector always uses the system pool.
• tls.insecure Type: boolean. Optional. Whether to disable transport security. If true, the Collector uses an unencrypted connection unless ca_file or ca_pem is set. If false, the Collector connects with TLS.
• tls.insecure_skip_verify Type: boolean. Optional. Whether to skip verification of the MongoDB server certificate. If true, the connection is encrypted but isn’t authenticated and is vulnerable to man-in-the-middle attacks. If false, the Collector verifies the certificate.
• tls.key_file Type: string. Optional. Path to the PEM-encoded client private key file used with cert_file for mutual TLS or MONGODB-X509 authentication.
• tls.key_pem Type: string. Optional. PEM-encoded client private key content used with cert_pem for mutual TLS or MONGODB-X509 authentication.
• tls.max_version Type: string. Optional. Maximum TLS protocol version the Collector can use, such as 1.3. If omitted, the Collector uses the maximum version supported by the Go TLS library.
• tls.min_version Type: string. Optional. Minimum TLS protocol version the Collector can use, such as 1.2. If omitted, the minimum version is TLS 1.2.
• tls.reload_interval Type: duration. Optional. How often the Collector reloads certificate and key files. If omitted, the Collector doesn’t reload the files.
• tls.server_name_override Type: string. Optional. Server name to verify in the MongoDB server certificate instead of the endpoint hostname. Use this setting when the certificate name differs from the endpoint hostname.
• tls.tpm Type: object. Optional. Trusted platform module settings for the TLS private key.
• tls.tpm.auth Type: string. Optional. Authorization value for the trusted platform module key.
• tls.tpm.enabled Type: boolean. Optional. Whether to use a trusted platform module for the TLS private key. If true, the Collector loads the key from the configured device or socket. If false, the Collector uses the configured key file or in-memory key.
• tls.tpm.owner_auth Type: string. Optional. Owner authorization value for the trusted platform module.
• tls.tpm.path Type: string. Optional. Path to the trusted platform module device or Unix domain socket, such as /dev/tpm0 or /dev/tpmrm0.