ObservabilitySpan

Pair framework: ObservabilitySpan

Pair\Core\ObservabilitySpan holds timing and safe context for an instrumented operation. Create spans through Observability, which owns enablement, sampling, attribute sanitization, retention, and adapter delivery.

Manual timing

use Pair\Core\Observability;

$span = Observability::start('report.build', ['report' => 'monthly']);

try {
	$report = buildReport();
	Observability::finish($span, ['rows' => $report->rowCount], 'ok');
} catch (Throwable $exception) {
	Observability::finish($span, ['exception' => $exception::class], 'error');
	throw $exception;
}

For a single callback, prefer Observability::trace(), which finishes the span and rethrows exceptions automatically.

Accessors

Method	Result
name(): string	Operation name.
attributes(): array	Context attached to the span.
correlationId(): string	Request correlation ID.
startedAt(): float	Start timestamp in seconds.
endedAt(): ?float	End timestamp, or null while open.
durationMs(): float	Non-negative elapsed milliseconds, using the current time while open.
status(): ?string	Completion status, or null while open.
isFinished(): bool	Whether an end timestamp was captured.
recordable(): bool	Whether the span was created for recording.
toArray(): array	Name, correlation ID, status, timestamps, duration, and attributes.

finish(array $attributes = [], string $status = 'ok'): self

Finishes the timing record and merges attributes. Repeated calls preserve the first end timestamp but can change status and attributes.

Direct finish() calls neither sanitize new attributes nor forward the span to an adapter. Application code should use Observability::finish() instead and finish each span once. Disabled or unsampled spans can be non-recordable; receiving a span object alone does not prove that telemetry was retained or exported.

See also: Observability, ObservabilityAdapter, ObservabilityEvent, OpenTelemetryHttpExporter.