> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Set Up Database Auditing **Note:** This page applies to both Atlas Infinite and Atlas Core. **Note:** This feature is not available for any of the following deployments: - Free clusters - Flex clusters To learn more, see [Limits.](https://www.mongodb.com/docs/atlas/reference/limitations.md#std-label-limits) Database auditing lets administrators track system activity for deployments with multiple users. Atlas administrators can select the actions, database users, Atlas roles, and LDAP groups that they want to audit. Atlas supports [auditing](https://www.mongodb.com/docs/manual/core/auditing/) most of the documented [system event actions.](https://www.mongodb.com/docs/manual/reference/audit-message/mongo.md#std-label-audit-action-details-results) The `authCheck` event action logs authorization attempts by users trying to read from and write to databases in the clusters in your project. Atlas audits the following specific commands: | `authCheck Reads` | `authCheck Writes` | | --- | --- | | [aggregate](https://www.mongodb.com/docs/manual/reference/command/aggregate/) | [aggregate](https://www.mongodb.com/docs/manual/reference/command/aggregate/) | | [mapReduce](https://www.mongodb.com/docs/manual/reference/command/mapReduce/) (deprecated in MongoDB 5.0) | [mapReduce](https://www.mongodb.com/docs/manual/reference/command/mapReduce/) (deprecated in MongoDB 5.0) | | [distinct](https://www.mongodb.com/docs/manual/reference/command/distinct/) | [delete](https://www.mongodb.com/docs/manual/reference/command/delete/) | | [count](https://www.mongodb.com/docs/manual/reference/command/count/) | [findAndModify](https://www.mongodb.com/docs/manual/reference/command/findAndModify/) | | [geoNear](https://www.mongodb.com/docs/manual/reference/command/geoNear/) (removed in MongoDB 4.2) | [insert](https://www.mongodb.com/docs/manual/reference/command/insert/) | | [geoSearch](https://www.mongodb.com/docs/manual/reference/command/geoSearch/) (removed in MongoDB 5.0) | [update](https://www.mongodb.com/docs/manual/reference/command/update/) | | [group](https://www.mongodb.com/docs/manual/reference/command/group/) (removed in MongoDB 4.2) | [resetError](https://www.mongodb.com/docs/v6.0/reference/command/resetError/) (removed in MongoDB 5.0) | | [find](https://www.mongodb.com/docs/manual/reference/command/find/) | | | [getLastError](https://www.mongodb.com/docs/manual/reference/command/getLastError/) (removed in MongoDB 5.1) | | | [getMore](https://www.mongodb.com/docs/manual/reference/command/getMore/) | | | [getPrevError](https://www.mongodb.com/docs/manual/reference/command/getPrevError/) (removed in MongoDB 4.2) | | Atlas implements the `authCheck` event action as the following four separate actions: | Event Action | Description | | --- | --- | | `authChecksReadFailures` | `authCheck` event action for all failed reads with the [auditAuthorizationSuccess](https://www.mongodb.com/docs/manual/reference/parameters/#param.auditAuthorizationSuccess) parameter set to false. This event action is the default for read-related event actions. | | `authChecksReadAll` | `authCheck` event action for all reads, both sucesses and failures. This event action is the same as `authChecksReadFailures`, but with the [auditAuthorizationSuccess](https://www.mongodb.com/docs/manual/reference/parameters/#param.auditAuthorizationSuccess) parameter set to true. WARNING: If you enable [auditAuthorizationSuccess](https://www.mongodb.com/docs/manual/reference/parameters/#param.auditAuthorizationSuccess), you might severely impact cluster performance. Enable this option with caution. | | `authChecksWriteFailures` | `authCheck` event action for all failed writes with the [auditAuthorizationSuccess](https://www.mongodb.com/docs/manual/reference/parameters/#param.auditAuthorizationSuccess) parameter set to false. This event action is the default for write-related event actions. | | `authChecksWriteAll` | `authCheck` event action for all writes, both successes and failures. This event action is the same as `authChecksWriteFailures`, but with the [auditAuthorizationSuccess](https://www.mongodb.com/docs/manual/reference/parameters/#param.auditAuthorizationSuccess) parameter set to true. WARNING: If you enable [auditAuthorizationSuccess](https://www.mongodb.com/docs/manual/reference/parameters/#param.auditAuthorizationSuccess), you might severely impact cluster performance. Enable this option with caution. | To learn about how MongoDB writes audit events to disk, see [Audit Guarantee](https://www.mongodb.com/docs/manual/core/auditing/#audit-guarantee) in the MongoDB Manual. ## Required Access To configure audit logs, you must have [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner) access to the project that you want to update or [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner) access to the organization that contains the project that you want to update. To learn about recommendations for auditing and logging, including the events that we recommend auditing, see [Guidance for Atlas Auditing and Logging](https://www.mongodb.com/docs/atlas/architecture/current/auditing-logging.md#std-label-arch-center-auditing-logging) in the Atlas Architecture Center. **Note:** The MongoDB Atlas Shared Responsibility Model defines the complementary duties of MongoDB and its customers in maintaining a secure and resilient data environment. Under this framework, MongoDB manages the security and operational integrity of the underlying platform, while customers are responsible for the configuration, management, and data policies of their specific deployments. For a detailed breakdown of ownership across security and operational excellence, see [Shared Responsibility Model.](https://www.mongodb.com/resources/products/fundamentals/shared-responsibility) To enforce that database auditing is enabled on all clusters in a project, use [Atlas Resource Policies](https://www.mongodb.com/docs/atlas/atlas-resource-policies.md#std-label-atlas-resource-policies-overview). You can use resource policies to require database auditing before you create or modify clusters. ## Procedure **Note:** To learn about best practices for auditing the actions of temporary database users, see [Audit Temporary Database Users.](https://www.mongodb.com/docs/atlas/production-notes.md#std-label-audit-temp-db-users) Use the following procedure to set up database auditing: 1. In Atlas, go to the Advanced page for your project. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar. If it's not already displayed, select your project from the Projects menu in the navigation bar. In the sidebar, click Database & Network Access under the Security heading. In the sidebar, click Advanced. The [Advanced](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsecurity%2Fadvanced) page displays. 2. Toggle the button next to Database Auditing to On. 3. Confirm that you want to audit authentication failures. By default, Atlas logs the failed authentication attempts of both known and unknown users in the audit log of the [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) node. 4. Select the database users, Atlas roles, and LDAP groups whose actions you want to audit in Select users and roles. Alternatively, click Use Custom JSON Filter to manually enter an [audit filter](https://www.mongodb.com/docs/manual/tutorial/configure-audit-filters/#auditfilter-option) as a JSON string. For more information on configuring custom audit filters in Atlas, see [Configure a Custom Auditing Filter.](https://www.mongodb.com/docs/atlas/database-auditing.md#std-label-auditing-custom-filter) 5. Select the event actions that you want to audit in Select actions to audit. **Note:** Deselecting the `authenticate` action prevents Atlas from auditing authentication failures. **Note:** When selecting the [authorization success granularity](https://www.mongodb.com/docs/manual/reference/parameters/#param.auditAuthorizationSuccess) of auditing for the `authCheck` event action, Atlas does not support different selections for reads and writes. For example, you may not select Successes and Failures for authCheck Reads and Failures for authCheck Writes. If you select both authCheck Reads and authCheck Writes, Atlas automatically applies your selected granularity to both. 6. Click Save. To retrieve the audit logs in Atlas, see [MongoDB Logs](https://www.mongodb.com/docs/atlas/mongodb-logs.md#std-label-mongodb-logs). To retrieve the audit logs using the API, see [Logs.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-downloadgroupclusterlog) ## Configure a Custom Auditing Filter **Note:** This feature is not available for any of the following deployments: - Free clusters - Flex clusters To learn more, see [Limits.](https://www.mongodb.com/docs/atlas/reference/limitations.md#std-label-limits) Atlas supports specifying a JSON-formatted audit filter for customizing [MongoDB Auditing.](https://www.mongodb.com/docs/manual/core/auditing/) Custom audit filters let users forgo the managed Atlas UI [auditing filter builder](https://www.mongodb.com/docs/atlas/database-auditing.md#std-label-set-up-database-auditing) in favor of hand-tailored granular control of event auditing. Atlas checks only that the custom filter uses valid JSON syntax, and doesn't validate or test the filter's functionality. The audit filter document must resolve to a query that matches one or more fields in the [audit event message](https://www.mongodb.com/docs/manual/reference/audit-message/#audit-message). The filter document can use combinations of [query operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates/) and equality conditions to match the desired audit messages. To view example auditing filters, see [Example Auditing Filters](https://www.mongodb.com/docs/atlas/database-auditing.md#std-label-auditing-filter-example). To learn more about configuring MongoDB auditing filters, see [Configure Audit Filter.](https://www.mongodb.com/docs/manual/tutorial/configure-audit-filters/) **Important:** Atlas uses a [rolling update](https://www.mongodb.com/docs/atlas/reference/faq/deployment.md#std-label-high-availability) strategy for enabling or updating audit configuration settings across all clusters in the Atlas project. Rolling updates require at least one election per replica set. To learn more about testing application resilience to replica set elections, see [Test Primary Failover](https://www.mongodb.com/docs/atlas/tutorial/test-resilience/test-primary-failover.md#std-label-test-failover). To learn more about how Atlas provides high availability, see [Atlas High Availability.](https://www.mongodb.com/docs/atlas/reference/faq/deployment.md#std-label-high-availability) ### Procedure 1. In Atlas, go to the Advanced page for your project. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar. If it's not already displayed, select your project from the Projects menu in the navigation bar. In the sidebar, click Database & Network Access under the Security heading. In the sidebar, click Advanced. The [Advanced](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsecurity%2Fadvanced) page displays. 2. Toggle the button next to Database Auditing to On. 3. Select Use Custom JSON Filter. 4. Enter your audit filter into the text box. 5. Toggle Audit authorization successes. **Warning:** Enabling Audit authorization successes can severely impact cluster performance. Enable this option with caution. For audit filters specifying the `authCheck` [action type](https://www.mongodb.com/docs/manual/reference/audit-message/#audit-event-actions-details-and-results), the auditing system logs only authorization failures for any specified `param.command` by default. Enabling Audit authorization successes directs the auditing system to also log authorization successes. If you don't enable [auditAuthorizationSuccess](https://www.mongodb.com/docs/manual/reference/parameters/#param.auditAuthorizationSuccess), your audit system can't log successful CRUD operations specified in the [action type](https://www.mongodb.com/docs/manual/reference/audit-message/#audit-event-actions-details-and-results). To learn more, see [auditAuthorizationSuccess.](https://www.mongodb.com/docs/manual/reference/parameters/#param.auditAuthorizationSuccess) 6. Click Save. ### Edit a Custom Auditing Filter You can edit your filter at any time: 1. In Atlas, go to the Advanced page for your project. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar. If it's not already displayed, select your project from the Projects menu in the navigation bar. In the sidebar, click Database & Network Access under the Security heading. In the sidebar, click Advanced. The [Advanced](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsecurity%2Fadvanced) page displays. 2. Edit the filter. Under Database Auditing Configure Your Auditing Filter, click Use Custom JSON Filter. Make the required changes. Click Save. ### View Your Custom Auditing Filter 1. In Atlas, go to the Advanced page for your project. If it's not already displayed, select the organization that contains your project from the Organizations menu in the navigation bar. If it's not already displayed, select your project from the Projects menu in the navigation bar. In the sidebar, click Database & Network Access under the Security heading. In the sidebar, click Advanced. The [Advanced](https://cloud.mongodb.com/go?l=https%3A%2F%2Fcloud.mongodb.com%2Fv2%2F%3Cproject%3E%23%2Fsecurity%2Fadvanced) page displays. 2. View your filter. Your custom auditing filter displays under Database Auditing. ## Example Auditing Filters Use the following example auditing filters for guidance in constructing your own filters. **Important:** These examples are not intended for use in production environments, nor are they a replacement for familiarity with the [MongoDB Auditing Documentation.](https://www.mongodb.com/docs/manual/core/auditing/) ### Audit all authentication events for known users ```json { "atype": "authenticate" } ``` ### Audit all authentication events for known users and authentication failures for unknown users ```json { "$or": [ { "users": [] }, { "atype": "authenticate" } ] } ``` **Note:** The `authenticate` action is required to log authentication failures from known and unknown users. ### Audit authentication events for the "myClusterAdministrator" user ```json { "atype": "authenticate", "param": { "user": "myClusterAdministrator", "db": "admin", "mechanism": "SCRAM-SHA-256" } } ``` ### Audit unauthorized attempts at executing the selected commands ```json { "atype": "authCheck", "param.command": { "$in": [ "insert", "update", "delete" ] } } ``` ### Audit user creation and deletion events ```json { "atype": { "$in": [ "createUser", "dropUser", "directAuthMutation" ] } } ``` **Note:** The `directAuthMutation` action tracks direct modifications to the `admin.system.users` and `admin.system.roles` collections. This includes SCRAM user creation and modification operations that Atlas performs directly in the `admin` database. ## Monitoring Agent Queries in Audit Logs When you enable database auditing, you might observe queries from the `mms-monitoring-agent` user in your audit logs. These queries are internal operations that Atlas uses to collect metrics and performance data for monitoring features. The `mms-monitoring-agent` user has the [`clusterMonitor`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-clusterMonitor) and [`directShardOperations`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-directShardOperations) roles and performs queries on behalf of the following Atlas monitoring features: - [Query Insights](https://www.mongodb.com/docs/atlas/query-shape-insights.md#std-label-query-shape-insights): Collects query performance statistics and shapes to help you identify slow queries. - [Namespace Insights](https://www.mongodb.com/docs/atlas/namespace-insights.md#std-label-namespace-insights): Gathers collection-level latency statistics using [$collStats](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collStats/) aggregation pipelines with `latencyStats` histograms. - Other performance metrics: Retrieves database and cluster statistics for monitoring dashboards. ### Example Audit Log Entry The following example shows an audit log entry for a Namespace Insights query. This query uses the [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collStats.md#mongodb-pipeline-pipe.-collStats) stage to collect latency statistics for a collection: ```json { "atype": "authCheck", "ts": { "$date": "2025-11-20T13:44:20.201+00:00" }, "users": [ { "user": "mms-monitoring-agent", "db": "admin" } ], "roles": [ { "role": "clusterMonitor", "db": "admin" }, { "role": "directShardOperations", "db": "admin" } ], "param": { "command": "aggregate", "ns": "test_db.people_1234", "args": { "aggregate": "people_1234", "pipeline": [ { "$collStats": { "latencyStats": { "histograms": true } } } ], "$readPreference": { "mode": "nearest" } } }, "result": 0 } ``` These queries are expected behavior and don't require action. If you want to exclude monitoring agent queries from your audit logs, you can create a custom audit filter. To learn more, see [Configure a Custom Auditing Filter.](https://www.mongodb.com/docs/atlas/database-auditing.md#std-label-auditing-custom-filter) ## Manage Database Auditing with the Atlas CLI You can use the Atlas CLI to manage database auditing configuration for your projects. ### Update Auditing Configuration To update the auditing configuration for the specified project using the Atlas CLI, run the following command: ```sh atlas auditing update [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas auditing update.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-auditing-update/) ### View Auditing Configuration To return the auditing configuration for the specified project using the Atlas CLI, run the following command: ```sh atlas auditing describe [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas auditing describe.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-auditing-describe/)