Flow PHP

Tracer

FinalYes

Creates and manages spans within a trace.

Tracer is the primary API for distributed tracing. It creates spans, manages parent-child relationships through the shared Context (the active span lives in the Context and the parent is derived from it), and delegates span lifecycle events to a SpanProcessor.

Example usage - a leaf span, which never needs to become the active span:

$span = $tracer->span('process-order');
try {
    // do work
    $span->setStatus(SpanStatus::ok());
} catch (\Throwable $e) {
    $span->recordException($e)->setStatus(SpanStatus::error($e->getMessage()));
    throw $e;
} finally {
    $tracer->complete($span);
}

When spans created inside must nest under this one, activate it and detach the scope before completing:

$span = $tracer->span('process-order');
$scope = $tracer->activate($span);
try {
    // spans started here become children of $span
} finally {
    $scope->detach();
    $tracer->complete($span);
}

Or use the trace() helper:

$result = $tracer->trace('process-order', function() {
    // do work
    return $result;
});
Tags
phpstan-import-type

TAttributeValueMap from Attributes

Methods

__construct()  : mixed
activate()  : Scope
Make a span the active span in the current Context.
activeSpan()  : SpanContext|null
Get the currently active span context from the shared Context, or null if none.
complete()  : void
Complete a span and pass it to the processor.
context()  : Context
Get the tracer's context.
flush()  : bool
Flush all pending spans to the exporter.
instrumentationScope()  : InstrumentationScope
Get the instrumentation scope.
name()  : string
Get the tracer name.
processor()  : SpanProcessor
Get the processor used by this tracer.
span()  : Span
Start a new span, without making it the active span.
trace()  : T
Execute a callable within a span, automatically completing it.
version()  : string
Get the tracer version.
withInstrumentationScope()  : self
Change the instrumentation scope for this tracer.

Methods

__construct()

public __construct(Resource $resource, InstrumentationScope $scope, SpanProcessor $processor, ClockInterface $clock, ContextStorage $contextStorage[, Sampler|null $sampler = null ][, SpanLimits $limits = new SpanLimits() ][, ErrorHandler $errorHandler = new ErrorLogHandler() ][, Attributes $signalAttributes = new Attributes() ]) : mixed
Parameters
$resource : Resource
$scope : InstrumentationScope
$processor : SpanProcessor
$clock : ClockInterface
$contextStorage : ContextStorage
$sampler : Sampler|null = null
$limits : SpanLimits = new SpanLimits()
$errorHandler : ErrorHandler = new ErrorLogHandler()
$signalAttributes : Attributes = new Attributes()

activate()

Make a span the active span in the current Context.

public activate(Span $span) : Scope

The returned Scope must be detached by the caller, in LIFO order, before the span is completed.

Parameters
$span : Span
Return values
Scope

activeSpan()

Get the currently active span context from the shared Context, or null if none.

public activeSpan() : SpanContext|null
Return values
SpanContext|null

complete()

Complete a span and pass it to the processor.

public complete(Span $span) : void

This ends the span (if not already ended) and notifies the processor. Detaching the Context scope is the responsibility of whoever called activate().

Parameters
$span : Span

flush()

Flush all pending spans to the exporter.

public flush() : bool
Return values
bool

name()

Get the tracer name.

public name() : string
Return values
string

span()

Start a new span, without making it the active span.

public span(string $name[, SpanKind $kind = SpanKind::INTERNAL ][, TAttributeValueMap|Attributes $attributes = [] ][, array<string|int, SpanLink> $links = [] ][, null|false|Context $parent = null ]) : Span

OTEL trace API: "Span creation MUST NOT set the newly created Span as the active Span in the current Context by default, but this functionality MAY be offered additionally as a separate operation." That separate operation is activate().

Parameters
$name : string

The span name

$kind : SpanKind = SpanKind::INTERNAL

The span kind

$attributes : TAttributeValueMap|Attributes = []

Initial attributes

$links : array<string|int, SpanLink> = []

Links to other spans

$parent : null|false|Context = null

Explicit parent control:

  • null (default): automatic detection from the current Context's active span
  • Context: use that Context's active span as parent
  • false: create root span (no parent)
Return values
Span

trace()

Execute a callable within a span, automatically completing it.

public trace(string $name, callable(): T $callback[, SpanKind $kind = SpanKind::INTERNAL ][, null|false|Context $parent = null ]) : T

The span is automatically completed after the callback finishes, regardless of whether it throws an exception. If an exception is thrown, it is recorded as an event and the status is set to error.

Parameters
$name : string

The span name

$callback : callable(): T

The callable to execute

$kind : SpanKind = SpanKind::INTERNAL

The span kind

$parent : null|false|Context = null

Explicit parent control (see span() for details)

Tags
template
throws
Throwable

Rethrows any exception from the callback

Return values
T —

The callback result

version()

Get the tracer version.

public version() : string
Return values
string

withInstrumentationScope()

Change the instrumentation scope for this tracer.

public withInstrumentationScope(InstrumentationScope $scope) : self

This mutates the tracer instance and returns it for method chaining.

Parameters
$scope : InstrumentationScope
Return values
self
On this page

Search results