Use structured logging with build logs

This document describes how you can configure your Cloud Build logs for use with structured logging in Cloud Logging.

Structured logging lets you store a JSON-formatted build log field as part of the jsonPayload field, or as certain other fields, in a LogEntry. You can set up your build config file so that specific build log fields are mapped this way when you send a build log to Logging.

For example, if your build log contains a message, then the message appears in either textPayload or jsonPayload.message in the resulting log entry. If a build log field can't be mapped to a specific log entry field, then the build log field is stored as part of the log entry jsonPayload.

Map build log fields to log entry fields

To enable field mapping on your build logs, set the BuildOptions field enableStructuredLogging to TRUE.

The following table shows build log fields that map to a log entry field:

BuildLog Field (JSON) LogEntry Field Description Notes
message textPayload or jsonPayload.message Lets you set the log message

Must be a string.

If the build log contains only mappable fields, then the message appears in textPayload. Otherwise, the message appears in jsonPayload.message.

If the build log contains multiple steps, then the step identifier appears at the beginning of the message.
severity severity Lets you set the log severity. Must be an enum of LogSeverity.

The following build log fields can't be mapped and will be dropped from the log entry if they appear in a build log:

  • httpRequest
  • logging.googleapis.com/insertId
  • logging.googleapis.com/labels
  • logging.googleapis.com/operation
  • logging.googleapis.com/sourceLocation
  • logging.googleapis.com/spanId
  • logging.googleapis.com/trace
  • logging.googleapis.com/trace_sampled
  • time
  • timestamp
  • timestampSeconds
  • timestampNanos

All other build log fields will appear as part of the log entry's jsonPayload.