Tracing¶

Conflux propagates trace context through all execution boundaries using the W3C Trace Context standard and the OpenTelemetry PHP SDK.

traceparent format¶

The traceparent header uses the following format:

00-{trace-id}-{parent-id}-{flags}

Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

HTTP requests¶

Incoming: SetSpanContext middleware runs on every request. If a traceparent header is present, a child span is created from the upstream context. If absent, a new root span with a fresh trace ID is created.

Response headers set:

Queue jobs¶

When a job is dispatched, _traceparent is injected into the job payload from the active span context. When the worker picks up the job, the trace context is restored and a child span is created.

Payload key: _traceparent (W3C traceparent string)

If no span is active at dispatch time (e.g. dispatched from a CLI command with no active span), _traceparent is omitted and the job starts a fresh trace.

CLI commands¶

When an Artisan command starts, a root span with a fresh trace ID is created. This covers both scheduled commands and manually invoked ones.

Outgoing HTTP requests¶

All outgoing HTTP requests made via Laravel's Http facade automatically receive a traceparent header injected from the active span context. This propagates the trace into downstream services.

Log context¶

Every log entry written during a traced request, job, or command includes:

Resource attributes¶

Every exported span carries a service.name resource attribute. Per the OTel spec, an SDK falls back to unknown_service:{process.executable.name} (e.g. unknown_service:php) if this isn't set explicitly. Conflux sets it via config/telemetry.php's service_name key (env: OTEL_SERVICE_NAME, default conflux).

Implementation¶