percona/mongodb_exporter: Prometheus Metrics for MongoDB 6.0+

MongoDB monitoring gap addressed by percona/mongodb_exporter

Prometheus needs an exporter when the application being monitored does not publish metrics in the format Prometheus expects. percona/mongodb_exporter fills that gap for MongoDB by connecting to a MongoDB deployment, issuing monitoring commands, and exposing the returned values through an HTTP metrics endpoint. The README says this implementation handles all metrics exposed by MongoDB monitoring commands, with implemented sources including $collStats, $indexStats, getDiagnosticData, replSetGetStatus, replSetGetConfig, and serverStatus.

The project is relevant to database operators, platform engineers, and teams running Percona Server for MongoDB or MongoDB Community and Enterprise Edition. Its scope is broader than a basic process-level exporter. It can report information associated with collections, indexes, replica sets, server status, and supported storage engine data. The repository also includes a Docker image, a Docker Compose test topology, command-line configuration, authentication guidance, and a release build process for Linux, macOS, and several CPU architectures.

The exporter is not a MongoDB replacement and it does not manage replication or storage. It is an adapter between MongoDB monitoring interfaces and Prometheus. Its usefulness therefore depends on the MongoDB commands being available, the permissions granted to the connecting account, and the monitoring setup accepting the resulting metric names.

How diagnostic commands become Prometheus metrics

The documented architecture is straightforward. The exporter starts with a MongoDB URI, connects to one or more targets, loops through fields exposed by diagnostic commands, and transforms the returned data into Prometheus metrics. The metric sources named in the README cover several layers of the server rather than one narrow subsystem.

For collection and index behavior, the exporter uses $collStats and $indexStats. For replication state and configuration, it uses replSetGetStatus and replSetGetConfig. serverStatus supplies broad server information, while getDiagnosticData provides another diagnostic source. The README describes the implementation as trying to obtain data from all fields exposed by those commands, so the metric set is tied to the shape and availability of MongoDB responses.

This design has a practical consequence. The exporter is more useful for detailed MongoDB observability than a hand-written script that checks only a few commands, but it also depends on MongoDB permissions and version-specific command behavior. The repository's REFERENCE.md and command-line definitions are the relevant places to inspect when the complete metric mapping matters. A monitoring team should treat the available diagnostic fields as the source of truth rather than assuming that every database object produces the same series.

Installing the exporter and running a first scrape

The README documents Docker and Podman examples using the published image. The container publishes port 9216 and receives the MongoDB URI through --mongodb.uri. The example uses the 0.53 image tag and a MongoDB endpoint on port 17001.

docker run -d -p 9216:9216 percona/mongodb_exporter:0.53 --mongodb.uri=mongodb://127.0.0.1:17001

The README also documents an equivalent Podman command and an image published at GHCR. Both registries use the same tags and the images cover linux/amd64 and linux/arm64 according to the documentation.

podman run -d -p 9216:9216 percona/mongodb_exporter:0.53 --mongodb.uri=mongodb://127.0.0.1:17001

For a local build, the documented release command uses a Dockerized GoReleaser setup, so a separate Go installation is not required by the README.

make release

The generated binaries appear under the build directory. The README identifies `build/mongodb_exporter_linux_amd64_v1/mongodb_exporter` as one example. The project also documents a direct invocation:

build/mongodb_exporter_linux_amd64_v1/mongodb_exporter --mongodb.uri=mongodb://127.0.0.1:17001

After starting the exporter, the first operational check is the exporter's HTTP endpoint on port 9216. The excerpt documents the `/scrape` endpoint for the multi-target mode, but does not provide a Prometheus scrape configuration example, so the exact Prometheus job configuration should be taken from the deployment environment rather than inferred from an undocumented flag.

MongoDB privileges and multi-target configuration

The exporter needs a MongoDB account with enough rights to query the monitoring commands it uses. The README gives `clusterMonitor` on `admin` and `read` on `local` as sufficient roles for the connecting user. It also documents additional access for the PBM collector, which needs to query Percona Backup for MongoDB internal collections in the `admin` database.

For PBM collection access, the README shows a broad `find` privilege for the `admin` database. It also shows narrower privileges for named internal collections such as `pbmBackups`, `pbmAgents`, and `pbmConfig`, while noting that the collection list may change in future releases. This is a real maintenance concern. A narrowly enumerated collection list can become incomplete after a PBM change, while the broader database-level privilege grants more access than a least-privilege design may permit.

