mongodbreceiver

README

MongoDB Receiver

This receiver fetches stats from a MongoDB instance using the golang mongo driver. Stats are collected via MongoDB's dbStats and serverStatus commands.

Status
Stability	beta: metrics
Distributions	contrib
Issues
Code coverage
Code Owners	@justinianvoss22, @dyl10s, @ishleenk17 | Seeking more code owners!

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.0+
• 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.

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. 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.

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

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:

# Extract the certificate
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: 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

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.

Documentation

Index

• func NewFactory() receiver.Factory
• type Config
  • func (c *Config) ClientOptions(secondary bool) *options.ClientOptions
  • func (c *Config) Validate() error

Functions

func NewFactory

func NewFactory() receiver.Factory

NewFactory creates a factory for mongodb receiver.

Types

type Config

type Config struct {
	scraperhelper.ControllerConfig `mapstructure:",squash"`
	configtls.ClientConfig         `mapstructure:"tls,omitempty"`
	// MetricsBuilderConfig defines which metrics/attributes to enable for the scraper
	metadata.MetricsBuilderConfig `mapstructure:",squash"`
	// Deprecated - Transport option will be removed in v0.102.0
	Hosts                   []confignet.TCPAddrConfig `mapstructure:"hosts"`
	Scheme                  string                    `mapstructure:"scheme"`
	Username                string                    `mapstructure:"username"`
	Password                configopaque.String       `mapstructure:"password"`
	AuthMechanism           string                    `mapstructure:"auth_mechanism,omitempty"`
	AuthSource              string                    `mapstructure:"auth_source,omitempty"`
	AuthMechanismProperties map[string]string         `mapstructure:"auth_mechanism_properties,omitempty"`
	ReplicaSet              string                    `mapstructure:"replica_set,omitempty"`
	Timeout                 time.Duration             `mapstructure:"timeout"`
	DirectConnection        bool                      `mapstructure:"direct_connection"`
}

func (*Config) ClientOptions

func (c *Config) ClientOptions(secondary bool) *options.ClientOptions

func (*Config) Validate

func (c *Config) Validate() error