Srf Datadog Statsd Bundle Laravel Package

Getting Started

This is a Symfony 2-era bundle, not a Laravel package — and it has been archived since 2015. Before writing any code, confirm what you're actually dealing with:

1. Read the DI extension first. Open DependencyInjection/SRFPhpDatadogStatsDBundleExtension.php and DependencyInjection/Configuration.php. These tell you the exact config keys (host, port, namespace, possibly sample_rate) and the service ID you'd inject (typically something like srf_php_datadog_statsd).
2. Check the underlying client. The bundle is a thin wrapper over php-datadog-statsd; the real API surface (increment, decrement, gauge, timing, histogram, set, update_stats) lives there. The bundle only wires it into the container.
3. Check composer.json constraints. You will almost certainly find Symfony ~2.x requirements and no PHP 8 support. composer require into a Laravel app will either fail on constraints or drag in conflicting Symfony components.

Realistic first step for a Laravel developer: don't install it. Port the pattern instead. A ~40-line service provider gives you the same thing:

// app/Providers/StatsdServiceProvider.php
$this->app->singleton(\DataDog\DogStatsd::class, fn () => new \DataDog\DogStatsd([
    'host'      => config('services.statsd.host', '127.0.0.1'),
    'port'      => config('services.statsd.port', 8125),
    'namespace' => config('services.statsd.namespace', 'app'),
    'tags'      => ['env' => app()->environment()],
]));

Your first use case is almost always request timing: emit a timing metric for every HTTP request plus a increment on error status codes, tagged by route and status. That single metric pays for the whole integration.

Implementation Patterns

Inject the client, never resolve it from the container. The bundle's service is a singleton; treat it the same way. Type-hint DogStatsd (or an interface you own) in constructors so tests can swap a null client.

final class OrderService
{
    public function __construct(private DogStatsd $statsd) {}

    public function place(Order $order): void
    {
        $this->statsd->increment('orders.placed', 1, ['channel' => $order->channel]);
        $start = microtime(true);
        // ... work ...
        $this->statsd->timing('orders.place_ms', (microtime(true) - $start) * 1000);
    }
}

Use terminable middleware for HTTP metrics. This is the Laravel analogue of the Symfony kernel-event listener the bundle expects you to wire up:

public function terminate(Request $request, Response $response): void
{
    $this->statsd->timing('http.request_ms', (microtime(true) - LARAVEL_START) * 1000, 1, [
        'route'  => optional($request->route())->getName() ?? 'unmatched',
        'method' => $request->method(),
        'status' => $response->getStatusCode(),
    ]);
}

Namespace by domain, tag by dimension. Put the stable part in the metric name (orders.placed) and the volatile part in tags (channel, region). This mirrors what the bundle's namespace config option does and keeps dashboards stable.

Emit from jobs and events, not controllers. Queue jobs, Event::listen handlers, and scheduled commands are where business metrics belong. Keep controllers to transport-level metrics only.

Batch and flush at the end of the request/command. The StatsD client buffers UDP packets. In a Symfony setup the bundle expects a terminate hook; in Laravel, flush from the same terminable middleware or a CommandFinished listener.

If you're genuinely on Symfony 2: register the bundle in AppKernel, add the srf_php_datadog_statsd block to config.yml, and inject the service ID. The config tree in Configuration.php is authoritative — the README is likely stale.

Gotchas and Tips

• UDP is fire-and-forget. Every call succeeds silently, including when the agent is down, the port is wrong, or the host is a typo. Debug by pointing at nc -ul 8125 (or a local statsd container) and watching for packets — not by adding try/catch, which will never fire.
• Archived means zero PHP 8 or Symfony 5+ support. The underlying client may use older signatures (positional $sampleRate, $tags as the fourth argument). If you copy usage examples from the bundle's docs into a modern client, argument order will bite you.
• Sampling changes semantics. increment('foo', 1, ['sample_rate' => 0.1]) sends 1/10th of events and the server scales them back. Fine for high-volume counters, wrong for anything that must be exact (billing, quota enforcement).
• Cardinality will explode your Datadog bill. Tagging by user_id, raw URL, or exception message is the classic mistake. Cap tag values — bucket status codes, normalize routes, drop query strings.
• Long-running processes leak. Octane workers and queue daemons don't recycle the container. If the client accumulates buffered metrics and nothing flushes, memory grows. Explicitly flush after each job.
• Test with a null client. Bind a no-op implementation of your own interface in testing so unit tests don't send UDP or require a running agent. This is the main extension point the bundle didn't give you.
• Swap the client, don't fight it. The bundle's only real value is the container wiring. In Laravel, the equivalent extension point is the singleton binding — replace it with a decorated client if you need retries, filtering, or a different backend.
• Don't build dashboards against metric names you can't change. Since the package is dead, treat any metric naming it suggests as your own convention and document it in one place (a Metrics constants class) before the first deploy.