Understanding audit logs

This page describes Cloud Audit Logs log entries in detail: their structure,how to read them, and how to interpret them.

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

For a general overview of Cloud Audit Logs, seeCloud Audit Logs.

Format of audit log entries

An audit log entry is a type of Cloud Logging log entry. Like allLogging log entries, an audit log entry is stored in aLogEntry object. What distinguishes an audit log entry from otherlog entries is theprotoPayload field. In audit logentries, the log entry'sprotoPayload field contains anAuditLog object that stores the audit loggingdata.

In short, every audit log entry is characterized by the following information:

  • The project, folder, or organization that owns the log entry.
  • The resource to which the log entry applies. This information consistsof a resource type from theMonitored resource list andadditional values that denote a specific instance. For example, you canview audit log entries from a single Compute Engine VMinstance or from all VM instances.
  • A timestamp.

  • A service: Services are individual Google Cloud products, such asCompute Engine, Cloud SQL, or Pub/Sub. Each serviceis identified by name: Compute Engine iscompute.googleapis.com,Cloud SQL iscloudsql.googleapis.com, and so forth. This informationis listed in theprotoPayload.serviceName field of the audit log entry.

    Resource types belongs to a single service, but a service can have severalresource types. For a list of services and resources, go toMapping services to resources.

  • A payload, which is theprotoPayload type. The payload of eachaudit log entry is an object of typeAuditLog,which defines a set of fields specific to Cloud Audit Logs, such asserviceName andauthenticationInfo. It also has an optional field,metadata, that Google Cloud services use to list service-specificinformation in the audit log entry. Some Google Cloud services still use theolderserviceData field to list service-specific information. For a listof services that use theserviceData field, seeService-specific audit data.

  • A log name: Audit log entries belong to logs within billing accounts,projects, folders, and organizations. The following table lists log names:

projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivityprojects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_accessprojects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fsystem_eventprojects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fpolicyfolders/FOLDER_ID/logs/cloudaudit.googleapis.com%2Factivityfolders/FOLDER_ID/logs/cloudaudit.googleapis.com%2Fdata_accessfolders/FOLDER_ID/logs/cloudaudit.googleapis.com%2Fsystem_eventfolders/FOLDER_ID/logs/cloudaudit.googleapis.com%2FpolicybillingAccounts/BILLING_ACCOUNT_ID/logs/cloudaudit.googleapis.com%2FactivitybillingAccounts/BILLING_ACCOUNT_ID/logs/cloudaudit.googleapis.com%2Fdata_accessbillingAccounts/BILLING_ACCOUNT_ID/logs/cloudaudit.googleapis.com%2Fsystem_eventbillingAccounts/BILLING_ACCOUNT_ID/logs/cloudaudit.googleapis.com%2Fpolicyorganizations/ORGANIZATION_ID/logs/cloudaudit.googleapis.com%2Factivityorganizations/ORGANIZATION_ID/logs/cloudaudit.googleapis.com%2Fdata_accessorganizations/ORGANIZATION_ID/logs/cloudaudit.googleapis.com%2Fsystem_eventorganizations/ORGANIZATION_ID/logs/cloudaudit.googleapis.com%2Fpolicy

Within a billing account, project, folder, or organization, these log names are typically abbreviated asactivity,data_access,system_event, andpolicy.

Sample audit log entry

This section uses a sample audit log entry to explain how to find the mostimportant information in audit log entries.

The following sample is an Admin Activity audit log entry written byApp Engine to record a change toan Identity and Access Management (IAM) policy withPROJECT_IDmy-gcp-project-id.For brevity, some parts of the log entry are omitted, and some fields arehighlighted:

{protoPayload:{@type:"type.googleapis.com/google.cloud.audit.AuditLog",status:{},authenticationInfo:{principalEmail:"user@example.com"},serviceName:"appengine.googleapis.com",methodName:"SetIamPolicy",authorizationInfo:[...],serviceData:{@type:"type.googleapis.com/google.appengine.legacy.AuditData",policyDelta:{bindingDeltas:[action:"ADD",role:"roles/logging.privateLogViewer",member:"user:user@example.com"],}},request:{resource:"my-gcp-project-id",policy:{bindings:[...],}},response:{bindings:[{role:"roles/logging.privateLogViewer",members:["user:user@example.com"]}],}},insertId:"53179D9A9B559.AD6ACC7.B40604EF",resource:{type:"gae_app",labels:{project_id:"my-gcp-project-id"}},timestamp:"2019-05-27T16:24:56.135Z",severity:"NOTICE",logName:"projects/my-gcp-project-id/logs/cloudaudit.googleapis.com%2Factivity",}

Here is the query that was used to select the previous audit log entry sample.The query can be used in the Logs Explorer, Logging API, orGoogle Cloud CLI. The project identifier is in the log's name:

resource.type="gae_app"logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"

If you are looking for audit logs from a single instance of a resource type,such asgce_instance, add an instance qualifier:

resource.type="gce_instance"resource.instance_id="INSTANCE_ID"logName="projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity"

Interpreting the sample audit log entry

In the previousaudit log entry sample, theprotoPayload,insertId,resource,timestamp,severity andlogName fields shown are part of theLogEntry object. The value of theprotoPayload field is anAuditLog object. It encapsulates the audit logging data.

