laravel-statsd

Fire-and-forget StatsD metrics for Laravel, built for Netdata's built-in StatsD collector but compatible with any standard StatsD server.

Metrics are sent over UDP: a dropped packet or an unreachable server never delays or fails the request being measured.

Requirements

• PHP 8.2+
• Laravel 12.x or 13.x

Installation

composer require zhylon/laravel-statsd

Publish the config file:

php artisan vendor:publish --tag=config

Point it at your StatsD server in .env:

STATSD_HOST=127.0.0.1
STATSD_PORT=8125
STATSD_PREFIX=myapp

Usage

Type-hint the StatsdClient contract wherever you need it — it's bound as a singleton in the container:

use Zhylon\LaravelStatsd\Contracts\StatsdClient;

class ProcessesOrders
{
    public function __construct(private StatsdClient $statsd) {}

    public function handle(Order $order): void
    {
        $this->statsd->increment('orders.processed');

        $start = microtime(true);
        // ... do the work ...
        $this->statsd->timing('orders.duration', (microtime(true) - $start) * 1000);

        $this->statsd->gauge('orders.queue_size', Order::pending()->count());
        $this->statsd->set('orders.unique_customers', $order->customer_id);
    }
}

Or use the Statsd facade wherever constructor injection is inconvenient:

use Zhylon\LaravelStatsd\Facades\Statsd;

Statsd::increment('orders.processed');

$sampleRate (between 0.0 and 1.0) lets high-volume counters and timings sample instead of firing on every call — the client appends the |@rate suffix so your StatsD server scales the value back up.

Automatic no-op during tests

The package binds a NullStatsdClient automatically whenever $app->runningUnitTests() is true, so your test suite never fires real UDP packets — no need to fake or mock the client yourself.

Config

Testing

composer test

License

The MIT License (MIT). See LICENSE for more information.