README

A production-grade observability toolkit for PHP 8.4+ providing metrics, distributed tracing, and structured logging in a single, unified package. Ships with Prometheus, StatsD, W3C Trace Context, and PSR-3/PSR-15 integrations out of the box.

What's New in 2.0

Area	v1	v2
PHP version	8.1+	8.4+ — `readonly`, `final`, enums, named args
Metrics	Basic Prometheus only	`MetricsInterface` — Prometheus, StatsD, InMemory, Null drivers
Tracing	❌	Full W3C Trace Context — spans, events, exporters
Logging	❌	PSR-3 `TelemetryLogger` with automatic trace correlation
Middleware	❌	PSR-15 `RequestMetricsMiddleware` + `RequestTracingMiddleware`
Attributes	❌	`#[Traced]`, `#[Counted]`, `#[Timed]`
Factory	Manual construction	`TelemetryFactory::create()` — one-line bootstrapping
Facade	❌	`Telemetry::counter()`, `Telemetry::trace()`, `Telemetry::log()`

Features

📊 Metrics — Counter, Gauge, Histogram, Summary with Prometheus and StatsD backends

🔍 Distributed Tracing — W3C Trace Context compatible spans, events, and exception recording

📝 Structured Logging — PSR-3 logger with automatic trace/span ID injection

🌐 PSR-15 Middleware — Automatic HTTP request metrics and distributed tracing

🏷️ PHP 8 Attributes — #[Traced], #[Counted], #[Timed] for declarative instrumentation

🏭 Factory Pattern — One-line bootstrap via TelemetryFactory::create()

⚡ Zero-cost Null Drivers — NullMetrics, NullTracer for safe development

Installation

composer require monkeyscloud/monkeyslegion-telemetry:^2.0

Optional Dependencies

# Prometheus exposition format
composer require promphp/prometheus_client_php

# PSR-15 middleware support
composer require psr/http-message psr/http-server-middleware

Quick Start

One-line Bootstrap

use MonkeysLegion\Telemetry\Telemetry;

Telemetry::init([
    'metrics' => ['driver' => 'memory', 'namespace' => 'myapp'],
    'tracing' => ['service_name' => 'myapp', 'exporter' => 'console'],
    'logging' => ['json' => true, 'level' => 'info'],
]);

// Metrics
Telemetry::counter('requests_total');
Telemetry::gauge('active_connections', 42);
Telemetry::histogram('response_time', 0.123);

// Tracing
$result = Telemetry::trace('fetch-user', fn () => $userRepo->find($id));

// Logging (with automatic trace correlation)
Telemetry::log()->info('User fetched', ['user_id' => $id]);

Metrics

All metric drivers implement MetricsInterface and support Counter, Gauge, Histogram, Summary, and Timer operations.

Drivers

Driver	Class	Use Case
`null`	`NullMetrics`	Development — zero overhead
`memory`	`InMemoryMetrics`	Testing, single-request
`prometheus`	`PrometheusMetrics`	Production — Prometheus scraping
`statsd`	`StatsDMetrics`	Production — StatsD / DogStatsD / Telegraf

Counter (Monotonically Increasing)

use MonkeysLegion\Telemetry\Telemetry;

// Increment by 1
Telemetry::counter('http_requests_total');

// Increment by N with dimensional labels
Telemetry::counter('http_requests_total', 1, [
    'method' => 'GET',
    'status' => '200',
]);

Gauge (Point-in-Time Value)

Telemetry::gauge('active_connections', 42);
Telemetry::gauge('queue_depth', 128, ['queue' => 'emails']);

Histogram (Distribution / Timing)

Telemetry::histogram('response_time_seconds', 0.157);

// Custom buckets
Telemetry::histogram('payload_size_bytes', 4096, [], [
    100, 500, 1000, 5000, 10000, 50000,
]);

Timer Helper

$stop = Telemetry::timer('db_query_duration');

$result = $db->query('SELECT ...');

$elapsed = $stop(['query' => 'user_lookup']);
// Records a histogram observation automatically

Direct Driver Construction

use MonkeysLegion\Telemetry\Metrics\StatsDMetrics;
use MonkeysLegion\Telemetry\Metrics\PrometheusMetrics;
use MonkeysLegion\Telemetry\Metrics\InMemoryMetrics;
use Prometheus\Storage\InMemory;

