Traces and spans

In Cloud Trace, traces and spans form the data model used to track the path and latency of requests through your distributed applications. A trace captures how a request runs end-to-end across your services. A trace is composed of spans, which record the individual operations, function calls, and RPCs that occur during that request.

Trace data model

A trace consists of the following:

  • Trace ID: The unique identifier of the end-to-end operation. The trace ID is propagated in the request context across service boundaries.

  • Span collection: A set of spans that share the same trace ID. These spans form a tree or a directed acyclic graph that represents the call hierarchy of a request.

Cloud Trace uses the trace ID to identify which spans in its repository are associated with the same trace.

Span data model

A span represents a single operation that occurred within a specific time period. Each span contains fields that provide information about the span and the status of the operation:

  • Identifiers include the following fields:

    • Trace ID: The unique identifier of the overall request or trace to which the span belongs.
    • Span ID: The unique identifier for the span. If an operation is invoked multiple times within a single trace, each invocation generates a separate span with the same name but a unique span ID.
    • Parent span ID: Identifies the parent operation that invoked this span. The "root" span has the parent span ID set to null.
    • Name: The name of the operation that was performed.
    • Kind: The span kind provides information to tracing tools, such as the Trace Explorer, about how spans are related to each other. For more information, see OpenTelemetry SpanKind.

  • Execution information is provided in the following fields:

    • Status: Records the completion status of the operation. The value of this field is Unset (default), Error, or Ok. The default value doesn't indicate an error.
    • Start time: The start time of the operation.
    • End time: The end time of the operation.

Spans can contain other fields, such as events, attributes, and links:

  • Events record timestamped structured messages within a span.
  • Attributes store additional information about an operation by using key-value pairs. When writing attributes, we recommend that you follow the OpenTelemetry Semantic Conventions where possible.
  • Links let you relate one span to another.

For more information, see OpenTelemetry: Spans.

Resources

OpenTelemetry resources:

What's next