Mongodb Receiver

Available in: contrib Maintainers: @justinianvoss22, @dyl10s, @ishleenk17, @shrenikjain38 Source: opentelemetry-collector-contrib

Supported Telemetry

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 in order to collect metrics. Please refer to lpu.sh for an example of how to configure these permissions.

Permissions for explain plans (`db.server.top_query`)

The clusterMonitor role is sufficient for metrics and basic slow query collection (profiler data and getLog). However, populating mongodb.explain_plan.text and mongodb.explain_plan.hash on db.server.top_query events requires the receiver to run explain against user collections, which needs the find privilege on each monitored database. Without this permission, slow query collection still works but explain fields are empty and an Unauthorized warning is logged for each query. To enable explain plans, grant read on each database you want to monitor (recommended — least privilege):

db.createUser({
  user: "otel",
  pwd: "<password>",
  roles: [
    { role: "clusterMonitor", db: "admin" },
    { role: "read", db: "mydb" },
    { role: "read", db: "myotherdb" }
  ]
})

Alternatively, grant readAnyDatabase to cover all databases on the server:

db.createUser({
  user: "otel",
  pwd: "<password>",
  roles: [
    { role: "clusterMonitor", db: "admin" },
    { role: "readAnyDatabase", db: "admin" }
  ]
})

To disable explain plan collection entirely and avoid needing additional permissions, set max_explain_each_interval: 0 in top_query_collection.

Configuration

The following settings are optional:

hosts (default: [{endpoint: "localhost:27017"}]): list of objects with an endpoint field set to host:port or a unix domain socket path. 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. 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.
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.

Top Query Collection

The receiver can collect the top slow queries from MongoDB using system.profile (when profiling is enabled) or the diagnostic log ring buffer (getLog) as a fallback. To enable it:

receivers:
  mongodb:
    hosts:
      - endpoint: localhost:27017
    events:
      db.server.top_query:
        enabled: true

By default, top query collection is disabled. See the Permissions for explain plans section for the roles required when explain plan collection is enabled. The following options are available under top_query_collection:

collection_interval: (default = 60s) How often to scrape slow query data. Independent of the receiver’s collection_interval.
top_query_count: (default = 500) The maximum number of slow query events to emit per scrape. The slowest N executions are selected.
max_query_sample_count: (default = 1000) The maximum number of slow query entries to read from system.profile or getLog per scrape before ranking.
max_explain_each_interval: (default = 250) The maximum number of server-side explain calls to issue per scrape interval. Set to 0 to disable explain plan collection entirely.
query_plan_cache_size: (default = 500) The number of query shapes whose explain plans are cached. Set to 0 to disable caching.
query_plan_cache_ttl: (default = 10m) How long a cached explain plan is considered valid.

Example Configuration

receivers:
  mongodb:
    hosts:
      - endpoint: localhost:27017
    username: otel
    password: ${env:MONGODB_PASSWORD}
    collection_interval: 60s
    initial_delay: 1s
    tls:
      insecure: true
      insecure_skip_verify: true
    events:
      db.server.top_query:
        enabled: true
    query_sample_collection:
      max_rows_per_query: 100
    top_query_collection:
      collection_interval: 60s
      top_query_count: 500
      max_explain_each_interval: 250
    resource_attributes:
      service.name:
        enabled: true
        override_value: "my-mongodb-service"  # defaults to unknown_service:mongodb
      service.namespace:
        enabled: true
        override_value: "production"           # defaults to empty string

Example Configuration (MongoDB Atlas / SRV)

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 with detailed sample configurations in testdata/config.yaml.

Authentication

The receiver supports several MongoDB authentication mechanisms. The auth_mechanism, auth_source, and auth_mechanism_properties fields are passed directly to the MongoDB Go driver’s options.Credential struct.

SCRAM (Default)

SCRAM-SHA-256 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).

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:

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 uses TLS client certificates instead of username and password. The certificate’s subject DN is used as the identity.

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, which requires separate cert_file and key_file entries. If you have a combined PEM file, split it into separate files:

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 authenticates using AWS IAM credentials. This mechanism is available in MongoDB 4.4+ and requires server-side support (e.g., MongoDB Atlas or Percona Server for MongoDB). It is not supported by the MongoDB Community Edition. Using explicit IAM credentials:

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:

receivers:
  mongodb:
    hosts:
      - endpoint: mongodb-host:27017
    auth_mechanism: MONGODB-AWS
    auth_source: $external
    collection_interval: 60s
    initial_delay: 1s

GSSAPI (Kerberos)

GSSAPI/Kerberos is available for MongoDB Enterprise 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 with CGO_ENABLED=1 and the gssapi build tag to use this mechanism.

receivers:
  mongodb:
    hosts:
      - endpoint: mongodb-host:27017
    username: [email protected]
    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

Feature gate configurations

See the 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.	us	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.explain_plan.hash`	FNV-64a hash of the obfuscated explain plan structure, identifying the execution plan shape.	string
`mongodb.explain_plan.text`	The obfuscated query explain plan, if collection is enabled.	string
`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.cpu.time`	CPU time in seconds for this query execution.	double
`mongodb.operation.docs_examined`	Number of documents examined by this query execution.	int
`mongodb.operation.docs_returned`	Number of documents returned by this query execution.	int
`mongodb.operation.duration`	The duration of the MongoDB operation in seconds.	double
`mongodb.operation.id`	Identifier of the MongoDB operation.	string
`mongodb.operation.keys_examined`	Number of index keys examined by this query execution.	int
`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.response_length`	Response length in bytes for this query execution.	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	✅
`service.name`	Logical name of the service. When enabled, defaults to unknown_service:mongodb.	string	❌
`service.namespace`	Logical namespace for the service (for example team or environment). When enabled, defaults to an empty string until set via configuration.	string	❌

Configuration

Example Configuration

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-08-24

​Mongodb Receiver

​Supported Telemetry

​Overview

​Purpose

​Prerequisites

​Permissions for explain plans (db.server.top_query)

​Configuration

​Top Query Collection

​Example Configuration

​Example Configuration (MongoDB Atlas / SRV)

​Authentication

​SCRAM (Default)

​X.509 Certificate Authentication

​MONGODB-AWS (IAM Authentication)

​GSSAPI (Kerberos)

​Metrics

​Feature gate configurations

​Metrics

​Attributes

​Resource Attributes

​Configuration

​Example Configuration

Mongodb Receiver

Supported Telemetry

Overview

Purpose

Prerequisites

Permissions for explain plans (`db.server.top_query`)

Configuration

Top Query Collection

Example Configuration

Example Configuration (MongoDB Atlas / SRV)

Authentication

SCRAM (Default)

X.509 Certificate Authentication

MONGODB-AWS (IAM Authentication)

GSSAPI (Kerberos)

Metrics

Feature gate configurations

Metrics

Attributes

Resource Attributes

Configuration

Example Configuration