// StatsD
$metrics = new StatsDMetrics(
    host: '127.0.0.1',
    port: 8125,
    namespace: 'myapp',
    dogstatsd: true,    // DogStatsD tag format
    sampleRate: 0.5,    // 50% sampling
);

// Prometheus
$metrics = new PrometheusMetrics(
    adapter: new InMemory(),
    namespace: 'myapp',
);

// InMemory (testing)
$metrics = new InMemoryMetrics('myapp');
$metrics->counter('requests', 1, ['method' => 'GET']);
$all = $metrics->getMetrics(); // inspect recorded values

Distributed Tracing

W3C Trace Context compatible tracing with automatic parent-child span relationships.

Traced Callback (Recommended)

use MonkeysLegion\Telemetry\Telemetry;

$order = Telemetry::trace('create-order', function () use ($cart) {
    // Nested spans are automatically parented
    $items = Telemetry::trace('validate-items', fn () => $cart->validate());
    $payment = Telemetry::trace('charge-payment', fn () => $stripe->charge($cart));

    return new Order($items, $payment);
});

Manual Span Management

use MonkeysLegion\Telemetry\Telemetry;
use MonkeysLegion\Telemetry\Tracing\SpanKind;
use MonkeysLegion\Telemetry\Tracing\SpanStatus;

$span = Telemetry::startSpan('db.query', SpanKind::CLIENT, [
    'db.system'    => 'mysql',
    'db.statement' => 'SELECT * FROM users WHERE id = ?',
]);

try {
    $result = $db->query($sql, $params);
    $span->setStatus(SpanStatus::OK);
    $span->setAttribute('db.row_count', count($result));
} catch (\Throwable $e) {
    $span->recordException($e);
    $span->setStatus(SpanStatus::ERROR, $e->getMessage());
    throw $e;
} finally {
    $span->end();
}

Span Events

$span = Telemetry::startSpan('process-order');

$span->addEvent('payment.started', ['amount' => 99.99]);
// ... process payment ...
$span->addEvent('payment.completed', ['transaction_id' => 'txn_123']);

$span->end();

Trace Context Propagation

use MonkeysLegion\Telemetry\Factory\TelemetryFactory;

$tracer = TelemetryFactory::createTracer([
    'service_name' => 'api-gateway',
    'exporter'     => 'http',
    'endpoint'     => 'http://jaeger:4318/v1/traces',
]);

// Extract from incoming HTTP headers
$context = $tracer->extract($request->getHeaders());

// Inject into outgoing HTTP headers
$headers = $tracer->inject([]);
// $headers = ['traceparent' => '00-<trace_id>-<span_id>-01']

Span Kinds

Kind	Use
`SpanKind::INTERNAL`	Default — internal application logic
`SpanKind::SERVER`	Incoming HTTP request handling
`SpanKind::CLIENT`	Outgoing HTTP / DB / RPC call
`SpanKind::PRODUCER`	Message queue publish
`SpanKind::CONSUMER`	Message queue consume

Exporters

Exporter	Class	Use Case
`console`	`ConsoleExporter`	Local development / debugging
`http`	`JsonHttpExporter`	OTLP/HTTP — Jaeger, Tempo, Zipkin
—	`InMemoryExporter`	Unit testing

Logging with Trace Correlation

PSR-3 compatible logging that automatically injects trace_id and span_id into every log entry.

use MonkeysLegion\Telemetry\Telemetry;

Telemetry::init([
    'tracing' => ['service_name' => 'api'],
    'logging' => ['json' => true, 'stream' => 'php://stderr'],
]);

Telemetry::trace('handle-request', function () {
    // trace_id and span_id injected automatically
    Telemetry::log()->info('Processing request', ['path' => '/api/users']);
    Telemetry::log()->warning('Slow query detected', ['duration_ms' => 450]);
});

// Output (JSON):
// {"level":"info","message":"Processing request","trace_id":"abc123...","span_id":"def456...","path":"/api/users","timestamp":"2026-04-27T20:00:00+00:00"}

Direct Logger Construction

