Distributed Tracing

Distributed tracing tracks a single request as it flows through multiple services in a distributed system. Each service records a span and propagates a trace context to downstream services via HTTP headers or message metadata. All spans sharing the same trace ID are assembled into a trace: a complete picture of the request’s journey.

Without distributed tracing, debugging latency or errors in a microservices system means correlating logs across dozens of services manually. Distributed tracing provides a visual timeline (waterfall diagram) showing which service took how long, where errors occurred, and how services depend on each other.

The W3C Trace Context standard, the traceparent header, defines the propagation format. OpenTelemetry is the vendor-neutral SDK and API for instrumenting PHP applications. Jaeger and Zipkin are common open-source backends; commercial alternatives include Datadog APM, New Relic, and Honeycomb.

In PHP, OpenTelemetry provides a native SDK for manual and automatic instrumentation. The ext-opentelemetry extension enables zero-code instrumentation for frameworks and HTTP clients.

<?php

use OpenTelemetry\API\Globals;

// Manual span creation
$tracer = Globals::tracerProvider()->getTracer('order-service');

$span = $tracer->spanBuilder('place-order')->startSpan();
$scope = $span->activate();

try {
    $order = $orderService->place($data);
    $span->setAttribute('order.id', $order->id);
} catch (\Throwable $e) {
    $span->recordException($e);
    $span->setStatus(\OpenTelemetry\API\Trace\StatusCode::STATUS_ERROR);
    throw $e;
} finally {
    $scope->detach();
    $span->end();
}

// The traceparent header is propagated automatically by the SDK
// when making outbound HTTP calls via PSR-18 clients with the OTel middleware.

?>

Documentation

See also OpenTelemetry PHP and W3C Trace Context.

Related : Trace, Monitoring, Microservice, Distributed Systems, Application Performance Management (APM), Telemetry

Related packages : open-telemetry/opentelemetry