MongoDB

Overview Copied

The MongoDB Collection Agent plugin gathers operational data from MongoDB. It supports both standalone and replica set topologies.

The plugin enables you to:

• Monitor overall server performance, including operation counters, memory usage, and cursor activity.
• Track lock acquisition patterns and detect potential contention or deadlocks.
• View storage statistics per database, including data size, index size, and object count.
• Monitor the health, state, and replication lag of replica set members.
• Detect assertion failures and other server-level warning signals.

Prerequisites Copied

Ensure your MongoDB deployment version is supported for this plugin. Refer to Database support for the list of supported versions.

Geneos environment Copied

• Gateway and Netprobe 7.1.x or higher.
• Collection Agent 5.x or higher. To run a Collection Agent, see Collection Agent setup.

Connectivity Copied

If the plugin runs on a different machine from the MongoDB server, ensure there is network connectivity between the two.

Permissions Copied

A MongoDB user account with read monitoring permissions is required. It is recommended to use the built-in clusterMonitor role, especially when connecting to a MongoDB Replica Set.

Configure Geneos to deploy the MongoDB plugin Copied

Setting up this plugin in Geneos involves these primary steps:

1. Set up your Collection Agent plugin.

2. Configure your mappings.

3. Configure your other Dynamic Entities in the Gateway. See Create Dynamic Entities in Collection Agent setup for a more detailed procedure.

Set up your Collection Agent plugin Copied

Set up your collector in the Gateway Setup Editor by adding the following configuration in Dynamic Entities > Collectors. For more information, see Collectors in Dynamic Entities.

Configuration reference Copied

collectors:
  - name: mongodb
    type: plugin
    className: MongoDbCollector

    # How often to collect metrics, in milliseconds. (optional, default: 300000)
    collectionInterval: 300000

    # Connection details
    connection:
      # The connection string in URI format. (required)
      # Refer below for the Standard and SRV connection format.
      #   mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]
      #   mongodb+srv://[username:password@]host[/[defaultauthdb][?options]]
      uri: mongodb://localhost:27017/admin

      # The alias that will be used to represent the connection string URI. (required)
      name: MyConnectionName

      # The list of Database names that will be monitored. (optional)
      # If this is not defined, then the defaultauthdb in the connection URI will be monitored.
      # If defaultauthdb is also not defined, then ALL databases will be monitored.
      databaseNames:
        - admin
        - local

      # Connect to a MongoDB instance using TLS
      # (optional, default is connecting without tls)
      tls:
        # The path to a CA PEM file that contains the CA certificate. (optional)
        # If this is not specified, the MongoDB Plugin will use the default Java truststore.
        caFile: <path to CA PEM file>

        # The path to a Client certificate. (optional)
        # The mongod/mongos does not require a certificate key file from the client to verify the client's identity.
        # If mongod/mongos is configured with Client Certificate Validation, clientCert and clientKey must be supplied.
        clientCert: <path to Client Certificate>

        # The path to a Client Key PEM File. It should be in PKCS#8 format. (optional)
        clientKey: <path to Client Key PEM file>      

Both the connection uri and name are required.

Sample URIs Copied

Replica set (explicit hosts):

uri: mongodb://user:password@mongo1:27017,mongo2:27018,mongo3:27019/myDb?replicaSet=myReplicaSet

Replica set (SRV):

uri: mongodb+srv://replicaset.srv.com/myDb?replicaSet=myReplicaSet

Standalone server (SRV):

uri: mongodb+srv://user:password@standalone.srv.com/myDb

Standalone server (direct):

uri: mongodb://user:password@localhost:27027/myDb

For more information on the connection URI format, refer to the MongoDB connection string documentation.

Configure your mappings Copied

You can configure your dynamic mappings using a built-in or custom mapping in Dynamic Entities > Mapping.

1. To use a built-in mapping, set Option to Built in, then select MongoDB V4 in the Built in > Name field.
2. To use a custom mapping, set Option to Custom.

For more information, see Mapping and mapping group in Dynamic Entities.

Connection behavior Copied

Standalone vs replica set mode Copied

The plugin automatically determines its operating mode from the connection URI:

• If the URI contains the replicaSet option (for example, ?replicaSet=myReplicaSet), the plugin runs in replica set mode. In this mode, it uses a cluster-level client for dbStats collection and connects to each host individually for serverStatus collection.
• If the URI does not contain a replicaSet option, the plugin runs in standalone mode. It collects both serverStatus and dbStats from each discovered server host.

Database discovery Copied

When databaseNames is not configured, the plugin discovers which databases to monitor using the following fallback chain:

