> 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: cli, Terraform
-->

# Guidance for Atlas Logging

To review Atlas platform activities, use logs.

## Features for Atlas Logging

### Accessing Audit Logs

You can use the Atlas CLI, Atlas Administration API, or Atlas UI for the following auditing activities:

- [View and download audit logs](https://www.mongodb.com/docs/atlas/database-auditing.md#std-label-set-up-database-auditing) to track [system event actions](https://www.mongodb.com/docs/manual/reference/audit-message/mongo.md#std-label-audit-action-details-results) for deployments with multiple users. Atlas administrators can configure a custom auditing filter to choose the actions, database users, Atlas roles, and LDAP (Lightweight Directory Access Protocol) groups that they want to audit.

- [View and download MongoDB logs](https://www.mongodb.com/docs/atlas/mongodb-logs.md#std-label-mongodb-logs) to track log events for your deployment, including incoming connections, commands run, and issues encountered. Generally, log messages are useful for diagnosing issues, monitoring your deployment, and tuning performance.

- [View project and organization events](https://www.mongodb.com/docs/atlas/tutorial/activity-feed.md#std-label-view-activity-feed) in the Project Activity Feed and Organization Activity Feed. These activity feeds list all events at the organization or project level, including changes related to Atlas access, alert configurations and monitoring, billing, and more.

- [View database authentication attempts](https://www.mongodb.com/docs/atlas/access-tracking.md#std-label-access-tracking) that users make against your cluster in your access logs (i.e. Database access history in the Atlas UI). Atlas logs both successful and unsuccessful authentication attempts, including the timestamp of each attempt and which user tried to authenticate.

### Programmatic Access to Audit Logs

To integrate with tools beyond the built-in integrations, we recommend that you retrieve logs with the following programmatic tools and feed the JSON (Javascript Object Notation)-formatted output to your external tools:

- To continually export logs to an AWS (Amazon Web Services) S3 (Simple Storage Service) bucket, use the Atlas Administration API endpoint for [Create One Log Integration.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-creategrouplogintegration)

- To retrieve deployment logs and lists of project events, use the Atlas Administration API endpoints for [Monitoring and Logs](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-monitoring-and-logs) and [Project and Organization Events.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-events)

- To retrieve deployment logs, use the [atlas deployment logs](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-deployments-logs.md#std-label-atlas-deployments-logs) command in the Atlas CLI.

## Recommendations for Atlas Logging

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

To perform a full audit, you can use a combination of [audit logs](https://www.mongodb.com/docs/manual/reference/audit-message/), [MongoDB log messages](https://www.mongodb.com/docs/manual/reference/log-messages/), and [the project and organization activity feed.](https://www.mongodb.com/docs/atlas/tutorial/activity-feed.md#std-label-view-activity-feed)

By default, audit log messages are returned in a format designed by MongoDB, called the [mongo schema](https://www.mongodb.com/docs/manual/reference/audit-message/mongo/). Audit log messages that follow the `mongo` schema always include the following information:

- Action type (`atype`)

- Timestamp

- Client connection ID (UUID)

- Client IP address and port number

- Incoming connection IP address and port number

- Username(s)

- User authentication database(s)

- User role(s)

- User role database(s)

- `param` document containing specific details for the event

- Result value or error code

For a full list of audit action types and their associated `param` details and `result` values, see [mongo Schema Audit Messages.](https://www.mongodb.com/docs/manual/reference/audit-message/mongo/)

## Automation Examples: Atlas Logging

**Tip:**

For Terraform examples that enforce our recommendations across all pillars, see one of the following examples in GitHub:

- [Staging/Prod](https://github.com/mongodb/docs/blob/main/content/atlas-architecture/current/source/includes/examples/tf-staging-prod-complete/)

- [Dev/Test](https://github.com//mongodb/docs/blob/main/content/atlas-architecture/current/source/includes/examples/tf-dev-test-complete/)

The following examples show how to retrieve and download logs and configure auditing using Atlas [tools for automation.](https://www.mongodb.com/docs/atlas/architecture/current/automation.md#std-label-arch-center-automation)

### CLI

You can retrieve logs and download logs. You can also retrieve alerts.

- Retrieving logs allows you to get logs for real-time viewing and accessing of current log files.

- Downloading logs lets you create a log archive from MongoDB Atlas for later analysis or storage.

### Retrieve Logs

Retrieve logs to monitor and examine your cluster's activity in real-time and to  troubleshoot an issue in current logs.

Each [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) and [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance in a cluster outputs its own [MongoDB log](https://www.mongodb.com/docs/manual/reference/log-messages/) and audit log messages with potentially different contents than other instances. You can view these log messages in the Atlas CLI using the [atlas deployment logs](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-deployments-logs.md#std-label-atlas-deployments-logs) command.

To retrieve audit log entries for a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance in your cluster, provide the [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) hostname and specify `mongodb-audit-log.gz` as the name of the audit log file:

```text
atlas deployments logs --output json --type atlas --hostname cluster0-shard-00-00.a1b2c.mongodb.net --name mongodb-audit-log.gz
```

To retrieve audit log entries for a [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance in a sharded cluster, provide the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) hostname and specify `mongos-audit-log.gz` as the name of the audit log file:

```text
atlas deployments logs --output json --type atlas --hostname cluster0-shard-00-00.a1b2c.mongodb.net --name mongos-audit-log.gz
```

To retrieve [MongoDB log messages](https://www.mongodb.com/docs/manual/reference/log-messages/), provide the hostname of your [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance, and specify the name of the log file as `mongodb.gz` or `mongos.gz`, respectively:

```text
atlas deployments logs --output json --type atlas --hostname cluster0-shard-00-00.a1b2c.mongodb.net --name mongodb.gz
```

You can also use the [atlas accessLogs list](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-accessLogs-list.md#std-label-atlas-accessLogs-list) command to view the access log for a node or cluster. The access log is a JSON (Javascript Object Notation)-formatted list of all authentication requests against your specified node or cluster.

To retrieve the access log, run the [atlas accessLogs list](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-accessLogs-list.md#std-label-atlas-accessLogs-list) command and specify the hostname or cluster name of the target node or cluster:

```text
atlas accessLogs list --output json --clusterName Cluster0
```

### Download Logs

Download logs to focus on historical logs and analyze them for audits or performance, or to archive them.

Each [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) and [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance in a cluster has its own [MongoDB log](https://www.mongodb.com/docs/manual/reference/log-messages/) and audit log with potentially different contents than other instances. Even though, from the perspective of the application, a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) or a [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance behaves identically to any other MongoDB instance, their logs contain information specific to their roles in MongoDB.

- The logs for [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) contain data requests, data access information, and background management operations for MongoDB.

- The logs for [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) contain information about routing queries and write operations to the shards in a sharded cluster.

You can download each log as a compressed file using the [atlas logs download](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-deployments-logs.md#std-label-atlas-deployments-logs) Atlas CLI command.

To download the audit log for a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance in your cluster, provide the [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) hostname and the audit log file name `mongodb-auditlog.gz` as arguments. The name of this file is used here as an example and you can use another name.

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

To download the audit log for a [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance in a sharded cluster deployment, provide the [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) hostname and the audit log file name `mongos-auditlog.gz` as arguments. The name of this file is used here as an example and you can use another name.

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

To download the [MongoDB log](https://www.mongodb.com/docs/manual/reference/log-messages/) for a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance, provide as arguments the hostname of the instance and the log file names `mongodb.gz` or `mongos.gz`, respectively:

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

### Retrieve All Project Alerts

You can use the following Atlas CLI commands to return alerts triggered by events for your project or organization. Atlas provides alerts such as [`Replica set has no primary`](https://www.mongodb.com/docs/atlas/reference/alert-conditions.md#mongodb-alert-Replica-set-has-no-primary) and [`User joined the project`](https://www.mongodb.com/docs/atlas/reference/alert-conditions.md#mongodb-alert-User-joined-the-project) by default. These events provide a record of significant activities and changes within the project or organization, including significant database, billing, or security activities or status changes.

To customize which events trigger alerts for your project and organization, see [Configure Alert Settings.](https://www.mongodb.com/docs/atlas/configure-alerts.md#std-label-configure-alerts)

### Retrieve All Log Events for Your Project or Organization

You can use the following Atlas CLI commands to return project or organization events from your Project Activity Feed or Organization Activity Feed.

To return all events for your organization, use the [atlas events organizations list](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-events-organizations-list.md#std-label-atlas-events-organizations-list) command and specify your organization ID. The following command returns a JSON-formatted list of events for the organization with the ID `5dd5a6b6f10fab1d71a58495`:

```text
atlas events organizations list --orgId 5dd5a6b6f10fab1d71a58495 --output json
```

To return all events for your project, use the [atlas events projects list](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-events-projects-list.md#std-label-atlas-events-projects-list) command and specify your project ID. The following command returns a JSON-formatted list of events for the project with the ID `64ac57bfe9810c0263e9d655`:

```text
atlas events organizations list --orgId 5dd5a6b6f10fab1d71a58495 --output json
```

### Download All Query Logs for an Entire Cluster

To download query logs for an entire cluster, obtain the required permissions, select your cluster in the Atlas UI, click Online Archive, and run:

```text
<cluster-name>_cluster_archive_<start-date>_<end-date>_queries.log.gz
```