Cloud Audit Logs overview | Cloud Logging

This document provides a conceptual overview of Cloud Audit Logs.

Google Cloud services write audit logs that record administrative activitiesand accesses within your Google Cloud resources. Audit logs help youanswer "who did what, where, and when?" within your Google Cloud resourceswith the same level of transparency as in on-premises environments. Enablingaudit logs helps your security, auditing, and compliance entities monitorGoogle Cloud data and systems for possible vulnerabilities or externaldata misuse.

Google services producing audit logs

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

For an overview of Google Workspace audit logs, seeAudit logs for Google Workspace.

Required roles

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

To get the permissions that you need to get read-only access to Admin Activity, Policy Denied, andSystem 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 youcannot 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 _Defaultbuckets, 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 thepermissions 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 thatapply to audit logs data, seeAccess control with IAM.

Types of audit logs

Cloud Audit Logs provides the following audit logs for eachGoogle 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 actionsthat modify the configuration or metadata of resources. For example, these logsrecord when users create VM instances or change Identity and Access Management permissions.

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

For a list of services that write Admin Activity audit logs and detailedinformation about which activities generate those logs, seeGoogle Cloud services with audit logs.

Data Access audit logs

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

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

Data Access audit logs—except forBigQuery Data Access audit logs—are disabled by default becauseaudit logs can be quite large. If you want DataAccess audit logs to be written for Google Cloud services other thanBigQuery, you must explicitly enable them. Enabling the logs mightresult in your Google Cloud project being charged for the additional logsusage. For instructions on enabling and configuring Data Access audit logs, seeEnable Data Access audit logs.

For a list of services that write Data Access audit logs and detailedinformation about which activities generate those logs, seeGoogle Cloud services with audit logs.

Data Access audit logs are stored in the_Default log bucket unlessyou've routed them elsewhere. For more information, see theStoring and routing audit logssection of this page.

System Event audit logs

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

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

For a list of services that write System Event audit logs and detailedinformation about which activities generate those logs, seeGoogle Cloud services with audit logs.

Policy Denied audit logs

Policy Denied audit logs are recorded when a Google Cloud service denies accessto a user or service account because of a securitypolicy violation.

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

For a list of services that write Policy Denied audit logs and detailedinformation about which activities generate those logs, seeGoogle Cloud services with audit logs.

Audit log entry structure

Every audit log entry in Cloud Logging is an object of typeLogEntry. What distinguishes an audit log entry from other logentries is the protoPayload field; this field contains anAuditLog object that stores the audit logging data.

To understand how to read and interpret audit log entries, and for a sample ofan audit log entry, seeUnderstanding audit logs.

Log name

Cloud Audit Logs log names include the following:

Resource identifiers indicating the Google Cloud project orother 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 resourceidentifiers:

 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 theGoogle Cloud resource. The caller's identity is held in theAuthenticationInfo field of AuditLog objects.

Audit logging doesn't redact the caller's principal email address for anyaccess 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 thecaller is a service account.

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

Legacy App Engine API: Identities aren'tcollected.
BigQuery: Calleridentities and IP addresses, as well as some resource names, are redactedfrom the audit logs, unless certain conditions are met.
Cloud Storage: When Cloud Storageusage logs are enabled, Cloud Storage writes usage data to theCloud Storage bucket, which generates Data Access audit logs for thebucket. The generated Data Access audit log has its caller identityredacted.
Firestore: If a JSON Web Token(JWT) was used for third-party authentication, the thirdPartyPrincipalfield includes the token's header and payload. For example, audit logs forrequests authenticated with Firebase Authentication include thatrequest's auth token.
VPC Service Controls: ForPolicy Denied audit logs, the following redaction occurs:
- Parts of the caller email addresses might be redacted and replaced bythree period characters ....
- Some caller email addresses belonging to the domain google.com areredacted and replaced by google-internal.
Organization Policy:Parts of the caller email addresses might be redacted and replaced bythree period characters ....
See Also
What is an Audit Trail? - Types, Purpose, & Importance | Tipalti

IP address of the caller in audit logs

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

