Skip to main content
use Keepsuit\LaravelOpenTelemetry\Facades\Meter;
The Meter facade provides access to all OpenTelemetry metric instruments. It supports seven instrument types covering both synchronous (push) and asynchronous (observable/pull) recording patterns.
Instruments are cached by name within the same Meter instance. Calling a creation method with the same name twice returns the existing instrument. Calling it with the same name but a different instrument type throws a RuntimeException.

​
Synchronous instruments

Synchronous instruments record measurements at the point in code where the event occurs.

​
counter()

Creates or retrieves a monotonically increasing Counter. Use for values that only ever go up, such as the number of requests processed or errors encountered. 
CounterInterface Meter::counter(
    string $name,
    ?string $unit = null,
    ?string $description = null,
    array $advisory = []
)
​
name
string
required
Instrument name. Must be unique within this meter. Reusing the same name returns the cached instrument.
​
unit
string | null
default:"null"
Unit of measure, e.g. 'requests', 'bytes', '{errors}'.
​
description
string | null
default:"null"
Human-readable description of what this counter measures.
​
advisory
array
default:"[]"
Optional advisory hints passed to the SDK.
​
return
OpenTelemetry\API\Metrics\CounterInterface
The counter instrument. Call ->add(int|float $amount, iterable $attributes = []) to record a measurement.
$counter = Meter::counter('http.server.requests', '{requests}', 'Total HTTP requests handled');

$counter->add(1, ['http.method' => 'GET', 'http.status_code' => 200]);

​
histogram()

Creates or retrieves a Histogram. Use for measuring distributions of values such as request durations or payload sizes. 
HistogramInterface Meter::histogram(
    string $name,
    ?string $unit = null,
    ?string $description = null,
    array $advisory = []
)
​
name
string
required
Instrument name.
​
unit
string | null
default:"null"
Unit of measure, e.g. 's' (seconds), 'ms' (milliseconds), 'By' (bytes).
​
description
string | null
default:"null"
Human-readable description.
​
advisory
array
default:"[]"
Optional advisory hints. Pass ExplicitBucketBoundaries to customize histogram bucket boundaries.
​
return
OpenTelemetry\API\Metrics\HistogramInterface
The histogram instrument. Call ->record(int|float $amount, iterable $attributes = []) to record a value.
$histogram = Meter::histogram('db.query.duration', 'ms', 'Database query execution time');

$start = microtime(true);
DB::select($sql);
$histogram->record((microtime(true) - $start) * 1000, ['db.system' => 'mysql']);
Customize bucket boundaries via advisory: 
$histogram = Meter::histogram(
    name: 'http.response.size',
    unit: 'By',
    description: 'HTTP response body size',
    advisory: ['ExplicitBucketBoundaries' => [100, 1000, 10000, 100000]]
);

​
gauge()

Creates or retrieves a Gauge. Use for values that can go up or down and represent a current state, such as memory usage, queue depth, or temperature.
gauge() is marked as experimental in the OpenTelemetry PHP SDK.
GaugeInterface Meter::gauge(
    string $name,
    ?string $unit = null,
    ?string $description = null,
    array $advisory = []
)
​
name
string
required
Instrument name.
​
unit
string | null
default:"null"
Unit of measure.
​
description
string | null
default:"null"
Human-readable description.
​
advisory
array
default:"[]"
Optional advisory hints.
​
return
OpenTelemetry\API\Metrics\GaugeInterface
The gauge instrument. Call ->record(int|float $amount, iterable $attributes = []) to set the current value.
$gauge = Meter::gauge('queue.depth', '{jobs}', 'Number of jobs waiting in the queue');

$gauge->record(Queue::size('default'), ['queue.name' => 'default']);
$gauge->record(Queue::size('emails'), ['queue.name' => 'emails']);

​
upDownCounter()

Creates or retrieves an UpDownCounter. Like a counter but can also decrease — suitable for tracking values such as active connections or items in a pool. 
UpDownCounterInterface Meter::upDownCounter(
    string $name,
    ?string $unit = null,
    ?string $description = null,
    array $advisory = []
)
​
name
string
required
Instrument name.
​
unit
string | null
default:"null"
Unit of measure.
​
description
string | null
default:"null"
Human-readable description.
​
advisory
array
default:"[]"
Optional advisory hints.
​
return
OpenTelemetry\API\Metrics\UpDownCounterInterface
The up-down counter instrument. Call ->add(int|float $amount, iterable $attributes = []) with positive or negative values.
$connections = Meter::upDownCounter('db.connections.active', '{connections}', 'Active database connections');

// Connection opened
$connections->add(1, ['db.system' => 'mysql']);

