feature: flow php telemetry library #2150
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
norberttech
force-pushed
the
feature/telemetry
branch
from
77e5e22 to
1e7f1e5
Compare
feature: telemetry building blocks
- added: New flow-php/telemetry library for metrics and tracing (core
foundation)
- added: TraceId - OpenTelemetry-compatible 16-byte trace identifier
with hex/bytes conversion
- added: SpanId - OpenTelemetry-compatible 8-byte span identifier with
hex/bytes conversion
- added: Baggage - immutable key-value store for context propagation
across process boundaries
- added: Context - main telemetry context carrier with TraceId, Baggage,
and active span tracking
- added: Resource - immutable entity metadata (service.name, version,
host) attached to all telemetry signals
- added: DSL functions: trace_id(), span_id(), baggage(), context(),
resource()
- added: Serialization support via normalize()/fromArray() on all
context classes
feature: building blocks for tracer
- added: SpanStatus - status code with optional description
- added: SpanContext - immutable span identification (traceId, spanId,
parentSpanId)
- added: SpanEvent interface and GenericEvent implementation for span
events
- added: SpanLink - links between spans with attributes
- added: Span - mutable span with lifecycle management, attributes,
events, and links
- added: DSL functions: trace_id(), span_id(), baggage(), context(),
resource(), span_context(), span_event(), span_link()
feature: initial version of tracer
- added: SpanExporter interface - export spans to external systems
- added: TracerProvider interface with withContextStorage() for shared
context propagation
- added: Tracer - creates and manages spans with automatic parent-child
relationships
- added: ContextStorage interface and LocalContextStorage for shared
context access across providers
- added: InMemoryTracerProvider - caches tracers by name/version, stores
spans in memory for testing
- added: InMemorySpanProcessor - stores spans in memory grouped by trace
ID for testing
- added: VoidSpanProcessor, VoidSpanExporter, VoidTracerProvider - no-op
implementations for disabled tracing
- added: DSL functions: trace_id(), span_id(), baggage(), context(),
resource(), span_context(), span_event(), span_link()
- added: DSL functions: telemetry_provider_memory(),
telemetry_provider_void()
- added: psr/clock dependency for clock abstraction
feature: logger contract
- added: Severity enum - OpenTelemetry-aligned log levels (TRACE, DEBUG,
INFO, WARN, ERROR, FATAL)
- added: LogRecord - immutable value object for structured log data with
fluent API
- added: Logger interface - convenience methods (trace, debug, info,
warn, error, fatal) and emit(LogRecord)
- added: LogProcessor interface - log record processing with SpanContext
correlation
- added: LogExporter interface - export logs to external systems
- added: LoggerProvider interface - factory for creating Logger
instances
feature: logger implementations
- added: VoidLogger, VoidLogProcessor, VoidLogExporter,
VoidLoggerProvider - no-op implementations for disabled logging
- added: InMemoryLogger, InMemoryLogProcessor, InMemoryLoggerProvider -
in-memory implementations for testing
- added: DSL functions: void_logger_provider(), logger_provider_memory()
feature: meter provider
- added: VoidMetricProcessor, VoidMetricExporter, VoidMeterProvider -
no-op implementations for disabled metrics collection
- added: InMemoryMetricProcessor, InMemoryMeterProvider - in-memory
implementations for testing with query helpers
- added: void_meter_provider() and in_memory_meter_provider() DSL
factory functions
- added: comprehensive unit tests for all Void and InMemory meter
implementations
- added: MetricsIntegrationTest for complete metrics workflow testing
- changed: Updated VoidMeterProviderTest, InMemoryMeterProviderTest, and
MetricsIntegrationTest to use DSL factory functions
- changed: Added PHPDoc type annotations to ExemplarTest and MetricTest
for PHPStan compliance
feature: telemetry entry point
- added: Telemetry main entry point class providing unified access to
tracing, metrics, and logging
- added: Provider namespace structure
(Flow\Telemetry\Provider\{Memory,Void}) for consistent provider
organization
- added: DSL function telemetry() for creating Telemetry instances
- changed: Renamed InMemory* classes to Memory* (MemoryTracerProvider,
MemoryMeterProvider, MemoryLoggerProvider, etc.)
- changed: Moved all provider implementations from component-specific
namespaces to Flow\Telemetry\Provider\{Memory,Void}
- changed: Renamed DSL functions for consistency:
telemetry_provider_memory() → tracer_memory_provider(),
void_logger_provider() → logger_void_provider(), etc.
feature: missing building blocks
- added: Carrier interface and ArrayCarrier for type-safe context
propagation
- added: W3CTraceContext and W3CBaggage propagators for distributed
tracing
- added: CompositePropagator and BaggagePropagator interfaces
- added: Telemetry::extract() and Telemetry::inject() methods for
context propagation
- added: Sampler system (AlwaysOnSampler, AlwaysOffSampler,
ParentBasedSampler, TraceIdRatioBasedSampler)
- added: InstrumentationScope for tracking instrumentation library
metadata
- added: SpanLimits for configuring span attribute/event/link limits
- added: TraceFlags and TraceState for W3C trace context support
- added: normalize()/fromArray() serialization methods on telemetry
value objects
- changed: Span now requires InstrumentationScope in constructor
- changed: SpanContext now includes TraceFlags and TraceState
- changed: TextMapPropagator interface uses typed Carrier instead of
mixed
feature: otlp bridge
- added: New telemetry library (flow-php/telemetry) with
OpenTelemetry-inspired API for traces, metrics, and logs
- added: OTLP bridge (flow-php/telemetry-otlp) for exporting telemetry
to OpenTelemetry Protocol collectors
- added: Tracer API with spans, events, links, and context propagation
- added: Meter API with Counter, UpDownCounter, Gauge, and Histogram
instruments
- added: Logger API with severity levels (TRACE, DEBUG, INFO, WARN,
ERROR, FATAL)
- added: Memory and Void provider implementations for testing and
disabled telemetry
- added: Batching processors for efficient OTLP export with configurable
batch sizes
- added: JSON and Protobuf serializers for OTLP wire format
- added: HTTP, gRPC, and async curl transports for OTLP endpoints
- added: DSL functions for easy telemetry setup (telemetry(),
tracer_provider(), meter_provider(), logger_provider())
- changed: Processor interfaces now expose exporter() method instead of
signal-specific names
- changed: Exporter interfaces now expose transports() method for
lifecycle management
- changed: Removed shutdown() from Exporter interfaces - only Transport
has shutdown responsibility
refactor: unified exporters and attributres
- added: LogEntry class to wrap LogRecord with contextual information
- added: Signal-specific exporters (MemoryLogExporter,
MemoryMetricExporter, MemorySpanExporter)
- added: Signal-specific void exporters (VoidLogExporter,
VoidMetricExporter, VoidSpanExporter)
- added: Support for DateTimeInterface and Throwable in Attributes
values
- changed: Transport interface now has signal-specific methods
(sendSpans, sendMetrics, sendLogs)
- changed: Renamed LocalContextStorage to MemoryContextStorage
- changed: LogProcessor and LogExporter now work with LogEntry instead
of arrays
- changed: AttributeSerializer now accepts Attributes objects instead of
arrays
- removed: Logs, Metrics, Spans wrapper classes
- removed: Generic MemoryExporter and VoidExporter
- removed: Duplicate batching processors from OTLP bridge
- removed: OTLP Serializer interface, Signal enum and Transport
interface
feature: exemplar's
- added: ExemplarFilter interface with AlwaysOn, AlwaysOff, and
TraceBased implementations
- added: ExemplarReservoir interface with SimpleFixedSize and
AlignedHistogramBucket implementations
- added: DSL functions for exemplar filters (always_on_exemplar_filter,
always_off_exemplar_filter, trace_based_exemplar_filter)
- added: ExemplarFilter parameter to meter_provider() DSL function
- added: Exemplar trace context display in ConsoleMetricExporter
- changed: Sampler interface simplified - shouldSample() now takes Span,
getDescription() renamed to __toString()
- changed: MeterProvider and Meter now accept ExemplarFilter parameter
- changed: Instrument classes now use ExemplarFilter and
ExemplarReservoir
- changed: Tracer span creation refactored to propagate trace flags from
parent context
- removed: Old stub ExemplarFilter and ExemplarReservoir interfaces
(moved to Meter/Exemplar/)
feature: context propagators
- added: Unified `Propagator` interface for context propagation
- added: `PropagationContext` value object containing both `SpanContext`
and `Baggage`
- added: `SuperglobalCarrier` for extracting context from PHP
superglobals
- added: DSL functions for propagation: propagation_context(),
array_carrier(), superglobal_carrier(), w3c_trace_context(),
w3c_baggage(), composite_propagator()
- added: Telemetry exception namespace with Exception and
RuntimeException
- changed: BREAKING - Renamed TextMapPropagator to Propagator
- changed: BREAKING - Propagator::extract() now returns
PropagationContext instead of ?SpanContext
- changed: BREAKING - Propagator::inject() now accepts
PropagationContext instead of SpanContext
- changed: CompositePropagator now merges contexts from all propagators
instead of returning first match
- removed: TextMapPropagator interface (replaced by Propagator)
- removed: BaggagePropagator interface (merged into unified Propagator)
feature: rename simple processors to pass through processors
- added: Telemetry library documentation with comprehensive guides for
traces, metrics, logs, processors, exporters, and propagators
- added: Telemetry OTLP Bridge documentation covering transports (Curl,
HTTP, gRPC), serializers (JSON, Protobuf), and APM integration examples
- added: Telemetry contracts documentation listing all interfaces and
their implementations
- added: Monorepo split configuration for telemetry-otlp-bridge package
- changed: Renamed Simple*Processor classes to PassThrough*Processor
(spans, metrics, logs) for clarity
- changed: Renamed DSL functions: simple_*_processor() →
pass_through_*_processor()
fix: remove ext-pg_query from monorepo composer.json
chore: updated dependencies
fix: telemetry collector on ci/cd
fix: otel collector service at gh actions
fix: run otel collector in background
fix: mutation tests configuration
fix: mutation tests
Improve mutation score
fix: otel collector port on gh actions
rm: debug otel collector
fix: exposing metrics from otel collector to tests
norberttech
force-pushed
the
feature/telemetry
branch
from
7bb0257 to
e1e0379
Compare
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## 1.x #2150 +/- ##
==========================================
+ Coverage 83.09% 83.85% +0.76%
==========================================
Files 1178 1269 +91
Lines 42164 45500 +3336
==========================================
+ Hits 35035 38156 +3121
- Misses 7129 7344 +215
🚀 New features to boost your workflow:
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Resolves: #1334
Change Log
Added
Fixed
Changed
Removed
Deprecated
Security