For a caller from the internet, the address is a public IPv4 or IPv6address.
For calls made from inside Google's internal production network from oneGoogle Cloud service to another, the caller_ip is redacted to "private".
For a caller from a Compute Engine VM with a external IP address, thecaller_ip is the external address of the VM.
For a caller from a Compute Engine VM without a external IP address, ifthe VM is in the same organization or project as the accessed resource, thencaller_ip is the VM's internal IPv4 address. Otherwise, the caller_ip isredacted to "gce-internal-ip". For more information, seeVPC network overview.

Viewing audit logs

You can query for all audit logs or you can query for logs by theiraudit log name. The audit log name includes theresource identifierof the Google Cloud project, folder, billing account, ororganization for which you want to view audit logging information.Your queries can specify indexed LogEntry fields, and if you usethe Log Analytics page, which supports SQL queries, then you canview your query results as a chart.

For more information about querying your logs, see the following pages:

Build queries in the Logs Explorer.
Query and view logs in Log Analytics.
Sample queries for security insights.

You can view audit logs in Cloud Logging by using theGoogle Cloud console, the Google Cloud CLI, or the Logging API.

Console

In the Google Cloud console, you can use the Logs Explorerto 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 isLogging.
Select an existing Google Cloud project, folder, or organization.
To display all audit logs, enter either of the following queriesinto 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 whoseaudit 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 ofthat type available in the Google Cloud project, folder, ororganization.
If you're experiencing issues when trying to view logs in theLogs Explorer, see thetroubleshootinginformation.
For more information about querying by using the Logs Explorer, seeBuild queries in the Logs Explorer.For information about summarizing log entries in the Logs Explorerby using Gemini, seeSummarize log entries with Gemini assistance.

gcloud

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

To read your Google Cloud project-level audit log entries, runthe 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 followingcommand:

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 flagto your command to read logs that are more than 1 day old.

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

API

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

For example, to use the Logging API to view your project-levelaudit log entries, do the following:

Go to the Try this API section in the documentation for theentries.listmethod.
Put the following into the Request body part of the Try thisAPI form. Clicking this prepopulated formautomatically fills the request body, but you need to supply a validPROJECT_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 ascontainers that store and organize your logs data. For eachGoogle Cloud project, folder, and organization, Loggingautomatically creates two log buckets, _Required and _Default, andcorrespondingly named sinks.

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

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 adifferent project, then those logs don't pass through the _Default or_Required sink of the destination project. Therefore, these logs aren't storedin the _Default log bucket or the _Required log bucket of the destinationproject. 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 Accessaudit logs as well as Policy Denied audit logs. To prevent Data Access auditlogs from being stored in the _Default buckets, you can disable them. Toprevent any Policy Denied audit logs from being stored in the _Defaultbuckets, you can exclude them by modifying their sinks' filters.

You can also route your audit log entries to user-definedCloud Logging buckets at the Google Cloud project level or to supporteddestinations outside of Logging using sinks. For instructionson routing logs, seeRoute logs to supported destinations.

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

If you want to route audit log entries for a Google Cloud organization,folder, or billing account, seeCollate 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 inQuotas and limits: Logs retention periods.

Access control

IAM permissions and roles determine your ability to access auditlogs data in the Logging API, theLogs Explorer, and theGoogle Cloud CLI.

For detailed information about the IAM permissions and roles youmight 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 asupported destination; however, the destination might apply charges.With the exception of the _Required log bucket,Cloud Logging charges to stream logs into log buckets andfor storage longer than the default retention period of the log bucket.

Cloud Logging doesn't charge for copying logs,for defining log scopes,or for queries issued through theLogs Explorer or Log Analytics pages.

For more information, see the following documents:

Cloud Logging pricing summary
Destination costs:
- Cloud Storage pricing
- BigQuery pricing
- Pub/Sub pricing
- Cloud Logging pricing
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 toread and understand audit logs.
Learn how toenable Data Access audit logs.
Review best practices forCloud Audit Logs.
Learn about Access Transparency,which provides logs of actions taken by Google Cloud staff when accessing yourGoogle Cloud content.

Cloud Audit Logs overview | Cloud Logging | Google Cloud (2024)