> ## Documentation Index > Fetch the complete documentation index at: https://otel.fyi/llms.txt > Use this file to discover all available pages before exploring further. # Mongodb > OpenTelemetry receiver for Mongodb # Mongodb Receiver ![Status](https://img.shields.io/badge/status-beta-yellow) **Available in:** `contrib` **Maintainers:** [@justinianvoss22](https://github.com/justinianvoss22), [@dyl10s](https://github.com/dyl10s), [@ishleenk17](https://github.com/ishleenk17) **Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/mongodbreceiver) ## Supported Telemetry ![Logs](https://img.shields.io/badge/logs-development-blue) ![Metrics](https://img.shields.io/badge/metrics-beta-green) ## Overview ## Purpose The purpose of this receiver is to allow users to monitor metrics from standalone MongoDB clusters. This includes non-Atlas managed MongoDB Servers. ## Prerequisites This receiver supports MongoDB versions: * 4.4+ * 5.0 * 6.0 * 7.0 Mongodb recommends to set up a least privilege user (LPU) with a [`clusterMonitor` role](https://www.mongodb.com/docs/v5.0/reference/built-in-roles/#mongodb-authrole-clusterMonitor) in order to collect metrics. Please refer to [lpu.sh](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/mongodbreceiver/testdata/integration/scripts/lpu.sh) for an example of how to configure these permissions. ## Configuration The following settings are optional: * `hosts` (default: \[`localhost:27017`]): list of `host:port` or unix domain socket endpoints.The `transport` option is no longer available. * For standalone MongoDB deployments this is the hostname and port of the mongod instance * For replica sets specify the hostnames and ports of the mongod instances that are in the replica set configuration. If the `replica_set` field is specified, nodes will be autodiscovered. * For a sharded MongoDB deployment, please specify a list of the `mongos` hosts. * `scheme` (default: `mongodb`): connection scheme. Use `mongodb+srv` for clusters that use SRV DNS records (e.g. MongoDB Atlas). When using `mongodb+srv`, exactly one host must be specified. * `username`: If authentication is required, the user can with `clusterMonitor` permissions can be provided here. * `password`: If authentication is required, the password can be provided here. * `auth_mechanism`: (optional) The authentication mechanism to use. Common values include `SCRAM-SHA-1`, `SCRAM-SHA-256`, `MONGODB-X509`, `GSSAPI`, `MONGODB-AWS`, etc. If not specified, MongoDB will use the default mechanism. * `auth_source`: (optional) The database name to use for authentication. If not specified, MongoDB will use the default authentication database (usually `admin`). * `auth_mechanism_properties`: (optional) A map of key-value pairs specifying additional properties for the authentication mechanism. For example, when using `GSSAPI` (Kerberos), you may need to set `SERVICE_NAME`. For `MONGODB-AWS`, you may need to set `AWS_SESSION_TOKEN` when using temporary AWS credentials. * `collection_interval`: (default = `1m`): This receiver collects metrics on an interval. This value must be a string readable by Golang's [time.ParseDuration](https://pkg.go.dev/time#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. * `initial_delay` (default = `1s`): defines how long this receiver waits before starting. * `replica_set`: If the deployment of MongoDB is a replica set then this allows users to specify the replica set name which allows for autodiscovery of other nodes in the replica set. * `timeout`: (default = `1m`) The timeout of running commands against mongo. * `tls`: TLS control. [By default, insecure settings are rejected and certificate verification is on](https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/configtls/README.md). * `direct_connection`: If true, then the driver will not try to autodiscover other nodes, and perform instead a direct connection o the host. * `query_sample_collection`: Additional configuration for query sample collection (`db.server.query_sample` event): * `max_rows_per_query`: (default = `100`) The maximum number of eligible query samples to emit per `$currentOp` query. Must be greater than `0`. ### Example Configuration ```yaml theme={null} receivers: mongodb: hosts: - endpoint: localhost:27017 username: otel password: ${env:MONGODB_PASSWORD} query_sample_collection: max_rows_per_query: 100 collection_interval: 60s initial_delay: 1s tls: insecure: true insecure_skip_verify: true ``` ### Example Configuration (MongoDB Atlas / SRV) ```yaml theme={null} receivers: mongodb: hosts: - endpoint: cluster0.example.mongodb.net scheme: mongodb+srv username: otel password: ${env:MONGODB_PASSWORD} collection_interval: 60s ``` The full list of settings exposed for this receiver are documented in [config.go](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/mongodbreceiver/config.go) with detailed sample configurations in [testdata/config.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/mongodbreceiver/testdata/config.yaml). ## Authentication The receiver supports several MongoDB [authentication mechanisms](https://www.mongodb.com/docs/drivers/go/current/fundamentals/auth/). The `auth_mechanism`, `auth_source`, and `auth_mechanism_properties` fields are passed directly to the MongoDB Go driver's [`options.Credential`](https://pkg.go.dev/go.mongodb.org/mongo-driver/v2/mongo/options#Credential) struct. ### SCRAM (Default) [SCRAM-SHA-256](https://www.mongodb.com/docs/drivers/go/current/security/authentication/scram/) is the default authentication mechanism for MongoDB 4.0+. If `auth_mechanism` is not specified and `username`/`password` are provided, the driver will negotiate the strongest SCRAM mechanism supported by the server (SCRAM-SHA-256, falling back to SCRAM-SHA-1). ```yaml theme={null} receivers: mongodb: hosts: - endpoint: localhost:27017 username: otel password: ${env:MONGODB_PASSWORD} collection_interval: 60s initial_delay: 1s tls: insecure: true ``` To explicitly specify the mechanism: ```yaml theme={null} receivers: mongodb: hosts: - endpoint: localhost:27017 username: otel password: ${env:MONGODB_PASSWORD} auth_mechanism: SCRAM-SHA-256 auth_source: admin collection_interval: 60s initial_delay: 1s tls: insecure: true ``` ### X.509 Certificate Authentication [X.509 authentication](https://pkg.go.dev/go.mongodb.org/mongo-driver/v2/mongo#example-Connect-X509) uses TLS client certificates instead of username and password. The certificate's subject DN is used as the identity. ```yaml theme={null} receivers: mongodb: hosts: - endpoint: localhost:27018 auth_mechanism: MONGODB-X509 auth_source: $external collection_interval: 60s initial_delay: 1s tls: ca_file: /path/to/ca.pem cert_file: /path/to/client-cert.pem key_file: /path/to/client-key.pem ``` The MongoDB Go driver typically uses a single combined PEM file (`tlsCertificateKeyFile`) containing both the certificate and private key. However, the receiver uses the OpenTelemetry Collector's standard [TLS configuration](https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/configtls/README.md), which requires separate `cert_file` and `key_file` entries. If you have a combined PEM file, split it into separate files: ```bash theme={null} openssl x509 -in client.pem -out client-cert.pem # Extract the private key openssl pkey -in client.pem -out client-key.pem ``` ### MONGODB-AWS (IAM Authentication) [MONGODB-AWS](https://www.mongodb.com/docs/drivers/go/current/security/authentication/aws-iam/) authenticates using AWS IAM credentials. This mechanism is available in MongoDB 4.4+ and requires server-side support (e.g., [MongoDB Atlas](https://www.mongodb.com/docs/atlas/security/aws-iam-authentication/) or [Percona Server for MongoDB](https://docs.percona.com/percona-server-for-mongodb/7.0/aws-iam.html)). It is not supported by the MongoDB Community Edition. Using explicit IAM credentials: ```yaml theme={null} receivers: mongodb: hosts: - endpoint: mongodb-host:27017 username: ${env:AWS_ACCESS_KEY_ID} password: ${env:AWS_SECRET_ACCESS_KEY} auth_mechanism: MONGODB-AWS auth_source: $external auth_mechanism_properties: AWS_SESSION_TOKEN: ${env:AWS_SESSION_TOKEN} collection_interval: 60s initial_delay: 1s tls: insecure: true ``` When running on AWS infrastructure (EC2, ECS, Lambda), the driver can automatically discover credentials from environment variables, the ECS task role endpoint, or the EC2 instance metadata endpoint. In that case, `username`, `password`, and `auth_mechanism_properties` can be omitted: ```yaml theme={null} receivers: mongodb: hosts: - endpoint: mongodb-host:27017 auth_mechanism: MONGODB-AWS auth_source: $external collection_interval: 60s initial_delay: 1s ``` ### GSSAPI (Kerberos) [GSSAPI/Kerberos](https://www.mongodb.com/docs/drivers/go/current/security/authentication/kerberos/) is available for [MongoDB Enterprise](https://www.mongodb.com/docs/manual/tutorial/control-access-to-mongodb-with-kerberos-authentication/) deployments only. It is not supported by MongoDB Community Edition. Using this mechanism requires: * The collector to be compiled with the `gssapi` build tag and cgo support (`CGO_ENABLED=1`). * On Linux, the `libkrb5` library must be installed. > **Note:** The default `otelcontribcol` binary is built without the `gssapi` build tag and with `CGO_ENABLED=0`, so GSSAPI authentication will not work out of the box. You will need to [build a custom collector](https://opentelemetry.io/docs/collector/custom-collector/) with `CGO_ENABLED=1` and the `gssapi` build tag to use this mechanism. ```yaml theme={null} receivers: mongodb: hosts: - endpoint: mongodb-host:27017 username: user@KERBEROS.REALM.COM auth_mechanism: GSSAPI auth_source: $external auth_mechanism_properties: SERVICE_NAME: mongodb collection_interval: 60s initial_delay: 1s ``` The default Kerberos service name is `mongodb`. Users can authenticate with an explicit password or by storing authentication keys in keytab files initialized with the `kinit` utility. ## Metrics The following metric are available with versions: * `mongodb.extent.count` \< 4.4 with mmapv1 storage engine Details about the metrics produced by this receiver can be found in [metadata.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/mongodbreceiver/metadata.yaml) ## Feature gate configurations See the [Collector feature gates](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md#collector-feature-gates) for an overview of feature gates in the collector. **STABLE**: `receiver.mongodb.removeDatabaseAttr` The feature gate `receiver.mongodb.removeDatabaseAttr` will remove the database name attribute from data points because it is already found on the resource. This feature gate cannot be changed and will be removed soon. ## Metrics | Metric Name | Description | Unit | Type | Attributes | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- | -------------- | ------------- | ------------------------------------ | | ❌ `mongodb.active.reads` | The number of read operations currently being processed. | \{reads} | UpDownCounter | | | ❌ `mongodb.active.writes` | The number of write operations currently being processed. | \{writes} | UpDownCounter | | | ✅ `mongodb.cache.operations` | The number of cache operations of the instance. | \{operations} | Counter | type | | ✅ `mongodb.collection.count` | The number of collections. | \{collections} | UpDownCounter | db.namespace | | ❌ `mongodb.commands.rate` | The number of commands executed per second. | \{command}/s | Gauge | | | ✅ `mongodb.connection.count` | The number of connections. | \{connections} | UpDownCounter | connection\_type, db.namespace | | ✅ `mongodb.cursor.count` | The number of open cursors maintained for clients. | \{cursors} | UpDownCounter | | | ✅ `mongodb.cursor.timeout.count` | The number of cursors that have timed out. | \{cursors} | UpDownCounter | | | ✅ `mongodb.data.size` | The size of the collection. Data compression does not affect this value. | By | UpDownCounter | db.namespace | | ✅ `mongodb.database.count` | The number of existing databases. | \{databases} | UpDownCounter | | | ❌ `mongodb.deletes.rate` | The number of deletes executed per second. | \{delete}/s | Gauge | | | ✅ `mongodb.document.operation.count` | The number of document operations executed. | \{documents} | UpDownCounter | operation, db.namespace | | ✅ `mongodb.extent.count` | The number of extents. | \{extents} | UpDownCounter | db.namespace | | ❌ `mongodb.flushes.rate` | The number of flushes executed per second. | \{flush}/s | Gauge | | | ❌ `mongodb.getmores.rate` | The number of getmores executed per second. | \{getmore}/s | Gauge | | | ✅ `mongodb.global_lock.time` | The time the global lock has been held. | ms | Counter | | | ❌ `mongodb.health` | The health status of the server. | 1 | Gauge | | | ✅ `mongodb.index.access.count` | The number of times an index has been accessed. | \{accesses} | UpDownCounter | collection, db.namespace | | ✅ `mongodb.index.count` | The number of indexes. | \{indexes} | UpDownCounter | db.namespace | | ✅ `mongodb.index.size` | Sum of the space allocated to all indexes in the database, including free index space. | By | UpDownCounter | db.namespace | | ❌ `mongodb.inserts.rate` | The number of insertions executed per second. | \{insert}/s | Gauge | | | ❌ `mongodb.lock.acquire.count` | Number of times the lock was acquired in the specified mode. | \{count} | Counter | lock\_type, lock\_mode, db.namespace | | ❌ `mongodb.lock.acquire.time` | Cumulative wait time for the lock acquisitions. | microseconds | Counter | lock\_type, lock\_mode, db.namespace | | ❌ `mongodb.lock.acquire.wait_count` | Number of times the lock acquisitions encountered waits because the locks were held in a conflicting mode. | \{count} | Counter | lock\_type, lock\_mode, db.namespace | | ❌ `mongodb.lock.deadlock.count` | Number of times the lock acquisitions encountered deadlocks. | \{count} | Counter | lock\_type, lock\_mode, db.namespace | | ✅ `mongodb.memory.usage` | The amount of memory used. | By | UpDownCounter | memory\_type, db.namespace | | ✅ `mongodb.network.io.receive` | The number of bytes received. | By | UpDownCounter | | | ✅ `mongodb.network.io.transmit` | The number of by transmitted. | By | UpDownCounter | | | ✅ `mongodb.network.request.count` | The number of requests received by the server. | \{requests} | UpDownCounter | | | ✅ `mongodb.object.count` | The number of objects. | \{objects} | UpDownCounter | db.namespace | | ✅ `mongodb.operation.count` | The number of operations executed. | \{operations} | Counter | operation | | ❌ `mongodb.operation.latency.time` | The latency of operations. | us | Gauge | operation\_latency | | ❌ `mongodb.operation.repl.count` | The number of replicated operations executed. | \{operations} | Counter | operation | | ✅ `mongodb.operation.time` | The total time spent performing operations. | ms | Counter | operation | | ❌ `mongodb.page_faults` | The number of page faults. | \{faults} | Counter | | | ❌ `mongodb.queries.rate` | The number of queries executed per second. | \{query}/s | Gauge | | | ❌ `mongodb.repl_commands_per_sec` | The number of replicated commands executed per second. | \{command}/s | Gauge | | | ❌ `mongodb.repl_deletes_per_sec` | The number of replicated deletes executed per second. | \{delete}/s | Gauge | | | ❌ `mongodb.repl_getmores_per_sec` | The number of replicated getmores executed per second. | \{getmore}/s | Gauge | | | ❌ `mongodb.repl_inserts_per_sec` | The number of replicated insertions executed per second. | \{insert}/s | Gauge | | | ❌ `mongodb.repl_queries_per_sec` | The number of replicated queries executed per second. | \{query}/s | Gauge | | | ❌ `mongodb.repl_updates_per_sec` | The number of replicated updates executed per second. | \{update}/s | Gauge | | | ✅ `mongodb.session.count` | The total number of active sessions. | \{sessions} | UpDownCounter | | | ✅ `mongodb.storage.size` | The total amount of storage allocated to this collection. | By | Counter | db.namespace | | ❌ `mongodb.updates.rate` | The number of updates executed per second. | \{update}/s | Gauge | | | ❌ `mongodb.uptime` | The amount of time that the server has been running. | ms | Counter | | | ❌ `mongodb.wtcache.bytes.read` | The number of bytes read into the WiredTiger cache. | By | Counter | | ## Attributes | Attribute Name | Description | Type | Values | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- | | `client.address` | Hostname or address of the client. | string | | | `client.port` | TCP port used by the client. | int | | | `collection` | The name of a collection. | string | | | `type` | The status of the connection. | string | `active`, `available`, `current` | | `db.collection.name` | The MongoDB collection being accessed within the database stated in db.namespace. | string | | | `db.namespace` | The name of a database. | string | | | `db.operation.name` | The name of the MongoDB command being executed (e.g. find, aggregate, insert). | string | | | `db.query.text` | The obfuscated MongoDB command statement. | string | | | `db.system.name` | The database management system (DBMS) product as identified by the client instrumentation. | string | `mongodb` | | `lock_mode` | The mode of Lock which denotes the degree of access | string | `shared`, `exclusive`, `intent_shared`, `intent_exclusive` | | `lock_type` | The Resource over which the Lock controls access | string | `parallel_batch_write_mode`, `replication_state_transition`, `global`, `database`, `collection`, `mutex`, `metadata`, `oplog` | | `type` | The type of memory used. | string | `resident`, `virtual` | | `mongodb.client.app.name` | The identifier of the client application which ran the operation, as set by the driver's `appName` connection option. | string | | | `mongodb.cursor.await_data` | Whether the tailable cursor waits for new data instead of returning immediately. | bool | | | `mongodb.cursor.id` | The identifier of the cursor. | string | | | `mongodb.cursor.no_timeout` | Whether the cursor is configured not to time out when idle. | bool | | | `mongodb.cursor.originating_command` | The obfuscated command that originally created the cursor. | string | | | `mongodb.cursor.returned_batches` | The cumulative number of batches returned by the cursor. | int | | | `mongodb.cursor.returned_documents` | The cumulative number of documents returned by the cursor. | int | | | `mongodb.cursor.tailable` | Whether the cursor is a tailable cursor. | bool | | | `mongodb.lsid.id` | The UUID portion of the logical session identifier associated with the MongoDB operation. | string | | | `mongodb.operation.comment` | The comments attached to the MongoDB command. String comments are reported as-is; array comments are expanded into multiple entries; non-string values are reported as MongoDB Extended JSON. | slice | | | `mongodb.operation.duration` | The duration of the MongoDB operation in seconds. | double | | | `mongodb.operation.id` | Identifier of the MongoDB operation. | string | | | `mongodb.operation.plan.summary` | Summary of the execution plan for the MongoDB operation. | string | | | `mongodb.operation.prepared_read_conflict.count` | The number of times the MongoDB operation had to wait for a prepared transaction with a write to commit or abort. | int | | | `mongodb.operation.state` | Simplified state of the MongoDB operation. | string | `active`, `waiting` | | `mongodb.operation.type` | The raw MongoDB operation type from `$currentOp.op` (e.g. query, insert, update, remove, getmore, command). | string | | | `mongodb.operation.wait.details` | Details about what the MongoDB operation is waiting on. | string | | | `mongodb.operation.wait.type` | The set of wait conditions the MongoDB operation is currently blocked on. Possible values: `lock` (from `waitingForLock`), `flow_control` (from `waitingForFlowControl`), and `latch` (when `waitingForLatch` is a non-empty document). An empty slice indicates the operation is not waiting on any of these conditions. | slice | | | `mongodb.operation.write_conflict.count` | The number of times the MongoDB operation conflicted with another write operation on the same document. | int | | | `mongodb.operation.yield.count` | The number of times the MongoDB operation yielded to allow other operations to complete. | int | | | `mongodb.query.framework` | The MongoDB query execution engine that processed this operation. Only present for operations that flow through the query subsystem (reads, read-modify-writes, and getMore continuations); absent for pure inserts, index management, and administrative commands. Known values include `classic` and `sbe`. | string | | | `mongodb.query.truncated` | Whether the value carried by db.query.text is a truncated rendering of the MongoDB command, as indicated by `$truncated` in the currentOp output. | bool | | | `operation` | The MongoDB operation being counted. | string | `insert`, `query`, `update`, `delete`, `getmore`, `command` | | `operation` | The MongoDB operation with regards to latency | string | `read`, `write`, `command` | | `type` | The result of a cache request. | string | `hit`, `miss` | | `user.name` | Name of the user associated with the operation. | string | | ## Resource Attributes | Attribute Name | Description | Type | Enabled | | --------------------- | ----------------------------------------------------------------------------------------------- | ------ | ------- | | `server.address` | The address of the MongoDB host. | string | ✅ | | `server.port` | The port of the MongoDB host. | int | ❌ | | `service.instance.id` | A unique identifier of the MongoDB resource as a UUID v5, derived from server address and port. | string | ✅ | ## Configuration ### Example Configuration ```yaml theme={null} mongodb: hosts: - endpoint: localhost:27017 username: otel password: ${env:MONGO_PASSWORD} auth_mechanism: SCRAM-SHA-256 auth_source: admin auth_mechanism_properties: SERVICE_NAME: mongodb query_sample_collection: max_rows_per_query: 42 collection_interval: 60s mongodb/srv: hosts: - endpoint: cluster0.example.mongodb.net scheme: mongodb+srv username: otel password: ${env:MONGO_PASSWORD} collection_interval: 60s ``` *** *Last generated: 2026-07-06*