MongoDB receiver

The MongoDB receiver collects data from a MongoDB instance.

The MongoDB receiver is a component of the OpenTelemetry Collector. It connects to standalone or self-managed MongoDB clusters, including non-Atlas managed MongoDB servers, and MongoDB Atlas deployments, and supports metrics and logs pipelines.

Use the MongoDB receiver for Splunk Database Monitoring with self-managed MongoDB and MongoDB Atlas deployments. For MongoDB Atlas, configure the MongoDB receiver with scheme: mongodb+srv. The MongoDB Atlas receiver, mongodb_atlas, doesn't support the db.server.query_sample and db.server.top_query events that Splunk Database Monitoring uses.

The receiver collects metrics with the MongoDB dbStats and serverStatus commands and can collect query sample and top query events. The receiver uses the Go MongoDB driver. For more information, see the MongoDB Go driver documentation.

Note: Use the MongoDB receiver in place of the deprecated SignalFx Smart Agent mongodb monitor type.

MongoDB and MongoDB Atlas support starts from these minimum collector versions:

  • Splunk Distribution of the OpenTelemetry Collector (splunk-otel-collector) v0.158.0 or higher
  • Community (OSS) version of the OpenTelemetry Collector (opentelemetry-collector-contrib) v0.158.0 or higher

Supported versions and platforms

The MongoDB receiver supports these MongoDB versions and platforms:

  • Versions: 4.0 and higher, including 5.0, 6.0, and 7.0
  • Platforms: Standalone MongoDB clusters, including non-Atlas managed MongoDB servers

Splunk Database Monitoring supports these MongoDB versions and platforms for collection of query sample and top query events:

  • Versions: Standalone or self-managed MongoDB 7.0
  • Platforms: MongoDB Atlas dedicated clusters M10 and higher

Prerequisites

  1. Create a monitoring user for the receiver:

    Prepare MongoDB by creating a dedicated user with the clusterMonitor role to collect metrics. For information about MongoDB roles, see MongoDB built-in roles. For an example of how to configure these permissions, see lpu.sh.

    Note: If you're using automatic discovery with MongoDB for metrics-only collection, see Automatic discovery for MongoDB.
    Self-managed MongoDB

    Create a dedicated MongoDB user for the OpenTelemetry Collector in the admin database. Grant the user these roles:

    • clusterMonitor on admin
    • readAnyDatabase on admin

    Create an additional custom role that grants find and indexStats access on system.profile:

    JS 
    use admin

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

db.createRole({
  role: "otelSystemProfileIndexStats",
  privileges: [
    {
      resource: { db: "", collection: "system.profile" },
      actions: [ "find", "indexStats" ]
    }
  ],
  roles: []
})

db.grantRolesToUser("otel-user", [
  { role: "otelSystemProfileIndexStats", db: "admin" }
])
    MongoDB Atlas

    Create a database user for the OpenTelemetry Collector. To use the Atlas CLI, set the Atlas project ID and create the user:

    BASH 
    export ATLAS_PROJECT_ID='atlas-project-id'

atlas dbusers create \
  --username 'otel-user' \
  --password 'otel-user-password' \
  --role clusterMonitor@admin,readAnyDatabase@admin \
  --projectId "$ATLAS_PROJECT_ID"

    If the user already exists, update it:

    BASH 
    atlas dbusers update 'otel-user' \
  --authDB admin \
  --role clusterMonitor@admin,readAnyDatabase@admin \
  --projectId "$ATLAS_PROJECT_ID"

    Verify the user:

    BASH 
    atlas dbusers describe 'otel-user' \
  --projectId "$ATLAS_PROJECT_ID" \
  -o json

    To use MongoDB Atlas, create or update the database user in the MongoDB Atlas UI:

    1. Log in to MongoDB Atlas.
    2. Select the correct organization and project.
    3. Select Security > Database Access.
    4. Select Add New Database User for a new user, or select Edit for an existing user.
    5. Select Password authentication and enter the username and password for the OpenTelemetry Collector user.
    6. Assign clusterMonitor on admin and readAnyDatabase on admin.
    7. Save the user.

  2. Configure the database:

    Self-managed MongoDB

    To improve top_query reliability, configure profiling level 1 and a slow query threshold of 100 ms. MongoDB records operations that run longer than the slow query threshold as slow operations. The receiver can use those records for top query collection.

    If you use docker-compose, add these options to the mongod command:

    YAML 
    command:
  [
    "mongod",
    "--replSet", "rs0",
    "--bind_ip_all",
    "--port", "27017",
    "--auth",
    "--keyFile", "/etc/mongo-keyfile",
    "--profile", "1",
    "--slowms", "100"
  ]

    If you use mongod.conf, add these settings:

    YAML 
    operationProfiling:
  mode: slowOp
  slowOpThresholdMs: 100

    Restart MongoDB and validate the profiling settings:

    JS 
    db.getSiblingDB("database-name").getProfilingStatus()
    MongoDB Atlas

    Since MongoDB Atlas profiler settings don't persist (they're reset to default values after reboot), the receiver uses a fallback mechanism to get logs.

