Browse documentation

#Contracts

Flow Telemetry is a contract library. Its interfaces let you extend and change each part of the telemetry pipeline. This page lists all contracts (interfaces) and their available implementations.

#Core Contracts

#Transport

Interface: Flow\Bridge\Telemetry\OTLP\Transport\Transport

Sends telemetry to an OTLP backend. The signal type is Signals::$type:

public function send(Signals $signal) : void;
public function shutdown() : void;

#Exporter

Interface: Flow\Telemetry\Exporter\Exporter

Exports telemetry to external observability backends. One exporter handles all three signals with a match on Signals::$type.

public function export(Signals $signal) : bool;
public function shutdown() : void;

#Signals

Flow\Telemetry\Signal\Signals carries the payload of one signal type across Exporter and Transport boundaries:

• Signals::logs(array<LogEntry>), read with allLogs()
• Signals::metrics(array<Metric>), read with allMetrics()
• Signals::traces(array<Span>), read with allSpans()

$type is a SignalType: LOGS, METRICS or TRACES.

#ContextStorage

Interface: Flow\Telemetry\Context\ContextStorage

Stores and gets the telemetry context (active span, baggage) in a request lifecycle. attach() returns a Scope. You must detach the scopes in reverse order. A span is the parent of later spans only while its scope is attached. For more information, read Tracer::activate().

#Tracer Contracts

#SpanProcessor

Interface: Flow\Telemetry\Tracer\SpanProcessor

Receives span lifecycle events (onStart, onEnd) and decides how spans are buffered and exported. The processor is between the Tracer and the unified Exporter. The exporter() accessor returns the unified Exporter.

#Sampler

Interface: Flow\Telemetry\Tracer\Sampler\Sampler

Makes sampling decisions for traces. It uses configurable rules to decide which spans are recorded and exported.

#SpanEvent

Interface: Flow\Telemetry\Tracer\SpanEvent

Represents timestamped events in the lifetime of a span, for example exceptions or state changes.

#Meter Contracts

#MetricProcessor

Interface: Flow\Telemetry\Meter\MetricProcessor

Processes metric measurements from instruments. It decides how metrics are aggregated and at what time they are exported. The exporter() accessor returns the unified Exporter.

#Instrument

Interface: Flow\Telemetry\Meter\Instrument\Instrument

Base interface for metric instruments. Instruments are the API that records measurements.

#Logger Contracts

#LogProcessor

Interface: Flow\Telemetry\Logger\LogProcessor

Processes log records from loggers. It decides how logs are buffered and at what time they are exported. A LogSink (a marker interface that extends LogProcessor) marks the terminal/leaf processors. PipelineLogProcessor runs an ordered chain of LogMiddleware and sends the remaining entries to one LogSink.

#LogMiddleware

Interface: Flow\Telemetry\Logger\LogMiddleware

A chainable step in a PipelineLogProcessor. process(LogEntry): ?LogEntry returns the entry for the next step (possibly enriched), or null to drop it. A middleware has no state. Flush and shutdown belong to the LogSink of the pipeline.

#Propagation Contracts

#TextMapPropagator

Interface: Flow\Telemetry\Propagation\TextMapPropagator

Extracts and injects trace context across process boundaries with text-based carriers (HTTP headers, message metadata).

#BaggagePropagator

Interface: Flow\Telemetry\Propagation\BaggagePropagator

Propagates application-specific key-value pairs (baggage) across process boundaries, together with the trace context.

#Carrier

Interface: Flow\Telemetry\Propagation\Carrier

Abstraction over the transport mechanism for context propagation. It has get/set operations for header-like values.

#Implementing Custom Contracts

You can extend all contracts. To implement a custom exporter:

<?php

use Flow\Telemetry\Exporter\Exporter;
use Flow\Telemetry\Signal\{Signals, SignalType};

use function Flow\Telemetry\DSL\pass_through_span_processor;

final class MyCustomExporter implements Exporter
{
    public function export(Signals $signal) : bool
    {
        match ($signal->type) {
            SignalType::TRACES => $this->writeSpans($signal->allSpans()),
            SignalType::METRICS => $this->writeMetrics($signal->allMetrics()),
            SignalType::LOGS => $this->writeLogs($signal->allLogs()),
        };

        return true;
    }

    public function shutdown() : void
    {
    }

    // ... per-signal helpers
}

$processor = pass_through_span_processor(new MyCustomExporter());

Found a typo or an outdated section? Edit this page on GitHub ↗