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 the protoPayload field. In audit logentries, the log entry's protoPayload 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 is
compute.googleapis.com,Cloud SQL iscloudsql.googleapis.com, and so forth. This informationis listed in theprotoPayload.serviceNamefield 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 the
protoPayloadtype. The payload of eachaudit log entry is an object of typeAuditLog,which defines a set of fields specific to Cloud Audit Logs, such asserviceNameandauthenticationInfo. 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 theolderserviceDatafield to list service-specific information. For a listof services that use theserviceDatafield, seeService-specific audit data.A log name: Audit log entries belong to logs within projects, folders, andorganizations. The log names are listed below:
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
Within a project, folder, or organization, these log names are typically abbreviated activity, data_access, system_event, and policy.
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 with PROJECT_ID my-gcp-project-id. Forbrevity, 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 audit log entry sample above.It can be used in the Logs Explorer, Logging API, or Google Cloud CLI.The project identifier is in the log's name, and the query is fast because thelogName field is indexed:
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 as gce_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 audit log entry sample above, the protoPayload, insertId,resource, timestamp, severity and logName fields shown are part of the LogEntry object. The value of the protoPayload field is anAuditLog object. It encapsulates the audit logging data.
Looking at the audit log entry sample above, you might have some questions:
Is this an audit log entry? It is, which you can tell in two ways:
The
protoPayload.@typefield istype.googleapis.com/google.cloud.audit.AuditLog.The
logNamefield includes the domaincloudaudit.googleapis.com.
What service wrote the audit log? The log was writtenby App Engine. This information is listedin the
protoPayload.serviceNamefield of the audit log entry.What operation is being audited?
SetIamPolicy, as specifiedin theprotoPayload.methodNamefield, is being audited. More informationabout the audited operation is in theAuditDataobject inprotoPayload.serviceData.What resource is being audited? An application running inApp Engine, associated with a Google Cloud project
my-gcp-project-id, is being audited. You can determine this from theresourcefield, which specifies the resource typegae_appand theproject identifiermy-gcp-project-id. In this example, you would finddetails on the resource type in themonitored resource type list.
For more information, see the LogEntry type, theAuditLog type, andthe IAM AuditData type.
Audit logs for long-running operations
APIs that are long-running operations emit twoaudit logs; one when the API is called and the operation starts, andone when the operation completes.
In this case, the LogEntry object contains an operation field. Log entriesfor the same operation have the same value for both LogEntry.operation.idand LogEntry.operation.producer. The first log written has LogEntry.operation.first=true,and the completion log has LogEntry.operation.last=true.
In cases where the operation completes immediately, there is only one logcontaining both LogEntry.operation.first=true and LogEntry.operation.last=true.
These APIs implement the Operationsservice. This service generally emit audit logs when called. Depending on which APIs are called,protoPayload.methodName is one of the following:
google.longrunning.Operations.ListOperationsgoogle.longrunning.Operations.GetOperationgoogle.longrunning.Operations.CancelOperationgoogle.longrunning.Operations.WaitOperationgoogle.longrunning.Operations.DeleteOperation
LogEntry.operation isn't specified in this case, as this API returnsmetadata about long-running operations, but is not a long-running operation itself.
See Google 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 auditlogs; one when the API is first called and one when the streaming connection has ended.
In this case, the LogEntry object contains an operation field and log entriesfor the same operation have the same value for both LogEntry.operation.idand LogEntry.operation.producer. The first log written has LogEntry.operation.first=true,and the completion log will have LogEntry.operation.last=true.
This API may also emit continuation logs with neither LogEntry.operation.first norLogEntry.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's serviceData field. The following table lists theservices that use serviceData field and provides a link to their AuditDatatype.
| Service | Service data type |
|---|---|
| App Engine | type.googleapis.com/google.appengine.v1.AuditData |
| App Engine (legacy) | type.googleapis.com/google.appengine.legacy.AuditData |
| BigQuery | type.googleapis.com/google.cloud.bigquery.logging.v1.AuditData |
| IAM | type.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 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.
