Edit

#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.

• ⬅️️ Back

#Core Contracts

#Transport

Interface: Flow\Telemetry\Transport\Transport

Sends serialized telemetry data to backends over the network. Has signal-specific methods: sendSpans(), sendMetrics(), sendLogs().

#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.

#Serializer

Interface: Flow\Telemetry\Serializer\Serializer

Converts telemetry data structures (spans, metrics, logs) into wire formats for transmission over transports.

#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 SpanExporter.

#SpanExporter

Interface: Flow\Telemetry\Tracer\SpanExporter

Exports completed spans to external observability backends. Receives batches of spans from processors.

#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.

#MetricExporter

Interface: Flow\Telemetry\Meter\MetricExporter

Exports collected metrics to external observability backends. Receives batches of metrics from processors.

#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.

#LogExporter

Interface: Flow\Telemetry\Logger\LogExporter

Exports log records to external observability backends. Receives batches of logs from processors.

#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, processor, or transport:

1. Implement the relevant interface
2. Pass your implementation to the appropriate provider or processor

<?php

use Flow\Telemetry\Tracer\SpanExporter;
use Flow\Telemetry\Tracer\ReadableSpan;

final class MyCustomSpanExporter implements SpanExporter
{
    /**
     * @param array<ReadableSpan> $spans
     */
    public function export(array $spans): bool
    {
        foreach ($spans as $span) {
            // Send to your custom backend
        }
        return true;
    }
}

// Use with any processor
$processor = pass_through_span_processor(new MyCustomSpanExporter());