> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  other tabs: devtest, stagingprod, cli, go-sdk, terraform
-->

# Guidance for Atlas Monitoring and Alerts

MongoDB Atlas has a robust set of built-in metrics, telemetry, and logs that you can leverage from Atlas or integrate into your third-party observability and alerting stack. This enables you to monitor and manage your Atlas deployments and respond to incidents proactively and in real time.

Monitoring your deployment allows you to:

- Understand the health and status of your cluster

- Learn how operations running on the cluster are impacting the database

- Learn if your hardware is resource constrained

- Perform workload and query optimization

- Detect and react to real-time issues to improve your application stack

Atlas provides several metrics for monitoring and alerting. You can track the health, availability, consumption, and performance of your deployments in visual dashboards and by API (Application Programming Interface). You can also view various cluster metrics, monitor your database performance, configure alerts and alert notification, and download activity logs.

## Features for Atlas Monitoring and Alerts

| Metrics | Deployment metrics provide insight into hardware performance and database operation efficiency. Atlas collects metrics for your servers, databases, and MongoDB processes and stores metrics data at [various granularity levels](https://www.mongodb.com/docs/atlas/monitor-cluster-metrics/#premium-monitoring-granularity). For each granularity level, Atlas computes metrics as averages of the reported metrics at the next finer granularity level. Many metrics have a burst reporting equivalent. You can monitor metrics in the Atlas UI using the Metrics view, Real-Time Performance Panel, Query Profiler, Performance Advisor and Namespace Insights page. You can also use the Atlas CLI or Atlas Administration API to funnel metrics into a tool of your choice. |
| --- | --- |
| Alerts | Atlas provides alerts for over 200 event types, allowing you to tailor alerts for precise monitoring. Atlas issues alerts for the database and server conditions that you configure in your alert settings. When a condition triggers an alert, Atlas displays a warning symbol on the cluster and sends alert notifications. You can use the Atlas UI, Atlas Administration API, Atlas CLI, and integrated Terraform resource to configure alerts and alert notification. |
| Monitoring | Atlas monitoring visualizations provide insights into various key metrics, including hardware performance and database operation efficiency. Tools such as real-time performance panels for network and operation visibility, query profilers for tracking efficiency trends, and automated index suggestions allow you to monitor and troubleshoot issues more effectively, driving greater operational efficiency. For example, these charts can help you understand the impact of server restarts and elections on database performance. |
| Logs | Atlas provides logs for each process in the cluster. Each process keeps an account of its activity in its own log file. You can download logs by using the Atlas UI, Atlas CLI, and Atlas Administration API. To learn more, see [Guidance for Atlas Auditing and Logging.](https://www.mongodb.com/docs/atlas/architecture/current/auditing-logging.md#std-label-arch-center-auditing-logging) |

## Recommendations for Atlas Monitoring and Alerts

### Single-Region Deployment Recommendations

#### Recommendations that apply only to deployments in a single region

Single-region deployments have no unique considerations for integrations with third-party alerting tools, such as [Datadog](https://www.mongodb.com/docs/atlas/tutorial/datadog-integration.md#std-label-datadog-integration) and [Prometheus](https://www.mongodb.com/docs/atlas/tutorial/prometheus-integration.md#std-label-prometheus-integration). See [All Deployment Paradigm Recommendations.](https://www.mongodb.com/docs/atlas/architecture/current/monitoring-alerts.md#std-label-arch-center-monitoring-alerts-recs-for-any-deployment)

### Multi-Region and Multi-Cloud Deployment Recommendations

#### Recommendations that apply only to deployments across multiple regions or multiple cloud providers

In multi-region clusters, consider potential data transfer costs associated with sending logs and metrics across regions. We recommend that you configure your logging and auditing system to minimize inter-region data transfers, possibly by keeping logs local to the region where they are generated.

### All Deployment Paradigm Recommendations

The following recommendations apply to all [deployment paradigms.](https://www.mongodb.com/docs/atlas/architecture/current/deployment-paradigms.md#std-label-arch-center-paradigms)

#### Monitor by Using Metrics

To monitor your cluster or database performance, you can view the cluster metrics such as historical throughput, performance, and utilization metrics. The following table lists some (but not all) important categories of metrics to monitor:

| Atlas Cluster Operations and Connection Metrics | Opcounters; Operation Execution Times; Query Executors and Query Targeting; Connections; Queues; Scan and Order |
| --- | --- |
| Hardware Metrics | Normalized System CPU; Normalized Process CPU; Disk Latency; Disk IOPS; Disk Space Free; System Memory; Swap Usage |
| Replication Metrics | Replication Lag; Replication Oplog Window; Replication Headroom; Oplog GB/Hour; Opcounters -repl |

You can use the Atlas UI, Atlas Administration API, and Atlas CLI to view Atlas cluster metrics. Additionally, Atlas provides built-in integrations with third-party tools such as [Datadog](https://www.mongodb.com/docs/atlas/tutorial/datadog-integration.md#std-label-datadog-integration) and [Prometheus](https://www.mongodb.com/docs/atlas/tutorial/prometheus-integration.md#std-label-prometheus-integration), and you can also leverage the Atlas Administration API to integrate with other custom metrics tools.

To learn more, see [Review Cluster Metrics.](https://www.mongodb.com/docs/atlas/monitor-cluster-metrics.md#std-label-monitor-cluster-metrics)

#### Monitor by Configuring Alerts

Atlas extends into your existing observability stack so that you can get alerts and make data-driven decisions without replacing your current tools or changing your workflows. Atlas can send alert notifications with third-party tools like [Microsoft Teams](https://www.mongodb.com/docs/atlas/tutorial/integrate-msft-teams/), [PagerDuty](https://www.mongodb.com/docs/atlas/tutorial/pagerduty-integration.md#std-label-pagerduty-integration), [DataDog](https://www.mongodb.com/docs/atlas/tutorial/datadog-integration.md#std-label-datadog-integration), [Opsgenie](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-integrations-create-OPS_GENIE/), [Splunk On-Call](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-integrations-create-VICTOR_OPS/), and [other tools](https://www.mongodb.com/docs/atlas/tutorial/third-party-service-integrations/) to give you visibility into both database and full-stack performance in the same place.

Configure alerts and notifications for security events, such as failed login attempts, unusual access patterns, and data breaches. In dev and test environments, we recommend configuring alerts for clusters that have been inactive for seven or more days to help you identify which clusters can be shut down to save costs.

When you [view alerts in the Atlas UI](https://www.mongodb.com/docs/atlas/alert-resolutions/#view-alerts), we recommend that you use available filters to limit results by host, replica set, cluster, shard, and more to help focus on the most critical alerts.

##### Recommended Atlas Alert Configurations

At the minimum, we recommend configuring the following alerts. These alerts recommendations provide a baseline, but you should adjust them based on your workload characteristics. Where "high priority" conditions are specified in the following table, we recommend that you configure multiple alerts for the same condition, one for a low priority level of severity, and one for a high priority level of severity. This allows you to configure alert notification settings for each separately.

Atlas configures some alerts by default. To learn about the default alert settings, see [Default Alert Settings.](https://www.mongodb.com/docs/atlas/configure-alerts.md#std-label-default-alert-settings)

| Condition | Recommended Alert Threshold: Low Priority | Recommended Alert Threshold: High Priority | Key Insights |
| --- | --- | --- | --- |
| Oplog Window | < 24h for 5 minutes | < 1h for 10 minutes | Monitor the replication oplog window, together with replication headroom, to determine whether the secondary may soon require a full resync. The replication oplog window often helps to determine in advance the resilience of secondaries to planned and unplanned outages. |
| [Election](https://www.mongodb.com/docs/manual/core/replica-set-elections/) events | > 3 for an hour, notify after 5 minutes | > 30 for an hour, notify after 5 minutes | Monitor election events, which occur when a primary node steps down and a secondary node is elected as the new primary. Frequent election events can disrupt operations and impact availability, causing temporary write unavailability and possible rollback of data. Keeping election events to a minimum ensures consistent write operations and stable cluster performance. |
| Read [IOPS](https://www.mongodb.com/docs/atlas/reference/alert-resolutions/disk-io-utilization/) | > 4000 for 2 minutes | > 9000 for 5 minutes | Monitor whether disk IOPS approaches the maximum provisioned IOPS. Determine whether the cluster can handle future workloads. |
| Write [IOPS](https://www.mongodb.com/docs/atlas/reference/alert-resolutions/disk-io-utilization/) | > 4000 for 2 minutes | > 9000 for 5 minutes | Monitor whether disk IOPS approaches the maximum provisioned IOPS. Determine whether the cluster can handle future workloads. |
| Read Latency | > 20ms for 5 minutes | > 50 s for 5 minutes | Monitor disk latency to track the efficiency of reading from and writing to disk. |
| Write Latency | > 20ms for 5 minutes | > 50ms for more than 5 minutes | Monitor disk latency to track the efficiency of reading from and writing to disk. |
| Swap use | > 2GB for 15 minutes | > 2GB for 15 minutes | Monitor memory to determine whether to upgrade to a higher cluster tier. This metric represents the average value over the time period specified by the metric granularity. |
| Host down | 15 minutes | 24 hours | Monitor your hosts to detect downtime promptly. A host down for more than 15 minutes can impact availability, while downtime exceeding 24 hours is critical, risking data accessibility and application performance. |
| No primary | 5 minutes | 5 minutes | Monitor the status of your replica sets to identify instances where there is no primary node. A lack of a primary for more than 5 minutes can halt write operations and impact application functionality. |
| Missing active `mongos` | 15 minutes | 15 minutes | Monitor the status of active `mongos` processes to ensure effective query routing in sharded clusters. A missing `mongos` can disrupt query routing. |
| Page faults | > 50/second for 5 minutes | > 100/second for 5 minutes | Monitor page faults to determine whether to increase your memory. This metric displays the average rate of page faults on this process per second over the selected sample period. In non-Windows environments this applies to hard page faults only. |
| Replication lag | > 240 second for 5 minutes | > 1 hour for 5 minutes | Monitor replication lag to determine whether the secondary might fall off the oplog. |
| Failed backup | Any occurrence | None | Track backup operations to ensure data integrity. A failed backup can compromise data availability. |
| Restored backup | Any occurrence | None | Verify restored backups to ensure data integrity and system functionality. |
| Fallback snapshot failed | Any occurrence | None | Monitor fallback snapshot operations to ensure data redundancy and recovery capability. |
| Backup schedule behind | > 12 hours | > 12 hours | Check backup schedules to ensure they are on track. Falling behind can risk data loss and compromise recovery plans. |
| Queued Reads | > 0-10 | > 10+ | Monitor queued reads to ensure efficient data retrieval. High levels of queued reads may indicate resource constraints or performance bottlenecks, requiring optimization to maintain system responsiveness. |
| Queued Writes | > 0-10 | > 10+ | Monitor queued writes to maintain efficient data processing. High levels of queued writes may signal resource constraints or performance bottlenecks, requiring optimization to maintain system responsiveness. |
| Restarts last hour | > 2 | > 2 | Track the number of restarts in the last hour to detect instability or configuration issues. Frequent restarts can indicate underlying problems that require immediate investigation to maintain system reliability and uptime. |
| [Primary election](https://www.mongodb.com/docs/manual/core/replica-set-elections/) | Any occurrence | None | Monitor primary elections to ensure stable cluster operations. Frequent elections can indicate network issues or resource constraints, potentially impacting the availability and performance of the database. |
| Maintenance no longer needed | Any occurrence | None | Review unnecessary maintenance tasks to optimize resources and minimize disruptions. |
| Maintenance started | Any occurrence | None | Track the start of maintenance tasks to ensure planned activities proceed smoothly. Proper oversight helps maintain system performance and minimize downtime during maintenance. |
| Maintenance scheduled | Any occurrence | None | Monitor scheduled maintenance to prepare for potential system impacts. |
| [Steal](https://www.mongodb.com/docs/atlas/alert-basics/#cpu-steal) | > 5% for 5 minutes | > 20% for 5 minutes | Monitor CPU steal on AWS EC2 clusters with Burstable Performance to identify when CPU usage exceeds the guaranteed baseline due to shared cores. High steal percentages indicate the CPU credit balance is depleted, affecting performance. |
| CPU | > 75% for 5 minutes | > 75% for 5 minutes | Monitor CPU usage to determine whether data is retrieved from disk instead of memory. |
| Disk partition usage | > 90% | > 95% for 5 minutes | Monitor disk partition usage to ensure sufficient storage availability. High usage levels can lead to performance degradation and potential system outages. |

To learn more, see [Configure and Resolve Alerts.](https://www.mongodb.com/docs/atlas/alerts/)

**Note: Auto-Scaling Alert Events**

For production environments, we recommend configuring alerts for the [Atlas Auto-Scaling](https://www.mongodb.com/docs/atlas/reference/alert-conditions.md#std-label-alert-conditions-autoscaling) category to maintain visibility into scaling actions. Atlas generates alerts for both reactive and predictive auto-scaling events, including:

- Cluster tier auto-scaling initiated (reactive)

- Predictive compute auto-scaling initiated

- Predictive auto-scaling did not initiate due to maximum tier

- Disk auto-scaling initiated

These alerts help you track when Atlas automatically adjusts cluster resources in response to workload changes. To learn more about auto-scaling alerts and how to configure them, see [Fix Auto-Scaling Issues.](https://www.mongodb.com/docs/atlas/reference/alert-resolutions/atlas-autoscaling-alerts/)

#### Monitor by Using Atlas Built-In Tools

Atlas provides several tools that allow you to proactively monitor and improve the performance of your database.

##### Real-Time Performance Panel

The Real-Time Performance Panel (RTPP) in the Atlas UI provides insights into current network traffic, database operations, and hardware statistics about the hosts at a one second granularity in the Atlas UI. We recommend that you use RTPP (Real-Time Performance Panel) to:

- Visually identify relevant database operations

- Evaluate query execution times

- Evaluate the ratio of documents scanned to documents returned

- Monitor network load and throughput

- Discover potential replication lag on secondary members of replica sets

- Kill operations before they have completed to free up valuable resources

The RTPP is not available to monitor from the Atlas Administration API, but you can enable and disable the RTPP from the Atlas Administration API with [Update One Project Settings.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-updateprojectsettings)

To learn more, see [Monitor Real-Time Performance.](https://www.mongodb.com/docs/atlas/real-time-performance-panel.md#std-label-real-time-metrics-status-tab)

##### Query Profiler

The Query Profiler identifies slow queries and bottlenecks, and suggests index refinement and query restructuring to improve the performance of your database. It provides visibility into the slowest operations over up to seven days in the Atlas UI, making it easier to identify trends and outliers in query efficiency. We recommend that you use this data to pinpoint and troubleshoot poorly performing queries, reducing performance overhead.

You can return log lines for slow queries that the Query Profiler identifies from the Atlas Administration API with [Return Slow Queries.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-listslowqueries)

To learn more, see [Monitor Query Performance with the Query Profiler.](https://www.mongodb.com/docs/atlas/tutorial/query-profiler.md#std-label-query-profiler)

##### Performance Advisor

The Performance Advisor automatically analyzes logs for slow-running queries and recommends indexes to create and drop. It analyzes slow queries and provides index suggestions for individual collections, ranked by a calculated impact score, and tailored to your workload. This gives you an easy, instantaneous way to make high-impact performance improvements. We recommend that you monitor regularly, focus on slow queries, and enable the profiler selectively to minimize overhead.

You can use the Atlas UI, Atlas CLI, and the Atlas Administration API to view slow queries and suggestions for improving the performance of your queries from the Performance Advisor.

You can return log lines for slow queries that the Performance Advisor identifies from the Atlas Administration API with [Return Slow Queries](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-listslowqueries). To return suggested indexes and more with the Atlas Administration API, see [Performance Advisor.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-performance-advisor)

To learn more, see [Monitor and Improve Slow Queries with the Performance Advisor.](https://www.mongodb.com/docs/atlas/performance-advisor.md#std-label-performance-advisor)

##### Namespace Insights

The Namespace Insights page in the Atlas UI allows you to monitor collection-level performance and usage metrics. It displays metrics (such as the number of CRUD operations on the collection) and statistics (like average query execution time) for certain hosts and operation types for the collections that you [pin for monitoring](https://www.mongodb.com/docs/atlas/namespace-insights/#manage-pinned-namespaces-from-the-dialog). This gives you more granular visibility into collection-level performance, which you can use to optimize database performance, resolve issues, and make decisions about scaling, indexing, and query tuning.

To learn more, see [Monitor Collection-Level Query Latency with Namespace Insights.](https://www.mongodb.com/docs/atlas/namespace-insights.md#std-label-namespace-insights)

##### Activity Feed

The Organization Activity Feed and Project Activity Feed in the Atlas UI list all events that occur for a given Atlas organization or project, respectively. You can filter each activity feed for event type and time range to monitor events such as API access updates, alert configuration changes, and more. This allows you to review activity records for your organization or project at your desired level of granularity.

Auto-scaling events, including both reactive and predictive auto-scaling actions, are logged in the Activity Feed. Filter these events to distinguish between reactive scaling that current resource usage triggers and predictive scaling that forecasted cyclical demand patterns trigger. This visibility helps you understand when and why Atlas adjusts cluster resources automatically.

You use the Atlas UI, Atlas CLI, and Atlas Administration API to retrieve events from each activity feed. To learn more, see [View Activity Feed.](https://www.mongodb.com/docs/atlas/tutorial/activity-feed.md#std-label-activity-feed)

#### Monitor by Using Logs

Atlas retains the last 30 days of log messages and system event audit messages. You can download Atlas logs at any point until the end of their retention periods by using the Atlas UI, Atlas Administration API, and Atlas CLI.

To learn more, see [View and Download MongoDB Logs.](https://www.mongodb.com/docs/atlas/mongodb-logs.md#std-label-mongodb-logs)

You can also [export logs to an AWS S3 bucket](https://www.mongodb.com/docs/atlas/export-logs-external-sinks/). When you configure this feature, Atlas exports from `mongod`, `mongos`, and audit logs to an AWS (Amazon Web Services) S3 bucket every minute.

## Automation Examples: Atlas Monitoring and Logging

The following examples demonstrate how to enable monitoring using Atlas [tools for automation.](https://www.mongodb.com/docs/atlas/architecture/current/automation.md#std-label-arch-center-automation)

### Dev and Test Environments

### Dev and Test Environments

### CLI

### View Cluster Metrics

Run the following command to retrieve the amount of used and free space on the specified disk. This metric can be used to determine if the system is running out of free space.

```text
atlas metrics disks describe atlas-lnmtkm-shard-00-00.ajlj3.mongodb.net:27017 data \
  --granularity P1D \
  --period P1D \
  --type DISK_PARTITION_SPACE_FREE,DISK_PARTITION_SPACE_USED \
  --projectId 6698000acf48197e089e4085 \
```

### Configure Alerts

Run the following command to create an alert notification to an email address when your deployment doesn't have a primary.

```text
atlas alerts settings create \
  --enabled \
  --event "NO_PRIMARY" \
  --matcherFieldName CLUSTER_NAME \
  --matcherOperator EQUALS \
  --matcherValue ftsTest \
  --notificationType EMAIL \
  --notificationEmailEnabled \
  --notificationEmailAddress "myName@example.com" \
  --notificationIntervalMin 5 \
  --projectId 6698000acf48197e089e4085
```

### Monitor Database Performance

Run the following command to enable Atlas-managed slow operation threshold for your project.

```text
atlas performanceAdvisor slowOperationThreshold enable --projectId 56fd11f25f23b33ef4c2a331
```

### Download Logs

Run the following command to download a compressed file that contains the MongoDB logs for the specified host in your project.

```text
atlas logs download cluster0-shard-00-00.a1b2c.mongodb.net mongodb.gz
```