DOCSEARCHbyAlgolia
Submit Docs

Percona MongoDB Exporter

repository·main·Indexed 23 days ago

https://github.com/percona/mongodb_exporter

A tool designed to export MongoDB metrics for monitoring. It supports multi-target monitoring, collection statistics (collstats), profile metrics, and sharded cluster metrics. The exporter provides topology labels (cl_role, cl_id, rs_nm, rs_state) and includes a compatibility mode for migrating from version 0.1x.y.

Tokens
13.5K
Snippets
13
Records
28
Agent score
79%

What's inside percona-mongodb_exporter

  1. Understand MongoDB topology labels in metrics

    main

    The exporter automatically attaches topology labels to all exported metrics to provide context about the MongoDB architecture:

    • cl_role: The cluster role:
      • mongos: For mongos instances.
      • shardsvr: For regular instances (primary/secondary) or arbiters.
      • (empty string): For standalone instances.
    • cl_id: The Cluster ID.
    • rs_nm: The ReplicaSet name.
    • rs_state: The ReplicaSet state (integer from getDiagnosticData() -> replSetGetStatus.myState).

  2. Use Multi-target support to monitor multiple MongoDB instances

    main

    The exporter can monitor multiple MongoDB instances using a single process by providing a comma-separated list of URIs to the --mongodb.uri flag or MONGODB_URI environment variable.

    Example configuration:

    --mongodb.uri=mongodb://user:pass@127.0.0.1:27017/admin,mongodb://user2:pass2@127.0.0.1:27018/admin

    Scraping specific targets: Use the /scrape endpoint with the target parameter to retrieve metrics for a specific instance. You can use a simplified URI (without credentials) in the parameter: GET /scrape?target=mongodb://127.0.0.1:27018

    Scraping all targets: Use the /scrapeall endpoint to query all configured targets in a single request. Each metric will include an instance label containing the host:port pair.

    Splitting clusters: Use the --split-cluster option to split all cluster nodes into separate targets. This is particularly useful when using mongodb+srv domain names, as the exporter will query SRV records on startup and allow each node to be queried individually via the /scrape endpoint.

    --mongodb.uri=mongodb://user:pass@127.0.0.1:27017/admin,mongodb://user2:pass2@127.0.0.1:27018/admin

  3. Configure MongoDB authentication for the exporter

    main

    To avoid leaking credentials in process lists (like ps or top), it is recommended to use environment variables MONGODB_USER and MONGODB_PASSWORD instead of passing them via CLI flags or the URI string.

    Using environment variables:

    MONGODB_USER=XXX MONGODB_PASSWORD=YYY mongodb_exporter_linux_amd64/mongodb_exporter --mongodb.uri=mongodb://127.0.0.1:17001

    Alternatively, using export:

    export MONGODB_USER=XXX
export MONGODB_PASSWORD=YYY
mongodb_exporter_linux_amd64/mongodb_exporter --mongodb.uri=mongodb://127.0.0.1:17001
    MONGODB_USER=XXX MONGODB_PASSWORD=YYY mongodb_exporter_linux_amd64/mongodb_exporter --mongodb.uri=mongodb://127.0.0.1:17001 --mongodb.collstats-colls=db1.c1,db2.c2

  4. Manage the MongoDB test sandbox

    main

    The project uses Docker-based containers to create a test sandbox. This allows testing against different MongoDB configurations (Standalone, Replica-set, or Sharded cluster).

    Start/Stop Sandbox

    • Start: make test-cluster
    • Stop: make test-cluster-clean

    Customizing MongoDB Version

    By default, the sandbox uses MongoDB 4.2. To use a different version or flavor, set the TEST_MONGODB_IMAGE environment variable:

    TEST_MONGODB_IMAGE=mongo:5.0 make test-cluster

    Sandbox Topology and Ports

    The sandbox exposes the following instances locally:

    • Standalone (mongod): port 27017
    • Router (mongos): port 17000
    • Replica-set 1 (3 servers + arbiter): ports 17001, 17002, 17003 (servers) and 17011 (arbiter)
    • Replica-set 2 (3 servers + arbiter): ports 17004, 17005, 17006 (servers) and 17012 (arbiter)
    • Config Server Replica-set: ports 17007, 17008, 17009

    All instances are created without authentication. You can connect via mongosh or mongo locally.

  6. Submit a Pull Request

    main

    When contributing to mongodb_exporter, follow these steps:

    1. Sign the CLA: Sign the Percona Contributor License Agreement.
    2. Follow Coding Standards: Use make format to ensure code adheres to standards (based on Effective Go).
    3. Verify Changes:
      • Add relevant tests for new functionality.
      • Run the full test suite using make test.
    4. Target Branch: All Pull Requests must be submitted against the main branch. Do not target release branches (e.g., release-X.Y); maintainers will cherry-pick fixes if necessary.

  7. Build the MongoDB exporter from source

    main

    You can build the exporter using a dockerized version of goreleaser, which removes the need to have Go installed locally. Run make release to generate binaries in the build directory. The output structure will look like this:

    ├── build
