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 Cloud services producing audit logs

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

For an overview of Google Workspace audit logs, see Audit logs for Google Workspace.

Required roles

To view audit logs, you must have the appropriate Identity and Access Management (IAM) permissions and roles:

To get the permissions that you need to get read-only access to Admin Activity, Policy Denied, and System Event audit logs, ask your administrator to grant you the Logs Viewer (roles/logging.viewer) IAM role on your project.

If you have only the Logs Viewer role (roles/logging.viewer), then you cannot view Data Access audit logs that are in the _Default bucket.

To get the permissions that you need to get access to all logs in the _Required and _Default buckets, including Data Access logs, ask your administrator to grant you the Private Logs Viewer (roles/logging.privateLogViewer) IAM role on your project.

The Private Logs Viewer role (roles/logging.privateLogViewer) includes the permissions contained in the Logs Viewer role (roles/logging.viewer), and those necessary to read Data Access audit logs in the _Default bucket.

For more information about the IAM permissions and roles that apply to audit logs data, see Access control with IAM.

Types of audit logs

Cloud Audit Logs provides the following audit logs for each Google 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.

For a list of services that write Admin Activity audit logs and detailed information about which activities generate those logs, see Google Cloud services with audit logs.

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 Google Cloud project being charged for the additional logs usage. For instructions on enabling and configuring Data Access audit logs, see Enable Data Access audit logs.

For a list of services that write Data Access audit logs and detailed information about which activities generate those logs, see Google Cloud services with audit logs.

Data Access audit logs are stored in the _Default log bucket unless you've routed them elsewhere. For more information, see the Storing and routing audit logs section of this page.

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 Cloud systems; they aren't driven by direct user action.

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

For a list of services that write System Event audit logs and detailed information about which activities generate those logs, see Google Cloud services with audit logs.

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.

Policy Denied audit logs are generated by default and your Google 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 stored in Cloud Logging.

For a list of services that write Policy Denied audit logs and detailed information about which activities generate those logs, see Google Cloud services with audit logs.

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, and for a sample of an audit log entry, see Understanding audit logs.

Log name

Cloud Audit Logs log names include the following:

Resource identifiers indicating the Google Cloud project or other Google Cloud entity that owns the audit logs.
The string cloudaudit.googleapis.com.
A string that indicates whether the log contains Admin Activity, Data Access, Policy Denied, or System Event audit logging data.

The following are the audit log names, including variables for the resource identifiers:

   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

   billingAccounts/BILLING_ACCOUNT_ID/logs/cloudaudit.googleapis.com%2Factivity
   billingAccounts/BILLING_ACCOUNT_ID/logs/cloudaudit.googleapis.com%2Fdata_access
   billingAccounts/BILLING_ACCOUNT_ID/logs/cloudaudit.googleapis.com%2Fsystem_event
   billingAccounts/BILLING_ACCOUNT_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

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.

Audit logging doesn't redact the caller's principal email address for any access that succeeds or for any write operation.

For read-only operations that fail with a "permission denied" error, Audit Logging might redact the caller's principal email address unless the caller is a service account.

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

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.
Cloud Storage: When Cloud Storage usage logs are enabled, Cloud Storage writes usage data to the Cloud Storage bucket, which generates Data Access audit logs for the bucket. The generated Data Access audit log has its caller identity redacted.

Firestore: If a JSON Web Token (JWT) was used for third-party authentication, the thirdPartyPrincipal field includes the token's header and payload. For example, audit logs for requests authenticated with Firebase Authentication include that request's auth token.

VPC Service Controls: For Policy Denied audit logs, the following redaction occurs:
- Parts of the caller email addresses might be redacted and replaced by three period characters ....
- Some caller email addresses belonging to the domain google.com are redacted and replaced by google-internal.

Organization Policy: Parts of the caller email addresses might be redacted and replaced by three period characters ....

IP address of the caller in audit logs

The IP address of the caller is held in the RequestMetadata.callerIp field of the AuditLog object:

For a caller from the internet, the address is a public IPv4 or IPv6 address.
For calls made from inside the internal production network from one Google Cloud service to another, the callerIp is redacted to "private".
For a caller from a Compute Engine VM with a external IP address, the callerIp is the external address of the VM.
For a caller from a Compute Engine VM without a external IP address, if the VM is in the same organization or project as the accessed resource, then callerIp is the VM's internal IPv4 address. Otherwise, the callerIp is redacted to "gce-internal-ip". For more information, see VPC network overview.