Configure the receiver

Modify your collector configuration file as follows. All examples are for the Splunk Distribution of the OpenTelemetry Collector.

  1. In the receivers: section, add mongodb:

    Self-managed MongoDB
    YAML 
    mongodb/receiver-instance-name:
  collection_interval: 10s
  hosts:
    - endpoint: host-ip:27017
  username: otel-user
  password: otel-user-password
  auth_source: admin
  direct_connection: true
  events:
    db.server.query_sample:
      enabled: true
    db.server.top_query:
      enabled: true
  tls:
    insecure: true
    insecure_skip_verify: true
    MongoDB Atlas
    YAML 
    mongodb/atlas-receiver-instance-name:
  scheme: mongodb+srv
  hosts:
    - endpoint: host-domain-name
  username: otel-user
  password: otel-user-password
  auth_source: admin
  collection_interval: 10s
  events:
    db.server.query_sample:
      enabled: true
    db.server.top_query:
      enabled: true
    Non-Database Monitoring
    YAML 
    mongodb:
  hosts:
    - endpoint: localhost:27017
  username: otel
  password: ${env:MONGODB_PASSWORD}
  initial_delay: 1s
  tls:
    insecure: true
    insecure_skip_verify: true
    Important:

    If you're using the Splunk Distribution of OpenTelemetry Collector, leave the following receiver settings at their default values:

    • query_sample_collection.max_rows_per_query (Default: 100)

    • top_query_collection.collection_interval (Default: 60s)

    • top_query_collection.max_query_sample_count (Default: 1000)

    These values support Database Monitoring without affecting the performance of the database or the collector. If you increase these values, you might adversely affect the performance of your database or collector, and this could result in ingest throttling.

  2. In the exporters: section, add an instance of the OTLP/HTTP exporter named otlp_http/dbmon. Confirm that a signalfx exporter is already present in your configuration because the metrics/dbmon pipeline uses it.

    Note: If you deployed the Splunk Distribution of the OpenTelemetry Collector, the signalfx exporter is already present in the default configuration.
    YAML 
    otlp_http/dbmon:
  headers:
    X-SF-Token: your-splunk-access-token
    X-splunk-instrumentation-library: dbmon
  logs_endpoint: https://ingest.your-splunk-realm.observability.splunkcloud.com/v3/event
  sending_queue:
    batch:
      flush_timeout: 15s
      max_size: 10485760
      sizer: bytes

  3. In the service.pipelines: section, create a metrics pipeline named metrics/dbmon and a logs pipeline named logs/dbmon. Replace mongodb/receiver-instance-name with the receiver instance name you configured, such as mongodb/node or mongodb/atlas:

    YAML 
    metrics/dbmon:
  receivers:
    - mongodb/receiver-instance-name
  processors:
    - memory_limiter
    - batch
  exporters:
    - signalfx
logs/dbmon:
  receivers:
    - mongodb/receiver-instance-name
  processors:
    - memory_limiter
    - batch
  exporters:
    - otlp_http/dbmon
    Important: Use an identical list of processors for the metrics and logs/dbmon pipelines, and include these processors in the same order.

  4. Restart the collector to apply your configuration changes.

    The restart command varies depending on what platform you deployed the collector on and what tool you used to deploy it. Here are general examples of the restart command:

    Linux

    Linux with installer script:

    BASH 
    sudo systemctl restart splunk-otel-collector
    Windows

    Windows with installer script:

    BASH 
    stop-service splunk-otel-collector