Looking at the audit log entry sample, you might have some questions:

  • Is this an audit log entry? It is, which you can tell in two ways:

    • TheprotoPayload.@type field istype.googleapis.com/google.cloud.audit.AuditLog.

    • ThelogName field includes the domaincloudaudit.googleapis.com.

  • What service wrote the audit log? The log was writtenby App Engine. This information is listedin theprotoPayload.serviceName field of the audit log entry.

  • What operation is being audited?SetIamPolicy, as specifiedin theprotoPayload.methodName field, is being audited. More informationabout the audited operation is in theAuditData object inprotoPayload.serviceData.

  • What resource is being audited? An application running inApp Engine, associated with a Google Cloud projectmy-gcp-project-id, is being audited. You can determine this from theresource field, which specifies the resource typegae_app and theproject identifiermy-gcp-project-id. In this example, you would finddetails on the resource type in themonitored resource type list.

For more information, see theLogEntry type, theAuditLog type, andtheIAMAuditData type.

Audit logs for long-running operations

APIs that arelong-running operations emit twoaudit logs; one when the API is called and the operation starts, andone when the operation completes.

In this case, theLogEntry object contains anoperation field.Log entries for the same operation have the same value for bothLogEntry.operation.id andLogEntry.operation.producer.The first log entry that was written hasLogEntry.operation.first=true,and the completion log entry hasLogEntry.operation.last=true.

In cases where the operation completes immediately or fails, there is only one log entrycontaining bothLogEntry.operation.first=true andLogEntry.operation.last=true.

Some services don't populate theLogEntry.operation field when theoperation fails. However, you can determine which operations are long-runningoperations by referring to theservice's audit logging documentation.

These APIs implement theOperations service.This service generally emit audit log entries when called. Depending on whichAPIs are called,protoPayload.methodName is one of the following:

  • google.longrunning.Operations.ListOperations
  • google.longrunning.Operations.GetOperation
  • google.longrunning.Operations.CancelOperation
  • google.longrunning.Operations.WaitOperation
  • google.longrunning.Operations.DeleteOperation

LogEntry.operation isn't specified in this case, as this API returns metadataabout long-running operations, but is not a long-running operation itself.

SeeGoogle Cloud services with audit logs for detailsabout which APIs are audited, as it can vary per service.

Audit logs for streaming APIs

Similar to long-running operations, streaming APIs emit two audit log entries;one when the API is first called and one when the streaming connection hasended.

In this case, theLogEntry object contains anoperation fieldand log entriesfor the same operation have the same value for bothLogEntry.operation.idandLogEntry.operation.producer.The first log written hasLogEntry.operation.first=true,and the completion log will haveLogEntry.operation.last=true.

This API may also emit continuation log entries with neitherLogEntry.operation.firstnorLogEntry.operation.last set to indicate that the stream remains open.

Service-specific audit data

Some services extend the information stored in theirAuditLog by placing a supplementary datastructure in the audit log entry'sserviceData field. The following table lists theservices that useserviceData field and provides a link to theirAuditDatatype.

ServiceService data type
App Enginetype.googleapis.com/google.appengine.v1.AuditData
App Engine (Legacy)type.googleapis.com/google.appengine.legacy.AuditData
BigQuerytype.googleapis.com/google.cloud.bigquery.logging.v1.AuditData
IAMtype.googleapis.com/google.iam.v1.logging.AuditData

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 indexedLogEntry fields.For more information about querying your logs, seeBuild queries in the Logs Explorer

The Logs Explorer lets you view filter individual log entries. If you wantto use SQL to analyze groups of log entries, then use theLog Analyticspage. For more information, see:

Most audit logs can be viewed in Cloud Logging by using theGoogle Cloud console, the Google Cloud CLI, or the Logging API.However, for audit logs related to billing, you can only use theGoogle 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:

Note: You can't view audit logs for Cloud Billing accounts in theGoogle Cloud console. You must use the API or the gcloud CLI.

  1. In the Google Cloud console, go to theLogs Explorer page:

    Go toLogs Explorer

    If you use the search bar to find this page, then select the result whose subheading isLogging.

  2. Select an existing Google Cloud project, folder, or organization.

  3. To display all audit logs, enter either of the following queriesinto the query-editor field, and then clickRun query:

    logName:"cloudaudit.googleapis.com"
    protoPayload."@type"="type.googleapis.com/google.cloud.audit.AuditLog"

  4. To display the audit logs for a specific resource and audit log type,in theQuery builder pane, do the following:

    • InResource type, select the Google Cloud resource whoseaudit logs you want to see.

    • InLog name, select the audit log type that you want to see:

      • For Admin Activity audit logs, selectactivity.
      • For Data Access audit logs, selectdata_access.
      • For System Event audit logs, selectsystem_event.
      • For Policy Denied audit logs, selectpolicy.

    • ClickRun 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.

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 aPROJECT_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.

REST

When building your queries, supply a valid resource identifier in each ofthe log names. For example, if your query includes aPROJECT_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:

  1. Go to theTry this API section in the documentation for theentries.list method.

  2. Put the following into theRequest body part of theTry thisAPI form. Clicking thisprepopulated 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"}

  3. ClickExecute.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.