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
