Stay organized with collections
Save and categorize content based on your preferences.
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-28 UTC."],[[["\u003cp\u003eCloud Build logs can be configured for structured logging, allowing JSON-formatted build log fields to be stored in \u003ccode\u003eLogEntry\u003c/code\u003e fields.\u003c/p\u003e\n"],["\u003cp\u003eEnabling structured logging involves setting the \u003ccode\u003eenableStructuredLogging\u003c/code\u003e field to \u003ccode\u003eTRUE\u003c/code\u003e in your \u003ccode\u003eBuildOptions\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eSpecific build log fields like \u003ccode\u003emessage\u003c/code\u003e and \u003ccode\u003eseverity\u003c/code\u003e can be mapped to corresponding \u003ccode\u003eLogEntry\u003c/code\u003e fields, such as \u003ccode\u003etextPayload\u003c/code\u003e or \u003ccode\u003ejsonPayload.message\u003c/code\u003e, and \u003ccode\u003eseverity\u003c/code\u003e respectively.\u003c/p\u003e\n"],["\u003cp\u003eCertain build log fields, including \u003ccode\u003ehttpRequest\u003c/code\u003e and various \u003ccode\u003elogging.googleapis.com/\u003c/code\u003e fields, are dropped from the log entry if present, while all other fields are included in the \u003ccode\u003ejsonPayload\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# Use structured logging with build logs\n\nThis document describes how you can configure your Cloud Build\nlogs for use with [structured logging](/logging/docs/structured-logging)\nin Cloud Logging.\n\nStructured logging lets you store a JSON-formatted build log field as part of\nthe `jsonPayload` field, or as certain other fields,\nin a [`LogEntry`](/logging/docs/reference/v2/rest/v2/LogEntry).\nYou can set up your build config file so that specific build log fields\nare mapped this way when you send a build log to Logging.\n\nFor example, if your build log contains a `message`, then the message appears\nin either `textPayload` or `jsonPayload.message` in the resulting\nlog entry. If a build log field can't be mapped to a specific log entry field,\nthen the build log field is stored as part of the log entry `jsonPayload`.\n\nMap build log fields to log entry fields\n----------------------------------------\n\nTo enable field mapping on your build logs, set the\n[`BuildOptions`](/build/docs/api/reference/rest/v1/projects.builds#buildoptions)\nfield `enableStructuredLogging` to `TRUE`.\n\nThe following table shows build log fields that map to a log entry field:\n\nThe following build log fields can't be mapped and will be dropped from the\nlog entry if they appear in a build log:\n\n- `httpRequest`\n- `logging.googleapis.com/insertId`\n- `logging.googleapis.com/labels`\n- `logging.googleapis.com/operation`\n- `logging.googleapis.com/sourceLocation`\n- `logging.googleapis.com/spanId`\n- `logging.googleapis.com/trace`\n- `logging.googleapis.com/trace_sampled`\n- `time`\n- `timestamp`\n- `timestampSeconds`\n- `timestampNanos`\n\nAll other build log fields will appear as part of the log entry's `jsonPayload`."]]
