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 built-in metrics such as server performance, replica set health, and connection pool statistics.
• Define custom metrics from MongoDB command responses in addition to the built-in metrics.
• Track lock acquisition, contention, and deadlocks.
• Detect assertion failures and other server-level warning signals.
• Monitor active user sessions per MongoDB user.
• Use Kerberos (GSSAPI) authentication where password-based authentication is not permitted.

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.9.x or higher.
• Collection Agent 6.5.x or higher. To run a Collection Agent, see Set up the Collection Agent.

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>

      # Kerberos (GSSAPI) authentication (optional).
      # Only applicable when the URI includes authMechanism=GSSAPI and authSource=$external.
      # Omit this block entirely to use the system default credential cache (KRB5CCNAME / OS default).
      kerberos:
        # Path to a keytab file for the principal. (optional, mutually exclusive with ccachePath)
        # When set, the plugin performs a programmatic JAAS login using the keytab so that
        # authentication works without a prior kinit. The principal is read from the URI.
        keytabPath: /path/to/mongouser.keytab

        # Path to a Kerberos credential cache file. (optional, mutually exclusive with keytabPath)
        # When set, the plugin reads the TGT from this specific cache file.
        # When omitted, the cache is resolved via KRB5CCNAME or the OS default location.
        ccachePath: /path/to/krb5cc_file

    # Custom metrics extracted from MongoDB command responses (optional).
    # Each group maps to a specific command: serverStatus, dbStats, connPoolStats,
    # or replicaSetMember (from replSetGetStatus).
    customMetrics:
      serverStatus:
        - datapointName: server_network_bytesIn
          type: counter
          path: network.bytesIn

      dbStats:
        - datapointName: db_total_size
          type: gauge
          unit: bytes
          path: totalSize
  
      connPoolStats:
        - datapointName: connpool_acquisition_wait_total_count
          type: counter
          path: acquisitionWaitTimes.totalCount
  
      replicaSetMember:
        - datapointName: rs_member_uptime
          type: gauge
          unit: seconds
          path: uptime

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.

Kerberos (GSSAPI) authentication Copied

MongoDB Enterprise supports Kerberos (GSSAPI) authentication. To use Kerberos authentication, set authMechanism=GSSAPI and authSource=$external in the connection URI, and URL-encode the principal name (@ becomes %40).

Example:

uri: mongodb://mongouser%40MONGODB.LOCAL@mongodb.example.local:27017/?authSource=$external&authMechanism=GSSAPI

For more information, refer to the MongoDB Kerberos (GSSAPI) authentication guide.

The optional kerberos block in the connection configuration is only needed when you want to supply Kerberos credentials explicitly (for example, from a keytab or credential cache file).

If the Collection Agent JVM already has a valid Kerberos ticket cache obtained through kinit, omit the kerberos block.

Authentication modes Copied

No external Java Authentication and Authorization Service (JAAS) configuration file is required for any authentication mode. The plugin always performs a programmatic JAAS login by using Krb5LoginModule and attaches the resulting Subject to the MongoDB credential. Authentication is self-contained regardless of JAAS defaults on the JVM.

Credential cache location resolution order Copied

When ccachePath is not configured, Krb5LoginModule resolves the credential cache in the following order:

1. KRB5CCNAME environment variable (for example, KRB5CCNAME=/tmp/krb5cc_1000).
2. OS default location (for example, /tmp/krb5cc_<uid> on Linux or the API cache on macOS).

Kerberos configuration file lookup Copied

The JDK Kerberos stack locates krb5.conf file in the following order:

1. -Djava.security.krb5.conf=<path> set on the Collection Agent JVM (recommended for non-default locations)
2. JDK fallback: <java.home>/conf/security/krb5.conf
3. OS default location:

• Linux and macOS — /etc/krb5.conf
• Windows — %WINDIR%\krb5.ini

Note

The Kerberos configuration file is JVM-global. All GSSAPI-authenticated MongoDB collectors running under the same Netprobe must share the same krb5.conf configuration.

Custom metrics Copied

The customMetrics block enables you to extract additional datapoints from MongoDB command responses beyond the built-in set. Each entry under a group is appended to the metrics collected by that command.

Supported groups Copied

Entry fields Copied

Each entry in a group requires the following fields:

Behavior Copied

• If a datapointName matches a built-in metric, the custom entry overrides the built-in metric and a warning is logged.
• If the path does not resolve in the command response during collection, an error is logged. Verify the path against the raw command output.
• Duplicate datapointName values across all groups are rejected at startup with a validation error.

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 four MongoDB commands: serverStatus, dbStats, connPoolStats, and replSetGetStatus. It also runs an aggregation pipeline on the config.system.sessions collection.

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 metrics Copied

Server operation counters metrics Copied

Server memory metrics Copied

Server cursor metrics Copied

Server asserts metrics Copied

Server concurrent transactions metrics Copied

Server connections metrics Copied

Server global lock queue metrics Copied

Server network metrics Copied

Server transactions metrics Copied

Server security metrics 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.

Connection pool statistics metrics Copied

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

User session metrics Copied

The following metrics are collected by aggregating the config.system.sessions collection and are published once per MongoDB user. These metrics are available in both standalone and replica set deployments.

The user dimension identifies the MongoDB username associated with the sessions.

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

Kerberos authentication failure Copied

If Kerberos authentication fails, check the following:

• Verify that the connection URI includes authMechanism=GSSAPI and authSource=$external, and that the principal name is URL-encoded (@ becomes %40).
• When you use a keytab file, verify that keytabPath points to a valid file that the Collection Agent can read, and that the principal in the keytab matches the principal in the URI.
• Verify that a krb5.conf file is available to the Collection Agent JVM. For the lookup order, see Kerberos configuration file lookup.
• Verify that the KDC is accessible from the host that runs the Collection Agent, and that the system clocks are synchronized within the allowed Kerberos clock skew (typically 5 minutes).

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.