> ## Documentation Index
> Fetch the complete documentation index at: https://docs-xcor.paloaltonetworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB

> MongoDB server performance and health metrics, including operations, connections, locks, WiredTiger cache, replication, and database storage.

The MongoDB integration requires CXDOT Collector 1.12.0 or greater.

[MongoDB](https://www.mongodb.com/) 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:

| Type | Supported |
| :-: | :-: |
| Logs | No |
| Metrics | Yes |
| Traces | No |
| Events | No |

## 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:

  ```javascript theme={null}
  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](https://www.mongodb.com/docs/manual/core/security-users/#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](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/discover/kubernetes.md).

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](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/install/kubernetes/architecture.md).
   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:

   ```yaml theme={null}
   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:

   ```yaml theme={null}
   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:

   ```yaml theme={null}
   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:

   ```yaml theme={null}
   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:

   ```yaml theme={null}
   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:

   ```yaml theme={null}
   config:
     integrations:
       mongodb:
         enabled: false
   ```

### Validate

To validate the MongoDB integration, follow these steps:

1. In the
   [Live Telemetry Analyzer](https://docs-xcor.paloaltonetworks.com/investigate/analyze/telemetry-analyzer.md),
   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](https://docs-xcor.paloaltonetworks.com/investigate/querying/metrics/explorer.md),
   run the following query while clients send operations to the MongoDB servers:

   ```text theme={null}
   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](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`.


## Related topics

- [CXDOT Collector integrations](https://docs-xcor.paloaltonetworks.com/ingest/xcor/integrations/collector.md)
- [Azure metrics available in Palo Alto Networks Cortex XCOR](https://docs-xcor.paloaltonetworks.com/ingest/xcor/integrations/server/azure/azure-metrics.md)
- [CreateExternalConnection](https://docs-xcor.paloaltonetworks.com/tooling/api-info/definition/operations/CreateExternalConnection.md)
- [UpdateExternalConnection](https://docs-xcor.paloaltonetworks.com/tooling/api-info/definition/operations/UpdateExternalConnection.md)
- [ReadExternalConnection](https://docs-xcor.paloaltonetworks.com/tooling/api-info/definition/operations/ReadExternalConnection.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.