liveBook · Manning

Trace context

As explained in Designing AI Systems

Distributed trace context is propagation metadata that associates work performed across services with the same distributed trace.

Trace context is propagation metadata that links work across service boundaries to one distributed trace. Without it, a slow request remains a collection of unrelated service events; with it, operators can follow the request, locate the bottleneck, and connect spans to detailed logs. section 7.4.3 section 7.8

A propagated context carries the identifiers needed to assemble a trace:

  • trace_id identifies the complete request and is shared by every participating span. section 7.4.3
  • span_id identifies the current unit of work, while parent_span_id preserves nesting between service operations. section 7.4.3
  • gRPC metadata headers such as x-trace-id, x-span-id, and x-workflow-id carry context between services. section 7.4.3
  • The API Gateway seeds the trace; each service creates child spans, and the Observability Service assembles the final trace afterward. section 7.8

Following a slow request

A patient-intake request completes in 2,370 ms. Its propagated trace context connects retrieval, validation, persistence, and a 1,650 ms model-generation span. An operator starts with the trace waterfall, follows the same trace_id into service logs, and checks metrics to determine whether the delay is systemic.

Listing 7.5 Span, Generation, and Trace Protocol Buffer definitions
message Span {
  string trace_id = 1;                          #A
  string span_id = 2;
  string parent_span_id = 3;
  string service = 4;
  string operation = 5;                         #B
  google.protobuf.Timestamp start_time = 6;
  google.protobuf.Timestamp end_time = 7;
  SpanStatus status = 8;
  string error_message = 9;
  map<string, string> attributes = 10;
  map<string, double> numeric_attributes = 11;
  repeated SpanEvent events = 12;
}
 
message Generation {
  Span span = 1;                                #C
  string model = 2;
  string provider = 3;
  string requested_model = 4;
  int32 prompt_tokens = 5;
  int32 completion_tokens = 6;
  double cost_usd = 7;
  bool cache_hit = 8;
  bool fallback_used = 9;
  double time_to_first_token_ms = 10;
}
 
message Trace {
  string trace_id = 1;
  string session_id = 2;                        #D
  repeated Span spans = 3;
  repeated Generation generations = 4;
  string input = 5;
  string output = 6;
  double total_duration_ms = 7;
  double total_cost_usd = 8;
  int32 total_tokens = 9;
  repeated Score scores = 10;                   #E
  repeated string tags = 11;
}

Inspect the Span, Generation, and Trace Protocol Buffer definitions to see how trace_id, span_id, parent_span_id, and related metadata form the tracing contract. section 7.4.3

How Designing AI Systems covers it

How deep it goes
Defines identifiers, parent-child relationships, transport headers, and assembly flow, but does not detail propagation code.
Examples
Uses a patient-intake waterfall, propagation headers, and trace-to-logs-to-metrics debugging workflow.
What it assumes
Assumes service boundaries and gRPC calls, while defining trace and span relationships explicitly.
What you can do after
Diagnose/debug with it: follow one request across services and correlate bottlenecks with logs and metrics.
How it connects
Ties distributed tracing to spans, logs, metrics, gRPC metadata, and the Observability Service.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Systems. The section links point to the parts of the book it draws on.