ez-php / metrics-otlp

2.7.1 2026-10-30 15:41 UTC

Requires

• php: ^8.5
• ez-php/contracts: ^2.7.0
• ez-php/metrics: ^2.7.0

Requires (Dev)

• ez-php/docker: ^2.7.0
• ez-php/testing-application: ^2.7.0
• friendsofphp/php-cs-fixer: ^3.94
• phpstan/phpstan: ^2.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^13.0

MIT

• Andreas Uretschnig

• php
• Metrics
• observability
• opentelemetry
• otlp
• ez-php

Published on Packagist.org on 2026-10-30 15:48 UTC

README

Exports ez-php/metrics counters, gauges and histograms to an OpenTelemetry collector as OTLP/HTTP JSON. It needs no SDK, no protobuf and nothing beyond the PHP standard library. If you already send traces to a collector with ez-php/otel, metrics can go there too, without a Prometheus scrape.

Installation

composer require ez-php/metrics-otlp

Setup

// provider/modules.php
EzPhp\Metrics\MetricsServiceProvider::class,
EzPhp\MetricsOtlp\MetricsOtlpServiceProvider::class,

METRICS_OTLP_ENDPOINT=http://otel-collector:4318/v1/metrics
METRICS_OTLP_SERVICE_NAME=shop          # empty = APP_NAME
METRICS_OTLP_HEADERS=Authorization=Bearer%20token

With an endpoint set, everything recorded through ez-php/metrics (Metrics::counter(...), RequestMetricsMiddleware, …) is exported. Without one, nothing is attached.

ez-php/metrics	OTLP
Counter	sum, monotonic, delta
Gauge	gauge (last value in the window)
Histogram	histogram, explicit buckets (the histogram's own bounds), delta

Labels become attributes, and the metric's help text becomes its description.

When is data sent?

• At the end of every PHP request or process, via a shutdown function.
• As soon as max_points values are waiting (default 1000).
• When you call flush(). Long-running workers should do this, for example after each job:

$app->make(EzPhp\MetricsOtlp\OtlpMetricsListener::class)->flush();

A failed export is dropped and nothing is thrown, so metrics never break a request.

Delta temporality

Each export contains only what happened since the previous one. That is the only model that works across short-lived PHP processes. If your collector forwards to Prometheus, add the deltatocumulative processor:

processors:
  deltatocumulative: {}
service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [deltatocumulative]
      exporters: [prometheus]

Custom HTTP client

Bind your own EzPhp\MetricsOtlp\Transport\MetricsTransportInterface. The default uses PHP's stream wrapper.

License

MIT