Structured logging

This document discusses the concept of structured logging and the methods for adding structure to log entry payload fields. When the log payload is formatted as a JSON object and that object is stored in the jsonPayload field, the log entry is called a structured log. For these logs, you can construct queries that search specific JSON paths and you can index specific fields in the log payload. In contrast, when the log payload is formatted as a string and stored in the textPayload field, the log entry is unstructured. You can search the text field, but you can't index its content.

To create structured log entries, do any of the following:

  • Call the entries.write API method and supply a fully formatted LogEntry.
  • Use the gcloud logging write command.
  • Use a Cloud Logging client library which writes structured logs.

For more information about these approaches, see the following sections.

Write logs by using client libraries or the API

You can write log data by using the Cloud Logging client libraries, which call the Cloud Logging API, or by directly calling the Cloud Logging API. Client libraries can simplify population of the special JSON fields by automatically capturing some information and by providing interfaces to appropriately populate the fields. However, for full control over the structure of your payloads, directly call the Cloud Logging API and pass the full LogEntry structure to the Cloud Logging API.

For more information, see the entries.write reference.

For code examples, see Writing structured logs.

Write logs by using the gcloud CLI

You can write log data by using the gcloud CLI. The interface supports unstructured logs and structured logs. When you want to write a structured log, provide the command a serialized JSON object.

For a quickstart, see Write and query log entries with the Google Cloud CLI.

For code examples, see the gcloud logging write reference.

What's next