// Connection closed
$connections->add(-1, ['db.system' => 'mysql']);

​
Asynchronous (observable) instruments

Asynchronous instruments report measurements through a callback that the SDK calls on its collection cycle. Use these when the measurement is expensive to compute or when you are observing an external value.

​
observableCounter()

Creates or retrieves an ObservableCounter. The SDK will call attached callbacks when it collects metrics. 
ObservableCounterInterface Meter::observableCounter(
    string $name,
    ?string $unit = null,
    ?string $description = null,
    array $advisory = []
)
​
name
string
required
Instrument name.
​
unit
string | null
default:"null"
Unit of measure.
​
description
string | null
default:"null"
Human-readable description.
​
advisory
array
default:"[]"
Optional advisory hints.
​
return
OpenTelemetry\API\Metrics\ObservableCounterInterface
The observable counter instrument. Use batchObserve() or attach a callback via the SDK to report values.
$counter = Meter::observableCounter('process.cpu.time', 's', 'CPU time consumed by the process');

​
observableGauge()

Creates or retrieves an ObservableGauge for asynchronous current-value reporting. 
ObservableGaugeInterface Meter::observableGauge(
    string $name,
    ?string $unit = null,
    ?string $description = null,
    array $advisory = []
)
​
name
string
required
Instrument name.
​
unit
string | null
default:"null"
Unit of measure.
​
description
string | null
default:"null"
Human-readable description.
​
advisory
array
default:"[]"
Optional advisory hints.
​
return
OpenTelemetry\API\Metrics\ObservableGaugeInterface
The observable gauge instrument.
$gauge = Meter::observableGauge('system.memory.usage', 'By', 'Current memory usage');

​
observableUpDownCounter()

Creates or retrieves an ObservableUpDownCounter for asynchronously reporting values that can increase or decrease. 
ObservableUpDownCounterInterface Meter::observableUpDownCounter(
    string $name,
    ?string $unit = null,
    ?string $description = null,
    array $advisory = []
)
​
name
string
required
Instrument name.
​
unit
string | null
default:"null"
Unit of measure.
​
description
string | null
default:"null"
Human-readable description.
​
advisory
array
default:"[]"
Optional advisory hints.
​
return
OpenTelemetry\API\Metrics\ObservableUpDownCounterInterface
The observable up-down counter instrument.
$counter = Meter::observableUpDownCounter('process.open.file_descriptors', '{file_descriptors}', 'Open file descriptors');

​
batchObserve()

Registers a single callback that reports measurements for multiple asynchronous instruments at once. This is more efficient than registering one callback per instrument when measurements share an expensive data source. 
ObservableCallbackInterface Meter::batchObserve(
    array $instruments,
    callable $callback
)
​
instruments
AsynchronousInstrument[]
required
An array of asynchronous instrument instances (observable counter, gauge, or up-down counter). All instruments must have been created by the same meter.
​
callback
callable
required
A callback that receives one ObserverInterface argument per instrument, in the same order as $instruments. Call ->observe(int|float $value, iterable $attributes = []) on each observer.
​
return
OpenTelemetry\API\Metrics\ObservableCallbackInterface
A token that can be used to detach the callback when it is no longer needed. Detach by calling ->detach() on the returned value.
use OpenTelemetry\API\Metrics\ObserverInterface;

$callback = Meter::batchObserve(
    [
        Meter::observableCounter('system.cpu.time', 's', 'CPU time by state'),
        Meter::observableGauge('system.memory.usage', 'By', 'Memory usage by type'),
    ],
    function (ObserverInterface $cpuObserver, ObserverInterface $memObserver): void {
        [$cpuTime, $memUsage] = collectSystemStats();

        $cpuObserver->observe($cpuTime, ['cpu.state' => 'user']);
        $memObserver->observe($memUsage, ['memory.type' => 'heap']);
    }
);

// Detach the callback when it is no longer needed
$callback->detach();

​
collect()

Forces the metric reader to collect and export all pending measurements immediately. 
bool Meter::collect()
​
return
bool
true if collection succeeded, false otherwise.
// Force export before process shutdown
Meter::collect();

​
Instrument caching

The Meter implementation caches every instrument by name. Requesting the same name a second time returns the previously created instance without allocating a new one: 
$a = Meter::counter('my.counter');
$b = Meter::counter('my.counter');

$a === $b; // true — same instance
If you request the same name with a different instrument type, a RuntimeException is thrown: 
Meter::counter('my.metric');      // OK
Meter::histogram('my.metric');    // throws RuntimeException: "Instrument with name 'my.metric' already exists as a different type."
Choose instrument names carefully and keep them consistent across your codebase.

Build docs developers (and LLMs) love

Get started for freeTalk to us