start-service splunk-otel-collector
    Kubernetes

    Kubernetes with Helm:

    BASH 
    helm upgrade your-splunk-otel-collector splunk-otel-collector-chart/splunk-otel-collector -f your-override-values.yaml

    where splunk-otel-collector-chart is the name you gave to the Helm chart in the helm repo add command.

Your database instance should now be visible on APM > Database monitoring as well as on Infrastructure > Infrastructure monitoring if you have a Database Monitoring license. For troubleshooting, see Troubleshoot data collection .

Advanced configurations

Configure MongoDB hosts

Use the hosts setting to define a list of host:port or Unix domain socket endpoints. The default is [localhost:27017]. The transport option is no longer available.

  • For standalone MongoDB deployments, specify the hostname and port of the mongod instance.

  • For replica sets, specify the hostnames and ports of the mongod instances in the replica set configuration. If you set replica_set, the receiver automatically discovers nodes.

  • For sharded MongoDB deployments, specify a list of mongos hosts.

  • For MongoDB Atlas deployments that use SRV DNS, set scheme to mongodb+srv and specify one host.

Monitor a replica set

If your MongoDB deployment is a replica set, use replica_set to specify the replica set name. This setting lets the receiver automatically discover other nodes in the replica set.

Use a direct connection

Set direct_connection to true to prevent the driver from automatically discovering other nodes and to use a direct connection to the host.

Identify database instances uniquely

Use service.instance.id, service.name, and service.namespace resource attributes to distinguish MongoDB instances when the generated identifier doesn't identify each instance uniquely in your deployment.

To identify database instances by using a combination of service.name, service.namespace, and override_value, use Splunk Distribution of the OpenTelemetry Collector (splunk-otel-collector) version 0.158.0 or higher or Community (OSS) version of the OpenTelemetry Collector (opentelemetry-collector-contrib) version 0.158.0 or higher.

If you collect metrics and logs, add the resource attributes under both metrics.resource_attributes and logs.resource_attributes. For example:

YAML 
mongodb/node:
  hosts:
    - endpoint: host-ip:27017
  username: otel-user
  password: otel-user-password
  metrics:
    resource_attributes:
      service.instance.id:
        enabled: true
        override_value: host-ip:27017
      service.name:
        enabled: true
        override_value: payments-db
      service.namespace:
        enabled: true
        override_value: prod-us-east-k8s
  logs:
    resource_attributes:
      service.instance.id:
        enabled: true
        override_value: host-ip:27017
      service.name:
        enabled: true
        override_value: payments-db
      service.namespace:
        enabled: true
        override_value: prod-us-east-k8s
Note: Set override_value only when enabled: true. When enabled without override_value, service.name defaults to unknown_service:mongodb and service.namespace defaults to an empty string.
Configure TLS

Use the tls setting to configure TLS. By default, insecure settings are rejected and certificate verification is active. For more information, see TLS configuration settings.

Enable optional metrics

Set metrics.metric-name.enabled to true. For example:

YAML 
mongodb:
  metrics:
    mongodb.health:
      enabled: true

Settings reference

Configuration options for this receiver:

included

https://raw.githubusercontent.com/splunk/collector-config-tools/main/cfg-metadata/receiver/mongodb.yaml

Metrics reference

Metrics, attributes, and resource attributes reported by this receiver:

included

https://raw.githubusercontent.com/splunk/collector-config-tools/main/metric-metadata/mongodbreceiver.yaml

mongodb.extent.count is available for versions earlier than 4.4 with the mmapv1 storage engine.

Activate or deactivate specific metrics

You can activate or deactivate specific metrics by setting the enabled field in the metrics section for each metric. For example:

YAML 
receivers:
  samplereceiver:
    metrics:
      metric-one:
        enabled: true
      metric-two:
        enabled: false

The following is an example of host metrics receiver configuration with activated metrics:

YAML 
receivers:
  hostmetrics:
    scrapers:
      process:
        metrics:
          process.cpu.utilization:
            enabled: true
Note: Deactivated metrics aren’t sent to Splunk Observability Cloud.
Billing

  • If you’re in a MTS-based subscription, all metrics count towards metrics usage.

  • If you’re in a host-based plan, metrics listed as active (Active: Yes) on this document are considered default and are included free of charge.

Learn more at Infrastructure Monitoring subscription usage (Host and metric plans).