use MonkeysLegion\Telemetry\Logging\TelemetryLogger;
use MonkeysLegion\Telemetry\Logging\StreamLogger;
use MonkeysLegion\Telemetry\Logging\JsonFormatter;
use MonkeysLegion\Telemetry\Logging\TracingContextProvider;
use Psr\Log\LogLevel;

$streamLogger = new StreamLogger(
    stream: '/var/log/app.log',
    minLevel: LogLevel::INFO,
    formatter: new JsonFormatter(prettyPrint: false),
);

$logger = new TelemetryLogger(
    logger: $streamLogger,
    contextProvider: new TracingContextProvider($tracer),
);

$logger->info('User created', ['user_id' => 42]);

// With explicit trace context
$logger->logWithTelemetry(
    level: 'info',
    message: 'Payment processed',
    context: ['amount' => 99.99],
    traceId: 'abc123',
    spanId: 'def456',
);

Log Processors

$logger->addProcessor(function (array $record): array {
    $record['context']['hostname'] = gethostname();
    $record['context']['pid'] = getmypid();
    return $record;
});

$logger->setDefaultContext(['app' => 'myapp', 'env' => 'production']);

PSR-15 Middleware

Request Metrics

Automatically records http_requests_total, http_request_duration_seconds, and http_requests_in_progress for every request.

use MonkeysLegion\Telemetry\Middleware\RequestMetricsMiddleware;

$middleware = new RequestMetricsMiddleware(
    metrics: $metrics,
    includeRoute:  true,   // label: route
    includeMethod: true,   // label: method
    includeStatus: true,   // label: status
);

// Add to your PSR-15 middleware pipeline
$app->pipe($middleware);

Recorded metrics:

Metric	Type	Labels
`http_requests_total`	Counter	`method`, `route`, `status`
`http_request_duration_seconds`	Histogram	`method`, `route`, `status`
`http_requests_in_progress`	Gauge	—

Request Tracing

Creates a root SERVER span per request with W3C trace context propagation.

use MonkeysLegion\Telemetry\Middleware\RequestTracingMiddleware;

$middleware = new RequestTracingMiddleware(
    tracer: $tracer,
    propagateContext: true,  // inject traceparent in response headers
);

$app->pipe($middleware);

Span attributes:

Attribute	Example
`http.method`	`GET`
`http.url`	`https://api.example.com/users/42`
`http.target`	`/users/42`
`http.status_code`	`200`
`http.host`	`api.example.com`
`net.peer.ip`	`192.168.1.1`

PHP 8 Attributes

Declarative instrumentation via attributes. Combine with an AOP framework or the MonkeysLegion service container for automatic weaving.

`#[Traced]` — Automatic Span Creation

use MonkeysLegion\Telemetry\Attribute\Traced;
use MonkeysLegion\Telemetry\Tracing\SpanKind;

class UserService
{
    #[Traced('fetch-user')]
    public function find(int $id): User { /* ... */ }

    #[Traced(kind: SpanKind::CLIENT, attributes: ['db.system' => 'mysql'])]
    public function query(string $sql): array { /* ... */ }
}

`#[Counted]` — Automatic Call Counting

use MonkeysLegion\Telemetry\Attribute\Counted;

class OrderController
{
    #[Counted('api_orders_total')]
    public function create(Request $request): Response { /* ... */ }

    #[Counted(labels: ['type' => 'refund'], countExceptions: true)]
    public function refund(string $orderId): void { /* ... */ }
}

`#[Timed]` — Automatic Duration Measurement

use MonkeysLegion\Telemetry\Attribute\Timed;

class ReportGenerator
{
    #[Timed('report_generation_duration')]
    public function generate(string $type): Report { /* ... */ }

    #[Timed(buckets: [0.1, 0.5, 1.0, 5.0, 10.0])]
    public function export(Report $report): string { /* ... */ }
}

Factory & Configuration

TelemetryFactory

use MonkeysLegion\Telemetry\Factory\TelemetryFactory;

// Create individual components
$metrics = TelemetryFactory::createMetrics([
    'driver'    => 'statsd',
    'namespace' => 'myapp',
    'host'      => '127.0.0.1',
    'port'      => 8125,
    'dogstatsd' => true,
    'sample_rate' => 0.5,
]);

