Metrics let you measure the behavior of your application over time — request rates, error counts, queue depths, latencies, and any other numeric value you care about. This package provides a Meter facade backed by the OpenTelemetry Metrics API.
Supported instrument types
OpenTelemetry defines several instrument types to cover different measurement scenarios:
| Instrument | Method | Description |
|---|
| Counter | counter() | A value that only increases (e.g. requests served) |
| ObservableCounter | observableCounter() | An asynchronous counter read via callback |
| UpDownCounter | upDownCounter() | A value that can increase or decrease (e.g. queue depth) |
| ObservableUpDownCounter | observableUpDownCounter() | An asynchronous up-down counter read via callback |
| Gauge | gauge() | A point-in-time measurement (e.g. CPU usage) |
| ObservableGauge | observableGauge() | An asynchronous gauge read via callback |
| Histogram | histogram() | Records a distribution of values (e.g. request duration) |
Instruments are cached by name within the same Meter instance. Calling the same method with the same name returns the cached instrument rather than creating a new one.
Meter facade reference
All instrument factory methods share the same signature:
Meter::counter(string $name, ?string $unit = null, ?string $description = null, array $advisory = []);
Meter::histogram(string $name, ?string $unit = null, ?string $description = null, array $advisory = []);
Meter::gauge(string $name, ?string $unit = null, ?string $description = null, array $advisory = []);
Meter::upDownCounter(string $name, ?string $unit = null, ?string $description = null, array $advisory = []);
Meter::observableCounter(string $name, ?string $unit = null, ?string $description = null, array $advisory = []);
Meter::observableGauge(string $name, ?string $unit = null, ?string $description = null, array $advisory = []);
Meter::observableUpDownCounter(string $name, ?string $unit = null, ?string $description = null, array $advisory = []);
Usage examples
Counter
Use a counter to track values that only go up:
use Keepsuit\LaravelOpenTelemetry\Facades\Meter;
$counter = Meter::counter('my-meter', 'times', 'my custom meter');
$counter->add(1);
Histogram
Use a histogram to record a distribution of measurements, such as durations or sizes:
use Keepsuit\LaravelOpenTelemetry\Facades\Meter;
$histogram = Meter::histogram('my-histogram', 'ms', 'my custom histogram');
$histogram->record(100, ['name' => 'value', 'app' => 'my-app']);
Gauge
Use a gauge to record a current value that can go up or down:
use Keepsuit\LaravelOpenTelemetry\Facades\Meter;
$gauge = Meter::gauge('my-gauge', null, 'my custom gauge');
$gauge->record(100, ['name' => 'value', 'app' => 'my-app']);
$gauge->record(1.2, ['name' => 'percentage', 'app' => 'my-app']);
Batch observable instruments
When multiple asynchronous instruments share an expensive data source, use batchObserve to collect all measurements in a single callback:
use Keepsuit\LaravelOpenTelemetry\Facades\Meter;
use OpenTelemetry\API\Metrics\ObserverInterface;
Meter::batchObserve([
Meter::observableCounter('usage', description: 'count of items used'),
Meter::observableGauge('pressure', description: 'force per unit area'),
], function (ObserverInterface $usageObserver, ObserverInterface $pressureObserver): void {
[$usage, $pressure] = expensive_system_call();
$usageObserver->observe($usage);
$pressureObserver->observe($pressure);
});
ObserverInterface argument per instrument, in the same order as the array.
Built-in instrumentation metrics
The included instrumentations automatically record the following metrics:
| Metric | Type | Unit | Recorded by |
|---|
http.server.request.duration | Histogram | s | HTTP server instrumentation |
http.client.request.duration | Histogram | s | HTTP client instrumentation |
db.client.operation.duration | Histogram | s | Database (Query) and Redis instrumentations |
Metrics temporality
The OTLP exporter supports two temporality modes for exported metrics:
| Mode | Description |
|---|
Cumulative | Each export includes all measurements since the process started |
Delta | Each export includes only measurements since the last export |
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=Delta
config/opentelemetry.php:
'exporters' => [
'otlp' => [
// ...
'metrics_temporality' => env('OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE'),
],
],
