Browse documentation

#Contracts

Flow Telemetry is designed as a contract library - it defines interfaces that allow you to extend and customize every part of the telemetry pipeline. This page documents all contracts (interfaces) and their available implementations.

#Core Contracts

#Transport

Interface: Flow\Telemetry\Transport\Transport

Sends serialized telemetry data to backends over the network. The signal type is inferred from the batch payload type (LogsBatch, MetricsBatch, TracesBatch). Single method:

public function send(LogsBatch|MetricsBatch|TracesBatch $batch) : void;
public function shutdown() : void;

#Exporter

Interface: Flow\Telemetry\Exporter\Exporter

Exports telemetry batches to external observability backends. A single exporter handles all three signals via match(true) instanceof dispatch on LogsBatch | MetricsBatch | TracesBatch.

public function export(LogsBatch|MetricsBatch|TracesBatch $batch) : bool;

/** @return array<Transport> */
public function transports() : array;

#Batch value objects

Three small immutable value objects in Flow\Telemetry\Batch carry the payload across Transport / Exporter boundaries:

• LogsBatch(array<LogEntry> $entries)
• MetricsBatch(array<Metric> $metrics)
• TracesBatch(array<Span> $spans)

#ContextStorage

Interface: Flow\Telemetry\Context\ContextStorage

Stores and retrieves telemetry context (active span, baggage) within a request lifecycle. Enables automatic context propagation to child spans.

#Tracer Contracts

#SpanProcessor

Interface: Flow\Telemetry\Tracer\SpanProcessor

Receives span lifecycle events (onStart, onEnd) and determines how spans are buffered and exported. The processor sits 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. Determines whether a span should be recorded and exported based on configurable rules.

#SpanEvent

Interface: Flow\Telemetry\Tracer\SpanEvent

Represents timestamped events that occurred during a span's lifetime (e.g., exceptions, state changes).

#Meter Contracts

#MetricProcessor

Interface: Flow\Telemetry\Meter\MetricProcessor

Processes metric measurements from instruments. Determines how metrics are aggregated and when 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 through which measurements are recorded.

#Logger Contracts

#LogProcessor

Interface: Flow\Telemetry\Logger\LogProcessor

Processes log records from loggers. Determines how logs are buffered and when they are exported. The exporter() accessor returns the unified Exporter.

#Propagation Contracts

#TextMapPropagator

Interface: Flow\Telemetry\Propagation\TextMapPropagator

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

#BaggagePropagator

Interface: Flow\Telemetry\Propagation\BaggagePropagator

Propagates application-specific key-value pairs (baggage) across process boundaries alongside trace context.

#Carrier

Interface: Flow\Telemetry\Propagation\Carrier

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

#Implementing Custom Contracts

All contracts are designed for extension. To implement a custom exporter:

<?php

use Flow\Telemetry\Batch\{LogsBatch, MetricsBatch, TracesBatch};
use Flow\Telemetry\Exporter\Exporter;
use Flow\Telemetry\Transport\{Transport, VoidTransport};

final class MyCustomExporter implements Exporter
{
    public function export(LogsBatch|MetricsBatch|TracesBatch $batch) : bool
    {
        match (true) {
            $batch instanceof TracesBatch => $this->writeSpans($batch->spans),
            $batch instanceof MetricsBatch => $this->writeMetrics($batch->metrics),
            $batch instanceof LogsBatch => $this->writeLogs($batch->entries),
        };

        return true;
    }

    public function transports() : array
    {
        return [new VoidTransport()];
    }

    // ... per-signal helpers
}

$processor = pass_through_span_processor(new MyCustomExporter());

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