Cloud Audit Logs overview

This document provides a conceptual overview of Cloud Audit Logs.

Google Cloud services write audit logs that record administrative activities and accesses within your Google Cloud resources. Audit logs help you answer "who did what, where, and when?" within your Google Cloud resources with the same level of transparency as in on-premises environments. Enabling audit logs helps your security, auditing, and compliance entities monitor Google Cloud data and systems for possible vulnerabilities or external data misuse.

Google services producing audit logs

For a list of Google Cloud services that provide audit logs, see Google services with audit logs. All Google Cloud services will eventually provide audit logs.

Types of audit logs

Cloud Audit Logs provides the following audit logs for each Cloud project, folder, and organization:

Admin Activity audit logs
Data Access audit logs
System Event audit logs
Policy Denied audit logs

Admin Activity audit logs

Admin Activity audit logs contain log entries for API calls or other actions that modify the configuration or metadata of resources. For example, these logs record when users create VM instances or change Identity and Access Management permissions.

Admin Activity audit logs are always written; you can't configure, exclude, or disable them. Even if you disable the Cloud Logging API, Admin Activity audit logs are still generated.

Data Access audit logs

Data Access audit logs contain API calls that read the configuration or metadata of resources, as well as user-driven API calls that create, modify, or read user-provided resource data.

Publicly available resources that have the Identity and Access Management policies allAuthenticatedUsers or allUsers don't generate audit logs. Resources that can be accessed without logging into a Google Cloud, Google Workspace, Cloud Identity, or Drive Enterprise account don't generate audit logs. This helps protect end-user identities and information.

Data Access audit logs-- except for BigQuery Data Access audit logs-- are disabled by default because audit logs can be quite large. If you want Data Access audit logs to be written for Google Cloud services other than BigQuery, you must explicitly enable them. Enabling the logs might result in your Cloud project being charged for the additional logs usage. For instructions on enabling and configuring Data Access audit logs, see Configure Data Access logs.

System Event audit logs

System Event audit logs contain log entries for Google Cloud actions that modify the configuration of resources. System Event audit logs are generated by Google systems; they aren't driven by direct user action.

System Event audit logs are always written; you can't configure, exclude, or disable them.

Policy Denied audit logs

Policy Denied audit logs are recorded when a Google Cloud service denies access to a user or service account because of a security policy violation. The security policies are determined by VPC Service Controls, which provides the Policy Denied audit logs to Cloud Logging.

Policy Denied audit logs are generated by default and your Cloud project is charged for the logs storage. You can't disable Policy Denied audit logs, but you can use exclusion filters to prevent Policy Denied audit logs from being ingested and stored in Cloud Logging.

Audit log entry structure

Every audit log entry in Cloud Logging is an object of type LogEntry. What distinguishes an audit log entry from other log entries is the protoPayload field; this field contains an AuditLog object that stores the audit logging data.

To understand how to read and interpret audit log entries, review Understanding audit logs.

Caller identities in audit logs

Audit logs record the identity that performed the logged operations on the Google Cloud resource. The caller's identity is held in the AuthenticationInfo field of AuditLog objects.

The caller's principal email address is redacted from an audit log if the operation is read-only and fails with a "permission denied" error. The only exception is when the caller is a service account in the Google Cloud organization associated with the resource, then the email address isn't redacted.

In addition to the conditions listed above, the following applies to certain Google Cloud products:

Legacy App Engine API: Identities aren't collected.
BigQuery: Caller identities and IP addresses, as well as some resource names, are redacted from the audit logs, unless certain conditions are met. For details, see BigQuery audit logs overview.

If you're viewing audit logs using the Google Cloud Console Activity page, User (anonymized) is displayed for any log entries where identity is redacted or empty.

Viewing audit logs

To find and view audit logs, you need to know the identifier of the Cloud project, folder, or organization for which you want to view audit logging information. You can further specify other indexed LogEntry fields, like resource.type; for details, review Find log entries quickly.

The following are the audit log names; they include variables for the identifiers of the Cloud project, folder, or organization:

   projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity
   projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access
   projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fsystem_event
   projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fpolicy

   folders/FOLDER_ID/logs/cloudaudit.googleapis.com%2Factivity
   folders/FOLDER_ID/logs/cloudaudit.googleapis.com%2Fdata_access
   folders/FOLDER_ID/logs/cloudaudit.googleapis.com%2Fsystem_event
   folders/FOLDER_ID/logs/cloudaudit.googleapis.com%2Fpolicy

   organizations/ORGANIZATION_ID/logs/cloudaudit.googleapis.com%2Factivity
   organizations/ORGANIZATION_ID/logs/cloudaudit.googleapis.com%2Fdata_access
   organizations/ORGANIZATION_ID/logs/cloudaudit.googleapis.com%2Fsystem_event
   organizations/ORGANIZATION_ID/logs/cloudaudit.googleapis.com%2Fpolicy

You can view audit logs in Cloud Logging using the Cloud Console, the gcloud command-line tool, or the Logging API.