│ ├── config.yaml
│ ├── mongodb_exporter_7c73946_checksums.txt
│ ├── mongodb_exporter-7c73946.darwin-amd64.tar.gz
│ ├── mongodb_exporter-7c73946.linux-amd64.tar.gz
│ ├── mongodb_exporter_darwin_amd64
│ │ └── mongodb_exporter <--- MacOS binary
│ └── mongodb_exporter_linux_amd64
│ └── mongodb_exporter <--- Linux binary
    make release

  8. Configure required MongoDB permissions

    main

    The connecting user requires specific roles to query statistics.

    Standard roles:

    • clusterMonitor on the admin database.
    • read on the local database.

    Percona Backup for MongoDB (PBM) permissions: If using the PBM collector, the user needs privileges to query PBM internal collections in the admin database. You can grant find privileges on the entire admin collection (not recommended) or specifically for each PBM collection:

    privileges: [
    { resource: { db: "admin", collection: "pbmBackups" }, actions: [ "find" ] },
    { resource: { db: "admin", collection: "pbmAgents" }, actions: [ "find" ] },
    { resource: { db: "admin", collection: "pbmConfig" }, actions: [ "find" ] },
    ...
]

  9. Set up the development environment

    main

    To develop for mongodb_exporter, ensure you have the following software installed:

    • Golang toolchain (v1.17 or higher)
    • make utility
    • Docker
    • docker-compose utility

    Once these are installed, initialize the development environment by running make init. This installs necessary tools for linting and formatting, including gci, gofumpt, golangci-lint, and reviewdog.

    make init

  10. Run the MongoDB exporter with Docker or Podman

    main

    You can run the exporter using official container images. Use the -p 9216:9216 flag to expose the metrics endpoint.

    Podman example:

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

    Docker example:

    docker run -d -p 9216:9216 percona/mongodb_exporter:0.40 --mongodb.uri=mongodb://127.0.0.1:17001
    # with podman
podman run -d -p 9216:9216 percona/mongodb_exporter:0.40 --mongodb.uri=mongodb://127.0.0.1:17001

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

  11. Enable MongoDB collection statistics (collstats) gathering

    main

    To monitor specific databases and collections using the collstats command, use the --mongodb.collstats-colls flag with a comma-separated list of database.collection pairs.

    Example:

    --mongodb.collstats-colls=db1.c1,db2.c2
    mongodb_exporter_linux_amd64/mongodb_exporter --mongodb.uri=mongodb://127.0.0.1:17001 --mongodb.collstats-colls=db1.c1,db2.c2

  12. Enable profile metrics gathering

    main

    To collect profile metrics, use the --collector.profile flag. Note that you must also enable the profiler within MongoDB itself by setting the profiling level (e.g., db.setProfilingLevel(2)).

    Profiling Levels:

    • 0: Profiler is off (default).
    • 1: Collects operations slower than slowms or matching a filter.
    • 2: Collects all operations.