Viewing audit logs

You can query for all audit logs or you can query for logs by their audit log name. The audit log name includes the resource identifier of the Google Cloud project, folder, billing account, or organization for which you want to view audit logging information. Your queries can specify indexed LogEntry fields. For more information about querying your logs, see Build queries in the Logs Explorer

The Logs Explorer lets you view filter individual log entries. If you want to use SQL to analyze groups of log entries, then use the Log Analytics page. For more information, see:

Most audit logs can be viewed in Cloud Logging by using the Google Cloud console, the Google Cloud CLI, or the Logging API. However, for audit logs related to billing, you can only use the Google Cloud CLI or the Logging API.

Console

In the Google Cloud console, you can use the Logs Explorer to retrieve your audit log entries for your Google Cloud project, folder, or organization:

In the Google Cloud console, go to the Logs Explorer page:
Go to Logs Explorer

If you use the search bar to find this page, then select the result whose subheading is Logging.
Select an existing Google Cloud project, folder, or organization.
To display all audit logs, enter either of the following queries into the query-editor field, and then click Run query:
```
logName:"cloudaudit.googleapis.com"
```
```
protoPayload."@type"="type.googleapis.com/google.cloud.audit.AuditLog"
```
To display the audit logs for a specific resource and audit log type, 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.
- Click Run query.
If you don't see these options, then there aren't any audit logs of that type available in the Google Cloud project, folder, or organization.

If you're experiencing issues when trying to view logs in the Logs Explorer, see the troubleshooting information.

For more information about querying by using the Logs Explorer, see Build queries in the Logs Explorer.

gcloud

The Google Cloud CLI provides a command-line interface to the Logging API. Supply a valid resource identifier in each of the log names. For example, if your query includes a PROJECT_ID, then the project identifier you supply must refer to the currently selected Google Cloud project.

To read your Google 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

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

gcloud logging read "logName : billingAccounts/BILLING_ACCOUNT_ID/logs/cloudaudit.googleapis.com" \
    --billing-account=BILLING_ACCOUNT_ID

Add the --freshness flag to your command to read logs that are more than 1 day old.

For more information about using the gcloud CLI, see gcloud logging read.

REST

When building your queries, supply a valid resource identifier in each of the log names. For example, if your query includes a PROJECT_ID, then the project identifier you supply must refer to the currently selected Google Cloud project.

For example, to use the Logging API to view your project-level 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 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.

Storing and routing audit logs

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

Cloud Logging _Required buckets store Admin Activity audit logs and System Event audit logs. You can't prevent Admin Activity or System Event audit logs from being stored. You also can't configure the sink that routes log entries to the _Required buckets.

Admin Activity audit logs and System Event audit logs are always stored in the _Required bucket in the project where the logs were generated.

If you route Admin Activity audit logs and System Event audit logs to a different project, then those logs don't pass through the _Default or _Required sink of the destination project. Therefore, these logs aren't stored in the _Default log bucket or the _Required log bucket of the destination project. To store these logs, create a log sink in the destination project. For more information, see Route logs to supported destinations.

The _Default buckets, by default, 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 Google Cloud project level or to supported destinations outside of Logging using sinks. For instructions on routing logs, see Route logs to supported destinations.

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 Collate and route organization-level logs to supported destinations.

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 Google Cloud CLI.

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

Quotas and limits

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

Pricing

Cloud Logging doesn't charge to route logs to a supported destination; however, the destination might apply charges. With the exception of the _Required log bucket, Cloud Logging charges to stream logs into log buckets and for storage longer than the default retention period of the log bucket.

Cloud Logging doesn't charge for copying logs, for creating log scopes or analytics views, or for queries issued through the Logs Explorer or Log Analytics pages.

For more information, see the following documents:

Cloud Logging pricing summary
Destination costs:
VPC flow log generation charges apply when you send and then exclude your Virtual Private Cloud flow logs from Cloud Logging.

What's next

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

Learn about Access Transparency, which provides logs of actions taken by Google Cloud staff when accessing your Google Cloud content.