Console

You can use the Logs Explorer in the Cloud Console to retrieve your audit log entries for your Cloud project, folder, or organization:

In the Cloud Console, go to the Logging > Logs Explorer page.

Go to the Logs Explorer page

Note: If you're using the Legacy Logs Viewer page, switch to the Logs Explorer page.
On the Logs Explorer page, select an existing Cloud project, folder or organization.
In the Query builder pane, do the following:
- In Resource type, select the Google Cloud resource whose audit logs you want to see.
- In Log name, select the audit log type that you want to see:
  - For Admin Activity audit logs, select activity.
  - For Data Access audit logs, select data_access.
  - For System Event audit logs, select system_event.
  - For Policy Denied audit logs, select policy.
If you don't see these options, then there aren't any audit logs of that type available in the Cloud project, folder, or organization.

For more details about querying using the Logs Explorer, see Build log queries.

gcloud

The gcloud command-line tool provides a command-line interface to the Cloud Logging API. Supply a valid PROJECT_ID, FOLDER_ID, or ORGANIZATION_ID in each of the log names.

To read your Cloud project-level audit log entries, run the following command:

gcloud logging read "logName : projects/PROJECT_ID/logs/cloudaudit.googleapis.com" --project=PROJECT_ID

To read your folder-level audit log entries, run the following command:

gcloud logging read "logName : folders/FOLDER_ID/logs/cloudaudit.googleapis.com" --folder=FOLDER_ID

To read your organization-level audit log entries, run the following command:

gcloud logging read "logName : organizations/ORGANIZATION_ID/logs/cloudaudit.googleapis.com" --organization=ORGANIZATION_ID

For more information about using the gcloud tool, see Read log entries.

API

When building your queries, replace the variables with valid values, substitute the appropriate project-level, folder-level, or organization-level audit log name or identifiers as listed in the audit log names. For example, if your query includes a PROJECT_ID, then the project identifier you supply must refer to the currently selected Cloud project.

To use the Logging API to look at your audit log entries, do the following:

Go to the Try this API section in the documentation for the entries.list method.
Put the following into the Request body part of the Try this API form. Clicking on this prepopulated form automatically fills the request body, but you need to supply a valid PROJECT_ID in each of the log names.
```
{
  "resourceNames": [
    "projects/PROJECT_ID"
  ],
  "pageSize": 5,
  "filter": "logName : projects/PROJECT_ID/logs/cloudaudit.googleapis.com"
}
```
Click Execute.

For more details about querying, see Logging query language.

For an example of an audit log entry and how to find the most important information in it, see Sample audit log entry.

Using the Activity page

You can view abbreviated audit log entries in your Cloud project, folder or organization's Activity page in the Cloud Console. The actual audit log entries might contain more information than appears on the Activity page.

To view abbreviated audit log entries in the Cloud Console, do the following:

Go to the Activity page:

Go to the Activity page
In the project selector, select the Cloud project, folder, or organization for which you want to view audit logs entries.
In the Filter panel, select the entries you want to view.

In the Activity page, where the identity performing logged actions is redacted from the audit log entry, User (anonymized) is displayed. For more details, read Caller identities in audit logs on this page.

Storing and routing audit logs

Cloud Logging uses log buckets as containers that store and organize your logs data. For each Cloud project, folder, and organization, Logging automatically creates two log buckets, _Required and _Default, and correspondingly named sinks.

Cloud Logging _Required buckets ingest and store Admin Activity audit logs and System Event audit logs. You can't configure _Required buckets or any logs data in it.

The _Default buckets, by default, ingest and store any enabled Data Access audit logs as well as Policy Denied audit logs. To prevent Data Access audit logs from being stored in the _Default buckets, you can disable them. To prevent any Policy Denied audit logs from being stored in the _Default buckets, you can exclude them by modifying their sinks' filters.

You can also route your audit log entries to user-defined Cloud Logging buckets at the Cloud project level or to supported destinations outside of Logging using sinks. See Configure sinks for instructions.

When configuring your log sinks' filters, you need to specify the audit log types you want to route; for filtering examples, see Security logging queries.

If you want to route audit log entries for a Google Cloud organization, folder, or billing account, see Configure aggregated sinks.

Audit log retention

For details on how long log entries are retained by Logging, see the retention information in Quotas and limits: Logs retention periods.

Access control

IAM permissions and roles determine your ability to access audit logs data in the Logging API, the Logs Explorer, and the gcloud command-line tool.

For detailed information about the IAM permissions and roles you might need, see the Access control guide.

Quotas and limits

For details on logging usage limits, including the maximum sizes of audit logs, see Quotas and limits.

Pricing

Admin Activity audit logs and System Event audit logs are free.

Data Access audit logs and Policy Denied audit logs are chargeable.

For information about Cloud Logging pricing, see Google Cloud's operations suite pricing: Cloud Logging.

What's next

Learn how to read and understand audit logs
Learn how to configure Data Access audit logs
Review best practices for Cloud Audit Logs