This document describes how you can link a log entry with a trace. You perform
the linkage by setting a field in log entry.
By using the trace fields in the LogEntry
structure— spanId
, trace
, and traceSampled
— you can
correlate 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 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.
Automatically associate a log entry with a trace or span
When using Cloud Logging client libraries , in some cases the trace fields in a log entry can be set automatically. Values set manually take precedence over values set automatically.
For example, if you are using OpenTelemetry and are logging from an active OpenTelemetry span, then the trace fields in the log entry are populated from the OpenTelemetry Context .
Alternatively, in some cases, when an HTTP request is present,
the trace fields can be set from the W3C traceparent
field or the X-Cloud-Trace-Context
value in the HTTP request.
For more information about automatic population of trace fields in log entries, see the following language-specific client-library documentation:
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 detailspane, 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 logsisn't displayed, no log entries are available.
-
To view the log entry in the Logs Explorer, click Viewnext to the label Login the Detailssection. Note that when you have a Cloud Load Balancing trace, click Viewnext 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 Viewerand Project ViewerIdentity 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
Viewerand Project ViewerIAM roles.
