Audit Log Datatypes

Audit log entries have the following structure:

  • An object of type LogEntry that contains the entire log entry.
  • An object of type AuditLog that is held in the protoPayload field of the LogEntry object.
  • An optional, service-specific object that is held in the serviceData field of the AuditLog object. See Service-specific audit data for a list of services that use this extension.

Knowing what information is held in these objects will help you understand your audit logs and will help you retrieve audit log entries using the Logs Viewer and the Stackdriver Logging API.

Sample audit log entry

This section uses a sample audit log entry to explain how to find the most important information in it.

The following sample is an Admin Access audit log entry written by the Cloud Resource Manager to record a change to an IAM policy in a GCP project named my-gcp-project-id. For brevity, some parts of the log entry are omitted, and some important fields are highlighted:

    {
      protoPayload: {
        @type: "type.googleapis.com/google.cloud.audit.AuditLog",
        status: {},
        authenticationInfo: {
          principalEmail: "user@example.com"
        },
        serviceName: "cloudresourcemanager.googleapis.com",
        methodName: "SetIamPolicy",
        authorizationInfo: [...],
        serviceData: {
          @type: "type.googleapis.com/google.iam.v1.logging.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: "project",
        labels: { project_id: "my-gcp-project-id" }
      },
      timestamp: "2016-04-27T16:24:56.135Z",
      severity: "NOTICE",
      logName: "projects/my-gcp-project-id/logs/cloudaudit.googleapis.com%2Factivity",
    }

Decoding the entry

  • Is this an audit log entry? It is, which you can tell in two ways. The logName field includes the domain cloudaudit.googleapis.com, and the protoPayload.@type field is type.googleapis.com/google.cloud.audit.AuditLog.

  • What resource is being audited? A GCP project,my-gcp-project-id, is being audited. The resource field specifies the resource type project and the project identifier my-gcp-project-id. Find project in the monitored resource type list and you see that this is a "Google project."

  • What service wrote the audit log? The log was written by Cloud Resource Manager. This is listed in the protoPayload.serviceName field of the audit log entry. Sometimes the resource type will also suggest the service: audit logs for resource type gce_instance are written by Google Compute Engine, for example.

  • What operation is being audited? A call to SetIamPolicy, as specified in the protoPayload.methodName field. More information about the audited operation is in the AuditData object in protoPayload.serviceData.

For more information, see the LogEntry type, the AuditLog type, and the IAM AuditData type.

Retrieving audit logs

Using the Logs Viewer basic interface

To see the sample audit log entry and ones like it in the Logs Viewer's basic viewing interface, do the following:

  • In the first drop-down menu, select the resource whose audit logs you wish to see. For the preceding sample audit log, the resource is Google project. You can select a specific project or "all projects."

  • In the second menu, select the log name you want to see: activity for Admin Activity audit logs and data_access for Data Access audit logs (if the logs are available).

The audit logs appear in the Logs Viewer.

Using the Logs Viewer advanced filter interface

In the Logs Viewer's advanced filter interface, use a filter to specify the resource type and log name. For the previous sample, here is two-line advanced logs filter. This works because the project identifier is in the log name, and the filter is fast because the logName field is indexed:

resource.type = "project"
logName = "projects/my-gcp-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, you should add an instance qualifier. Again, this filter uses indexed fields:

resource.type = "gce_instance"
resource.instance_id = "12345678901234567890"
logName = "projects/my-gcp-project-id/logs/cloudaudit.googleapis.com%2Factivity"

The fastest way to retrieve all audit logs in your project, both Admin Activity and Data Access, is to use the following filter:

logName = ("projects/my-gcp-project-id/logs/cloudaudit.googleapis.com%2Factivity" OR
    "projects/my-gcp-project-id/logs/cloudaudit.googleapis.com%2Fdata_access")

For more details about filters, see Logging Filters.

Using the API

To look at your audit log entries using the Stackdriver Logging API, see the Try It! section in the documentation for the entries:list method. Put the following into the Request body part of the Try It! form:

{
 "projectIds": [ "[PROJECT_ID]" ],
 "pageSize": 5,
 "filter": "logName : \"/logs/cloudaudit.googleapis.com\""
}

Click Authorize and Execute. For more details about filters, see Logging Filters.

Large or long-running audit log entries

A single audited operation can be split across multiple log entries if the operation runs asynchronously or if it generates a large AuditLog record. When there is more than one log entry for the same operation, the LogEntry object will contain an operation field and the entries for the same operation will have the same value for LogEntry.operation.id and LogEntry.operation.producer.

In the preceding screenshot, the operation field is not present, meaning that all the audit information is in this single log entry.

Service-specific audit data

Some services extend the information stored in their AuditLog by placing a supplementary data structure in the audit log's serviceData field. The following table lists the services that use serviceData and provides a link to their AuditData type

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
Cloud IAM type.googleapis.com/google.iam.v1.logging.AuditData

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Stackdriver Logging