Traces and spans

This document provides an introduction to traces and spans. A trace represents a single end-to-end operation. Traces are composed of spans, which are records for a single function or operation.

Trace data model

A trace has the following properties:

  • Trace ID: The unique identifier of the end-to-end operation. The trace ID must be propagated as context as part of the end-to-end operation.

  • A collection of spans that share the same value for the trace ID.

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

Span data model

A span corresponds to an operation which took place over some finite but non-zero time period. The following lists some essential properties stored by each span:

  • Trace ID: The identifier of the end-to-end operation in which this particular overall operation took place.
  • Span ID: The unique identifier for the span. If the same operation is invoked in the fulfillment of a single overall operation multiple times, then a trace might contain multiple spans with the same name. However, each span has a distinct span ID.
  • Parent span ID: Identifies the operation which invoked this span. The "root" span has the parent span ID set to null.
  • Name: The name of the operation that was performed.
  • Start time: The start time of the operation.
  • End time: The end time of the operation.

Spans might also contain attributes, which store additional information about an operation by using key-value pairs. Cloud Trace recommends that you use OpenTelemetry Semantic Conventions where possible.

Resources

OpenTelemetry resources:

What's next