This document describes how you can link a log entry with a trace. You performthe linkage by setting a field in log entry.By using the trace fields in theLogEntrystructure—spanId,trace, andtraceSampled— you cancorrelate logs and traces to enable better distributed troubleshooting.

Manually associate a log entry with a trace or span

If you use the Cloud Logging API to write log data, or if you writestructured log data,then you can associate a log entry with a trace or with a span. The log entrycan also record whether the trace was sampled. For information about how theOps Agent converts structured log data tofields in aLogEntry, seeSpecial fields in structured payloads.

To associate a log entry with a trace, set thetrace fieldin theLogEntry object:

• Preferred format:TRACE_ID
• Legacy format:projects/PROJECT_ID/traces/TRACE_ID

In the previous expressions,PROJECT_ID is your Google Cloud project ID andTRACE_ID is the trace identifier

To associate a log entry with a span when using the Cloud Logging API,set thespanId field in theLogEntry objectto the 16-character hexadecimal encoding of the span's ID.For example, to associate a log entry with a span that has an ID of74,set the span ID to000000000000004a.

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

Automatically associate a log entry with a trace or span

When usingCloud Logging clientlibraries, in some cases the trace fieldsin a log entry can be set automatically. Values setmanuallytake precedence over values set automatically.

For example, if you are usingOpenTelemetry and arelogging from an active OpenTelemetry span, then the trace fields in the log entryare populated from theOpenTelemetryContext.

Alternatively, in some cases, when an HTTP request is present,the trace fields can be set from theW3Ctraceparent field or theX-Cloud-Trace-Context value in the HTTP request.

For more information about automatic population of trace fields in logentries, see the following language-specific client-library documentation:

• Go
• Java
• NodeJS
• Python

Viewing logs

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

From theTrace 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 tothe waterfall graph and clickShow logs.WhenShow logs isn't displayed, no log entries are available.

• To view the log entry in the Logs Explorer, clickView next to thelabelLog in theDetails section.Note that when you have a Cloud Load Balancing trace, clickView nextto the labelVM Log.

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

Log viewing permissions

To view any log entries, you must have thelogging.logEntries.list permissionin your project. This permission is provided by theLogs Viewer andProject Viewer Identity and Access Management (IAM) roles.

To view VM instance logs, you must have thecompute.instances.get permissionin your project. This permission is provided by theCompute Engine NetworkViewer andProject Viewer IAM roles.