Integrating with Cloud Logging

This document describes how you can associate a trace with a Cloud Logging LogEntry.

Associate a log entry with a trace or span

If you use the Cloud Logging API to write log data, or if you write structured log data, then you can associate a log entry with a trace or with a span. The log entry can also record whether the trace was sampled. For information about how the Ops Agent converts structured log data to fields in a LogEntry, see Special fields in structured payloads.

To associate a log entry with a trace by setting the trace field in the LogEntry object. The trace field must be set to a string with the following format:

   projects/PROJECT_ID/traces/TRACE_ID

where PROJECT_ID is your Google Cloud project ID and TRACE_ID is the trace identifier

To associate a log entry with a span when using the Cloud Logging API, set the spanId field in the LogEntry object to the 16-character hexadecimal encoding of the span's ID. For example, to associate a log entry with a span that has an ID of 74, set the span ID to 000000000000004a.

To indicate that you are using trace sampling and that the trace was sampled for storage when the log entry was written, set the traceSampled field in the LogEntry object. When you use trace sampling, it's possible that a log entry is created when the trace itself isn't captured.

Viewing logs

You can view the log entry for a trace alongside the waterfall graph or in the Logs Explorer. When you use the Logs Explorer, it's automatically restricted to the timestamp range of the trace. If there are no log entries to display, the Logs Explorer displays the message No entries found matching current filter.

From the Trace details pane, to view the log entry for the trace, do one of the following:

  • To display the trace log entries alongside the waterfall graph, go to the waterfall graph and click Show logs. When Show logs isn't displayed, no log entries are available.

  • To view the log entry in the Logs Explorer, click View next to the label Log in the Details section. Note that when you have a Cloud Load Balancing trace, click View next to the label VM Log.

For more information about viewing log entries in Cloud Logging, see Using the Logs Explorer.

Log viewing permissions

To view any log entries, you must have the logging.logEntries.list permission in your project. This permission is provided by the Logs Viewer and Project Viewer Identity and Access Management (IAM) roles.

To view VM instance logs, you must have the compute.instances.get permission in your project. This permission is provided by the Compute Engine Network Viewer and Project Viewer IAM roles.