tracer-cloud--opensre/docs/mongodb-atlas.mdx

---
title: "MongoDB Atlas"
description: "Connect MongoDB Atlas to give OpenSRE visibility into cluster health, performance metrics, deployment status, and operational insights during investigations"
---

Databases in the cloud can be harder to troubleshoot. That's where OpenSRE comes in. Connect to your MongoDB Atlas cluster to get instant visibility into cluster health, performance metrics, slow queries, and replica set status when alerts fire.

## What you'll need

- MongoDB Atlas API Public Key
- MongoDB Atlas API Private Key
- Atlas Project ID
- Permissions to view cluster metrics and configuration

## Getting connected

### Quick setup: Interactive mode 

Let's walk through it step by step:

```bash
opensre integrations setup
```
Choose **MongoDB Atlas** and enter your Atlas API credentials when prompted.

### DIY mode: Environment variables

Prefer manual config? Add these to your `.env`:

```bash
MONGODB_ATLAS_PUBLIC_KEY=your_public_key
MONGODB_ATLAS_PRIVATE_KEY=your_private_key
MONGODB_ATLAS_PROJECT_ID=your_project_id
MONGODB_ATLAS_BASE_URL=https://cloud.mongodb.com/api/atlas/v2
```

| Variable | Default | Description |
| --- | --- | --- |
| `MONGODB_ATLAS_PUBLIC_KEY` | — | **Required.** Atlas API public key |
| `MONGODB_ATLAS_PRIVATE_KEY` | — | **Required.** Atlas API private key |
| `MONGODB_ATLAS_PROJECT_ID` | — | **Required.** Atlas project identifier |
| `MONGODB_ATLAS_BASE_URL` | `https://cloud.mongodb.com/api/atlas/v2` | Atlas Admin API base URL |


### Option 3: Persistent store

```json
{
  "version": 1,
  "integrations": [
    {
      "id": "mongodb-atlas-prod",
      "service": "mongodb_atlas",
      "status": "active",
      "credentials": {
        "public_key": "your_public_key",
        "private_key": "your_private_key",
        "project_id": "your_project_id"
      }
    }
  ]
}
```

## Finding your Atlas API credentials

1. Log in to MongoDB Atlas
2. Navigate to Access Manager → API Keys
3. Create a Project API Key
4. Copy the Public Key
5. Copy the Private Key
6. Locate your Project ID from the Atlas project settings

<Info>
This integration uses the **Atlas Admin API**, not a MongoDB connection string. Create a Project API key with read access to cluster metrics and alerts.
</Info>

## Investigation tools

When OpenSRE investigates a MongoDB Atlas-related alert, these tools query the Atlas Admin API:

### Clusters

Lists all clusters in the project — state, MongoDB version, instance size, and replication topology.

### Metrics

Retrieves performance metrics for a cluster (CPU, disk I/O, connections, opcounters).

### Alerts

Fetches open Atlas alerts including event type, affected cluster, and current metric values.

### Events

Returns recent project events such as cluster scaling, backup completions, and maintenance windows.

### Performance advisor

Surfaces Atlas Performance Advisor recommendations for slow queries and missing indexes.

## Verify it works

Let's make sure everything's connected:

```bash
opensre integrations verify mongodb_atlas
```

Expected output:

```
Service: mongodb_atlas
Status: passed
Detail: Connected to MongoDB Atlas project ...
```

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| **401 Unauthorized** | Regenerate the API key pair. Confirm the public and private keys are copied correctly. |
| **403 Forbidden** | Grant the API key **Project Read Only** (or higher) permissions for the target project. |
| **Invalid project ID** | Copy the Project ID from Atlas project settings — not the cluster name or connection string. |
| **Verify passes but tools fail** | Confirm `MONGODB_ATLAS_PROJECT_ID` matches the project that owns the clusters under investigation. |

## Security best practices

- Create a **dedicated Atlas API key** for OpenSRE with the minimum project role required.
- Rotate API keys periodically and revoke unused keys.
- Never commit API keys to source control — use `.env` or the integration store.