$tracer = TelemetryFactory::createTracer([
    'enabled'      => true,
    'service_name' => 'api',
    'sample_rate'  => 1.0,
    'exporter'     => 'http',
    'endpoint'     => 'http://jaeger:4318/v1/traces',
    'headers'      => ['Authorization' => 'Bearer token'],
]);

$logger = TelemetryFactory::createLogger([
    'stream' => 'php://stderr',
    'level'  => 'info',
    'json'   => true,
    'pretty' => false,
]);

// Or create the full stack in one call
$stack = TelemetryFactory::create([
    'metrics' => ['driver' => 'prometheus'],
    'tracing' => ['service_name' => 'api', 'exporter' => 'http'],
    'logging' => ['json' => true],
]);
// $stack['metrics'], $stack['tracer'], $stack['logger']

Configuration Reference

Metrics

Key	Type	Default	Description
`driver`	`string`	`'null'`	`null`, `memory`, `prometheus`, `statsd`
`namespace`	`string`	`'app'`	Metric name prefix
`host`	`string`	`'127.0.0.1'`	StatsD host
`port`	`int`	`8125`	StatsD port
`dogstatsd`	`bool`	`false`	Enable DogStatsD tag format
`sample_rate`	`float`	`1.0`	StatsD sampling rate (0.0–1.0)
`prometheus_adapter`	`Adapter`	`InMemory`	Prometheus storage adapter

Tracing

Key	Type	Default	Description
`enabled`	`bool`	`true`	Enable/disable tracing
`service_name`	`string`	`'app'`	Service identifier
`sample_rate`	`float`	`1.0`	Trace sampling rate (0.0–1.0)
`exporter`	`string`	`'console'`	`console`, `http`, `none`
`endpoint`	`string`	`'http://localhost:4318/v1/traces'`	OTLP endpoint
`headers`	`array`	`[]`	Extra HTTP headers for exporter

Logging

Key	Type	Default	Description
`stream`	`string\|resource`	`'php://stderr'`	Output stream
`level`	`string`	`'debug'`	Minimum log level (PSR-3)
`json`	`bool`	`false`	Enable JSON formatting
`pretty`	`bool`	`false`	Pretty-print JSON

Complete Application Example

use MonkeysLegion\Telemetry\Telemetry;
use MonkeysLegion\Telemetry\Tracing\SpanKind;
use MonkeysLegion\Telemetry\Middleware\RequestMetricsMiddleware;
use MonkeysLegion\Telemetry\Middleware\RequestTracingMiddleware;

// ── Bootstrap ──────────────────────────────────────────────
Telemetry::init([
    'metrics' => [
        'driver'    => 'statsd',
        'namespace' => 'ecommerce',
        'host'      => 'statsd.internal',
    ],
    'tracing' => [
        'service_name' => 'order-service',
        'exporter'     => 'http',
        'endpoint'     => 'http://jaeger:4318/v1/traces',
        'sample_rate'  => 0.1,
    ],
    'logging' => [
        'json'   => true,
        'level'  => 'info',
        'stream' => '/var/log/app.log',
    ],
]);

// ── Middleware Pipeline ────────────────────────────────────
$app->pipe(new RequestTracingMiddleware(Telemetry::tracer()));
$app->pipe(new RequestMetricsMiddleware(Telemetry::metrics()));

// ── Application Code ───────────────────────────────────────
function placeOrder(Cart $cart): Order
{
    return Telemetry::trace('place-order', function () use ($cart) {
        Telemetry::log()->info('Order started', ['items' => count($cart)]);

        // Validate stock (traced)
        $stock = Telemetry::trace('check-inventory', function () use ($cart) {
            $stop = Telemetry::timer('inventory_check_duration');
            $result = InventoryService::check($cart->items());
            $stop(['warehouse' => 'us-east']);
            return $result;
        });

        // Charge payment (traced as CLIENT span)
        $payment = Telemetry::trace(
            'charge-payment',
            fn () => PaymentGateway::charge($cart->total()),
            SpanKind::CLIENT,
            ['payment.provider' => 'stripe'],
        );

        Telemetry::counter('orders_completed_total', 1, ['region' => 'us']);
        Telemetry::log()->info('Order completed', ['order_id' => $payment->orderId]);

        return new Order($stock, $payment);
    });
}