Authentication can be included in --mongodb.uri, supplied through --mongodb.user and --mongodb.password, or supplied through MONGODB_USER and MONGODB_PASSWORD. The README warns that command-line credentials can be exposed through `ps` or `top`, so the environment variable approach avoids putting the password directly in the process arguments.

The exporter also accepts multiple MongoDB URIs separated by commas through --mongodb.uri or MONGODB_URI.

--mongodb.uri=mongodb://user:[email protected]:27017/admin,mongodb://user2:[email protected]:27018/admin

This mode centralizes the exporter process while still representing separate MongoDB targets. The documentation identifies `/scrape` for this use case.

Version boundaries and metric compatibility

The stated support boundary is MongoDB 6.0 and newer for Percona Server for MongoDB, MongoDB Community Edition, and MongoDB Enterprise Edition. The README says older versions might work, but they are no longer tested. That distinction matters because the exporter's implementation follows fields returned by monitoring commands, and those fields can differ across server versions, editions, and deployment modes.

The project also documents a --compatible-mode flag that exposes metrics with names compatible with the old 0.1x exporter. The old implementation is preserved on the release-0.1x branch. This gives operators a migration path when existing dashboards or alerts depend on historical metric names. It does not make the old implementation equivalent to the current one. The compatible flag changes naming, not the current exporter's supported MongoDB boundary.

A second practical constraint is that a broad diagnostic exporter can expose a large and changing set of fields. The README does not claim that every diagnostic field is always present, nor does it provide a stable field inventory in the excerpt. Teams should check REFERENCE.md and the deployed MongoDB responses before assuming that a particular collection, index, storage engine, or replication metric will be present on every target.

Release packaging, licensing, and upgrade work

The repository is licensed under Apache-2.0. The build output described in the README includes archives, DEB and RPM packages for Linux targets, and standalone binaries for macOS and Linux architectures. Snapshot builds include a short commit hash in filenames, which is useful when a deployment needs to identify the exact source revision behind a binary.

The repository's Makefile exposes `make release`, while the README states that the process uses the Dockerized version of GoReleaser. The Dockerfile uses a scratch final image, copies CA certificates, exposes port 9216, and sets `/mongodb_exporter` as the entrypoint. This packaging reduces the runtime filesystem, but it also means the runtime image has no shell or general-purpose operating-system tools beyond the copied certificate bundle and the exporter binary.

The recent release history includes v0.53.0 on 2026-08-20, v0.52.0 on 2026-07-30, and v0.51.0 on 2026-04-30. The repository is not archived, and the last push was on 2026-10-14. That is evidence of recent repository activity, not a guarantee that every metric name or configuration option remains unchanged. Operators should read the release notes and compare existing dashboard queries before upgrading. The Apache-2.0 license identifies the licensing basis for use and redistribution, but it does not remove the need to review dependencies, deployment policy, and security requirements.

When the legacy exporter or a simpler monitoring design is preferable

The old 0.1x implementation is the clearest alternative described by the repository. It remains available on the `release-0.1x` branch, while the current implementation covers the monitoring commands listed in the README and offers `--compatible-mode` for legacy metric names. An operator with existing dashboards built around 0.1x can either remain on that historical branch or use compatibility mode while reviewing query changes. The README does not document feature parity between the branches, so this is a migration choice rather than a claim that the old exporter has the same current coverage.

A simpler approach may be preferable when a deployment needs only a small, fixed set of server metrics and does not require collection, index, replication, or sharding detail. In that case, using a smaller exporter or direct MongoDB monitoring query can reduce metric volume and permission scope. The trade-off is reduced coverage. percona/mongodb_exporter is more appropriate when the monitoring requirement follows the breadth of MongoDB diagnostic commands and the team accepts a process that connects to MongoDB and republishes those responses as Prometheus metrics.

Editorial conclusion

Adopt percona/mongodb_exporter when MongoDB 6.0 or newer is monitored through Prometheus and the exporter can receive clusterMonitor and local read privileges. Do not choose it for older MongoDB releases that require tested support, or for a setup that cannot expose the exporter's metrics endpoint and protect MongoDB credentials. Verify the exact MongoDB edition and version, the required monitoring privileges, the selected metric sources, and the endpoint behavior before adding it to production monitoring.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. percona/mongodb_exporter on GitHub
4. README
5. Releases