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

* 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. To collect the
  `collection` metric group, also grant the monitoring user the `read` role on each
  database whose collections it reads.

* 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. You can configure targets either by
annotating pods in your Kubernetes cluster or by listing static endpoints in your Helm
values.

The integration supports standalone servers, replica sets, and sharded clusters. Each
server is a separate target: 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. To collect from MongoDB pods in Kubernetes, add a CXDOT integration annotation to the
   pod template for every pod that runs `mongod` or `mongos`. The annotation key must end
   with the container name, and its value can reference credentials stored in a
   Kubernetes Secret in the same namespace. For example, add the following annotation to
   your MongoDB workload:

   ```yaml theme={null}
   spec:
     template:
       metadata:
         annotations:
           integrations.cxdot.paloaltonetworks.com/mongod: |
             schema_version: v1.14
             mongodb:
               instances:
                 - endpoint: ${target.host}:${target.port.mongodb}
               username: cxdot
               password: ${k8s_secret:mongodb-credentials/password}
       spec:
         containers:
           - name: mongod
             image: mongo:8.0
             ports:
               - name: mongodb
                 containerPort: 27017
   ```

   The Collector replaces `${target.host}` with the pod IP address,
   `${target.port.mongodb}` with the container port named `mongodb`, and
   `${k8s_secret:mongodb-credentials/password}` with the `password` key of the
   `mongodb-credentials` Secret. To allow the Collector to read the Secret, add the
   pod's namespace to `apiServer.metadataServer.secretAllowlist` in the Helm values for
   your CXDOT Collector.

2. Optional: To collect from MongoDB servers outside your Kubernetes cluster, configure
   static 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

   collection:
     cxdot:
       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 annotated pods 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}
   collection:
     cxdot:
       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. Provide this
   variable through `clusterCollector.extraEnv`. 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. In the Helm values, these settings apply to the targets you list there. For
   an annotated pod, set them in its CXDOT integration annotation. 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}
   collection:
     cxdot:
       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 metric groups differ in the load they add to 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 on which the server has run an operation
     since it started, the command produces a count and a time series for each operation
     type and 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.
     Enable the group on an instance that lists one router. Otherwise, the Collector reads
     the same statistics once per router and reports each collection once per router. The
     group 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. In the Helm values, this setting
   applies to the targets you list there. For an annotated pod, set it in its CXDOT
   integration annotation. For example, add the setting to the `mongodb/static` instance
   in the Helm values file for your CXDOT Collector:

   ```yaml theme={null}
   collection:
     cxdot:
       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}
   collection:
     cxdot:
       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}
   collection:
     cxdot:
       integrations:
         mongodb:
           enabled: false
   ```

Metrics from each discovered pod include that pod's Kubernetes metadata. For more
information, see
[autodiscovery](https://docs-xcor.paloaltonetworks.com/ingest/xcor/collector/discover/kubernetes.md).

### 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 servers in the roles listed in
  the Configure section report storage statistics 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 `collection.cxdot.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 the 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 the 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 the configured targets.

* **`auth_mechanism`**
  Type: `string`. Optional. Default: empty string.
  Authentication mechanism for the configured targets. When empty, the Collector negotiates a
  Salted Challenge Response Authentication Mechanism (SCRAM) 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 the 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 the 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 also connects to each replica set
  secondary it finds at startup, with the same `tls` settings and `timeout`. Replication
  operation counts come from the server the connection reads, not from each secondary. Must be
  false when `scheme` is `mongodb+srv`.

* **`collection_interval`**
  Type: `duration`. Optional. Default: `15s`.
  Time between metric collections from each configured MongoDB target.

* **`timeout`**
  Type: `duration`. Optional. Default: `15s`.
  Maximum time to wait when connecting to each configured MongoDB target and for each metric
  collection from it. Set `timeout` to no more than `collection_interval` to prevent one
  collection from overlapping the next.

* **`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 the 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 the 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 the 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: `[]`.
  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 the 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 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.