1. It lists all available databases on the connected MongoDB instance.
2. If the database list is not yet available at startup, it uses the default authentication database specified in the connection URI.
3. If no default authentication database is specified in the URI, it uses the authSource of the connection credentials.
4. If none of the above yields a database, it defaults to admin.

The full database list is refreshed at the next collection interval.

Connecting to a MongoDB Replica Set Copied

To connect to a MongoDB Replica Set, include the replicaSet option in the URI. You can specify one or more replica set hosts.

uri: mongodb://user:password@mongo1:27017,mongo2:27018,mongo3:27019/myDb?replicaSet=myReplicaSet

The clusterMonitor role is recommended, as it provides the necessary permissions for both serverStatus and replSetGetStatus commands across all hosts.

TLS connections Copied

For TLS-enabled MongoDB servers, add the tls section to your connection configuration. The client key must be in PKCS#8 format. See Convert a client key file to PKCS#8 format for conversion instructions.

Published metrics Copied

The plugin collects metrics using three MongoDB commands: serverStatus, dbStats, and replSetGetStatus. Metrics are organized into the entity groups described below.

Dimensions Copied

All metrics are published with the following dimensions:

Not all dimensions are present on every metric. Each metric section below lists the specific dimensions it carries.

Server status metrics Copied

The following metrics are collected from the serverStatus command and are published once per monitored server host.

Server instance information Copied

Server operation counters Copied

Server memory metrics Copied

Server cursor metrics Copied

Server asserts Copied

Server concurrent transactions Copied

Server lock metrics Copied

Lock metrics are published for each combination of lock type and lock mode. If a lock type is not present in the server response, all its counters are published as zero.

Lock types Copied

• ParallelBatchWriterMode
• ReplicationStateTransition
• Global
• Database
• Collection
• Mutex
• Metadata
• oplog

Lock modes Copied

Metrics per lock type and mode combination Copied

Dimensions: connection_name, process, server, lock_type

Example metric names Copied

• server_locks_intent_shared_acquireCount
• server_locks_exclusive_timeAcquiringMicros
• server_locks_shared_deadlockCount

Database statistics metrics Copied

The following metrics are collected from the dbStats command and are published once per monitored database, per server host (standalone), or per replica set (replica set mode).

Note

The server dimension is used for standalone deployments, while the replica_set dimension is used for replica set deployments.

Replica set metrics Copied

The following metrics are collected from the replSetGetStatus command and are published once per replica set member. These are only available when the plugin is configured with a replica set URI.

Self-monitoring metrics Copied

The plugin publishes internal signal metrics to indicate the health of each collection cycle. These are published as two named signals per processor execution:

Self-monitoring metrics carry the following dimensions:

Troubleshooting Copied

Metrics are not appearing for a specific database Copied

If dbStats metrics are missing for a database, check the following:

• Verify that the database name is spelled correctly in databaseNames. Ensure that the MongoDB user has permission to list all databases so that it can be discovered automatically.
• The MongoDbConnection self-monitoring signal will be set to CRITICAL if the plugin cannot connect or run the command. Review the Collection Agent logs for the specific error message.

Metrics stopped updating Copied

If metrics stop updating, check the following:

• Collection tasks that do not complete within the configured collectionInterval are cancelled. If your MongoDB server responds slowly, consider increasing the collectionInterval.
• Check the MongoDbConnection and DataPointProcessing self-monitoring signals for CRITICAL alerts.

Missing replica set metrics Copied

If replica set metrics are not being displayed, check the following:

• Confirm that the connection URI includes the replicaSet option (for example, ?replicaSet=myReplicaSet). Without it, the plugin runs in standalone mode and does not collect replSetGetStatus metrics.
• Ensure that the MongoDB user has the clusterMonitor role, which is required to run replSetGetStatus across all replica set members.

rs_member_optimeDate and rs_member_replicationLag are not published Copied

These metrics are reported only for members that are currently UP and when a primary is reachable. If all members are in a non-primary state or the primary’s optime is unavailable, these metrics are suppressed.

TLS connection errors Copied

If you are experiencing TLS connection errors, check the following:

• Ensure that the clientKey file is in PKCS#8 format. See Convert a client key file to PKCS#8 format for conversion instructions.
• If you are using a custom CA, verify that the path in caFile is correct and readable by the Collection Agent process.
• If clientCert is provided, clientKey must also be provided, and vice versa.

Convert a client key file to PKCS#8 format Copied

The openssl genrsa command produces keys in PKCS#1 format by default. The MongoDB plugin requires the client key to be in PKCS#8 format.

To convert to PKCS#8 format, run the following:

openssl pkcs8 -topk8 -inform PEM -outform PEM -in client.key -out clientKey.pem -nocrypt

Use the resulting clientKey.pem as the value for the clientKey configuration field.