> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/sources/mongodb.md).
# MongoDB
The MongoDB source collects metrics and logs from MongoDB. Metrics are scraped from one or more `mongod` endpoints (host:port or a unix domain socket) using the OpenTelemetry MongoDB receiver, optionally authenticating with a monitoring user and TLS. Logs are read from MongoDB log files on the collector host and parsed into structured records.
### Supported Telemetry
| Platform | Metrics | Logs | Traces |
| -------- | ------- | ---- | ------ |
| macOS | ✓ | ✓ | |
| Linux | ✓ | ✓ | |
| Windows | ✓ | ✓ | |
### Prerequisites
* **A reachable MongoDB endpoint.** The collector must reach each `mongod` host and port listed in **Hosts** (default `localhost:27017`). For replica sets, list the member hosts; for sharded deployments, list the `mongos` hosts.
* **A monitoring user (metrics).** If authentication is enabled, create a least-privilege user with the built-in `clusterMonitor` role and supply it in **Username** / **Password**. `clusterMonitor` grants the read-only monitoring access the receiver needs without write privileges. See [MongoDB Built-In Roles](https://www.mongodb.com/docs/manual/reference/built-in-roles/) for the role definition and [the mongodbreceiver README](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/mongodbreceiver/README.md) for an example least-privilege-user setup.
* **TLS material (optional).** If MongoDB requires TLS, enable TLS and provide the CA file, and for mutual TLS the client certificate and key files, on the collector host.
* **Log file read access (logs).** The collector must have read access to the MongoDB log files at the configured **Log Paths** (default `/var/log/mongodb/mongodb.log*` and `/var/log/mongodb/mongod.log*`).
### Configuration
**General**
| Parameter | Type | Required | Default | Description |
| --------------------- | ------------------ | -------- | --------------------- | ------------------------------------------------------------ |
| Choose Telemetry Type | Telemetry Selector | No | `["Logs", "Metrics"]` | Which telemetry to collect. Valid values: `Logs`, `Metrics`. |
**Logs**
| Parameter | Type | Required | Default | Description |
| --------- | ---------------------- | -------- | --------------------------------------------------------------- | -------------------------------------------------------- |
| Log Paths | Strings | No | `/var/log/mongodb/mongodb.log*`, `/var/log/mongodb/mongod.log*` | Path to MongoDB log file(s). |
| Parse To | Enum: body, attributes | No | body | Parse structured log parts to either body or attributes. |
| Start At | Enum: beginning, end | No | end | Start reading logs from `beginning` or `end`. |
| Parse | Boolean | No | true | Parses the log fields into structured data. |
These parameters apply when **Choose Telemetry Type** includes `Logs`. All are advanced settings.
**Metrics**
| Parameter | Type | Required | Default | Description |
| ------------------- | ------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------- |
| Hosts | Strings | No | `localhost:27017` | List of host:port or unix domain socket endpoints. |
| Username | String | No | *(empty)* | If authentication is required, specify a username with `clusterMonitor` permission. Advanced setting. |
| Password | String | No | *(empty)* | The user's password. Sensitive value. Advanced setting. |
| Collection Interval | Integer | No | 60 | How often (seconds) to scrape for metrics. Advanced setting. |
| Filtering | Metrics | No | *(empty)* | Disable individual MongoDB metrics from collection. Advanced setting. |
These parameters apply when **Choose Telemetry Type** includes `Metrics`.
**TLS (Metrics)**
| Parameter | Type | Required | Default | Description |
| --------------------------------- | ------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------- |
| Enable TLS | Boolean | No | false | Whether or not to use TLS. Advanced setting. |
| Skip TLS Certificate Verification | Boolean | No | false | Enable to skip TLS certificate verification. Relevant when Enable TLS is true. |
| TLS Certificate Authority File | String | No | *(empty)* | Certificate authority used to validate TLS certificates. Relevant when Enable TLS is true. |
| TLS Client Certificate File | String | No | *(empty)* | A TLS certificate used for client authentication, if mutual TLS is enabled. Relevant when Enable TLS is true. |
| TLS Client Private Key File | String | No | *(empty)* | A TLS private key used for client authentication, if mutual TLS is enabled. Relevant when Enable TLS is true. |
### Examples
#### Scrape metrics from an authenticated replica set over TLS
Collects metrics every 30 seconds from two `mongod` members, authenticating with a `clusterMonitor` user and validating the server certificate against a CA file.
```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
name: mongodb
spec:
type: mongodb
parameters:
- name: telemetry_types
value: ["Metrics"]
- name: hosts
value:
- "mongo-1.internal:27017"
- "mongo-2.internal:27017"
- name: username
value: bindplane-monitor
- name: password
value: "REPLACE_WITH_PASSWORD"
- name: collection_interval
value: 30
- name: enable_tls
value: true
- name: ca_file
value: /etc/ssl/mongodb/ca.crt
```
### Configuration Tips
* For a replica set, list the member `mongod` hosts; for a sharded cluster, list the `mongos` hosts instead of individual shards.
* Use a dedicated user with only the `clusterMonitor` role for metrics. It is read-only and avoids granting write access to the collector.
* Use **Filtering** to disable metrics you do not need, reducing cardinality and downstream cost.
### Troubleshooting
#### Metrics endpoint connection refused
Symptoms: no MongoDB metrics arrive; collector logs show connection refused or timeout to the configured host.
Solutions:
1. Confirm each entry in **Hosts** is a reachable `mongod` (or `mongos`) host:port from the collector.
2. Verify firewall and network policy allow the collector to reach the MongoDB port (default 27017).
#### Authentication failed
Symptoms: collector logs report authentication or unauthorized errors during scrape.
Solutions:
1. Confirm **Username** and **Password** are correct and the user exists in MongoDB.
2. Verify the user has the built-in `clusterMonitor` role. See [MongoDB Built-In Roles](https://www.mongodb.com/docs/manual/reference/built-in-roles/).
#### TLS handshake failure
Symptoms: scrape fails with a certificate or TLS handshake error.
Solutions:
1. Confirm **Enable TLS** matches the server's requirement and that the **TLS Certificate Authority File** can validate the server certificate.
2. For testing only, enable **Skip TLS Certificate Verification**; do not use this in production.
#### No logs collected
Symptoms: no log records appear from the source.
Solutions:
1. Confirm the MongoDB log files exist at the configured **Log Paths** and that the collector user can read them.
2. If you expect existing log content, set **Start At** to `beginning`.
### Standalone Source
```yaml
apiVersion: bindplane.observiq.com/v1
kind: Source
metadata:
name: mongodb
spec:
type: mongodb
parameters:
- name: telemetry_types
value: ["Logs", "Metrics"]
- name: hosts
value:
- "localhost:27017"
- name: username
value: bindplane-monitor
- name: password
value: "REPLACE_WITH_PASSWORD"
- name: collection_interval
value: 60
- name: enable_tls
value: false
- name: log_paths
value:
- "/var/log/mongodb/mongodb.log*"
- "/var/log/mongodb/mongod.log*"
- name: start_at
value: end
- name: parse_to
value: body
- name: parse
value: true
```
### Related Resources
* [MongoDB Built-In Roles (clusterMonitor)](https://www.mongodb.com/docs/manual/reference/built-in-roles/)
* [OpenTelemetry mongodbreceiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/mongodbreceiver/README.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.bindplane.com/integrations/sources/mongodb.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.