Spans & Traces

TL;DR

Explanation

Trace: collection of spans sharing a trace ID. Root span: first span in a request. Child spans: nested operations (DB query, HTTP call, cache lookup). Span attributes: key-value data (db.statement, http.url, user.id). Span events: timestamped events within a span (cache.miss). Span status: OK, ERROR, UNSET. Span kind: SERVER, CLIENT, PRODUCER, CONSUMER, INTERNAL. W3C Trace Context: traceparent header carries (version, trace-id, parent-id, flags). Sampling: recording every span is expensive — sample 1-10% in production or use head/tail-based sampling.

Common Misconception

Why It Matters

Common Mistakes

• One span per request — no internal visibility.
• Span per line of code — noise and cost.
• Missing DB spans — usually the most important.
• Not setting span status=ERROR on exception — traces look successful.

Code Examples

// Single span for entire request — no internal visibility:
$span = $tracer->spanBuilder('handleRequest')->startSpan();
try { handleRequest(); } finally { $span->end(); }

// Nested spans:
$requestSpan = $tracer->spanBuilder('POST /orders')->setSpanKind(SpanKind::SERVER)->startSpan();
$dbSpan = $tracer->spanBuilder('SELECT orders')->setSpanKind(SpanKind::CLIENT)->startSpan();
$dbSpan->setAttribute('db.statement', 'SELECT * FROM orders WHERE id = ?');
try { $result = $pdo->query(...); }
catch (Exception $e) { $dbSpan->setStatus(StatusCode::ERROR, $e->getMessage()); throw $e; }
finally { $dbSpan->end(); }

References

• ↗ https://opentelemetry.io/docs/concepts/signals/traces/#spans

Tags

Related Terms