Prometheus Metrics Endpoint

use MonkeysLegion\Telemetry\Metrics\PrometheusMetrics;
use Prometheus\Storage\Redis;
use Prometheus\RenderTextFormat;

// Shared Redis-backed storage for multi-process
$metrics = new PrometheusMetrics(
    adapter: new Redis(['host' => 'redis']),
    namespace: 'myapp',
);

// Exposition route: GET /metrics
$renderer = new RenderTextFormat();
$registry = $metrics->getRegistry();

header('Content-Type', $renderer->getMimeType());
echo $renderer->render($registry->getMetricFamilySamples());

Architecture

MonkeysLegion\Telemetry\
├── Telemetry               # Static facade
├── Factory/
│   └── TelemetryFactory    # Component factory
├── Metrics/
│   ├── MetricsInterface    # Driver contract
│   ├── AbstractMetrics     # Base class (timer, default labels)
│   ├── NullMetrics         # No-op
│   ├── InMemoryMetrics     # Testing
│   ├── PrometheusMetrics   # Prometheus via promphp/prometheus_client_php
│   └── StatsDMetrics       # UDP-based StatsD / DogStatsD
├── Tracing/
│   ├── TracerInterface     # Tracer contract
│   ├── Tracer              # W3C Trace Context implementation
│   ├── SpanInterface       # Span contract
│   ├── Span                # Span implementation
│   ├── SpanKind            # Enum: INTERNAL, SERVER, CLIENT, PRODUCER, CONSUMER
│   ├── SpanStatus          # Enum: UNSET, OK, ERROR
│   ├── NullTracer          # No-op tracer
│   ├── NullSpan            # No-op span
│   └── Exporter/
│       ├── SpanExporterInterface
│       ├── ConsoleExporter
│       ├── InMemoryExporter
│       └── JsonHttpExporter
├── Logging/
│   ├── TelemetryLoggerInterface  # PSR-3 extension
│   ├── TelemetryLogger           # Core logger with processors
│   ├── StreamLogger              # File/stdout/stderr writer
│   ├── JsonFormatter             # Structured JSON output
│   ├── ContextProvider           # Context injection contract
│   └── TracingContextProvider    # Auto-injects trace/span IDs
├── Middleware/
│   ├── RequestMetricsMiddleware  # PSR-15 HTTP metrics
│   └── RequestTracingMiddleware  # PSR-15 distributed tracing
├── Attribute/
│   ├── Traced      # #[Traced] — automatic span creation
│   ├── Counted     # #[Counted] — automatic call counting
│   └── Timed       # #[Timed] — automatic duration measurement
└── Exception/
    ├── TelemetryException
    ├── MetricsException
    └── TracingException

Testing

composer test                # Run all tests
composer test:coverage       # Generate HTML coverage report
composer analyse             # PHPStan level 8
composer cs-check            # Code style check
composer cs-fix              # Auto-fix code style

monkeyscloud / monkeyslegion-telemetry

Maintainers

Package info

Statistics

Security

README

What's New in 2.0

Features

Installation

Optional Dependencies

Quick Start

One-line Bootstrap

Metrics

Drivers

Counter (Monotonically Increasing)

Gauge (Point-in-Time Value)

Histogram (Distribution / Timing)

Timer Helper

Direct Driver Construction

Distributed Tracing

Traced Callback (Recommended)

Manual Span Management

Span Events

Trace Context Propagation

Span Kinds

Exporters

Logging with Trace Correlation

Direct Logger Construction

Log Processors

PSR-15 Middleware

Request Metrics

Request Tracing

PHP 8 Attributes

#[Traced] — Automatic Span Creation

#[Counted] — Automatic Call Counting

#[Timed] — Automatic Duration Measurement

Factory & Configuration

TelemetryFactory

Configuration Reference

Metrics

Tracing

Logging

Complete Application Example

Prometheus Metrics Endpoint

Architecture

Testing

License

`#[Traced]` — Automatic Span Creation

`#[Counted]` — Automatic Call Counting

`#[Timed]` — Automatic Duration Measurement