Statsdbundle Laravel Package

Getting Started

1. Install: composer require tarjei/statsdbundle. This is a Symfony2-era bundle, so expect it to pull in an older StatsD client dependency and to target symfony/symfony ^2.x; on a modern app you'll likely need to register the service manually rather than via Flex.
2. Register the bundle (legacy AppKernel.php):

   // app/AppKernel.php
   public function registerBundles()
   {
       $bundles = [
           // ...
           new Tarjei\StatsdBundle\TarjeiStatsdBundle(),
       ];
       return $bundles;
   }
   

3. Configure the connection once in app/config/config.yml (check the bundle's DependencyInjection/Configuration.php for the exact tree — typically host/port/namespace):

   tarjei_statsd:
       host: 127.0.0.1
       port: 8125
       namespace: myapp
   

   For real environments, point at your StatsD/Telegraf/Graphite endpoint via parameters.yml and environment-specific overrides.
4. Look first at Resources/config/services.xml (or .yml) to confirm the service ID (usually statsd or tarjei_statsd.client) and its class. That tells you which methods are actually exposed (increment, decrement, timing, gauge, and possibly updateCount, updateStats).
5. First use case: inject the statsd client into a service and drop a counter in your request lifecycle:

   $statsd->increment('user.signup');
   $statsd->timing('db.query', $ms);
   

Implementation Patterns

• Don't depend on the vendor class directly. Wrap the injected client in a small application-level Metrics service (methods like countSignup(), timeQuery()). That isolates your code from both the StatsD client and the bundle, and gives you one place to switch in a no-op implementation for tests/local dev.
• Request/response instrumentation via a kernel event subscriber is the highest-value integration. Time the whole request in kernel.request/kernel.terminate, and emit per-route names, e.g. $statsd->timing("request.{$route}", $ms). Avoid emitting route names with high-cardinality IDs — normalize first.
• Counters around business events, not technical details: sign-ups, orders placed, failed payments, cache hits/misses. These are the metrics you'll actually alert on.
• Timers around discrete blocks using microtime(true) deltas — the client typically takes milliseconds. Wrap this in a helper so you're not repeating boilerplate:

  $start = microtime(true);
  $result = $this->doWork();
  $this->metrics->timing('work.duration', (microtime(true) - $start) * 1000);
  

• Namespace per app/environment (myapp.prod, myapp.staging) so dashboards don't cross-contaminate. Configure this at the bundle level rather than prefixing every metric name in code.
• Gauges for current state (queue depth, connection count) — emit them from a cron/console command, not on every request, since gauge semantics are "last value wins."
• Testing: point the client at a local StatsD container (docker run -p 8125:8125/udp statsd) and assert on the emitted line, or swap in a mock for unit tests. Because UDP is fire-and-forget, you need an explicit sink (like nc -ul 8125) to verify what's actually sent.
• Console commands and workers benefit from the same counters — reuse the metrics service rather than re-wiring the client.

Gotchas and Tips

• UDP is fire-and-forget. If the StatsD daemon is down, misconfigured, or the host/port is wrong, there is no error — packets are silently dropped. Always verify with a listener on the configured port before trusting dashboards.
• Symfony 4+/Flex compatibility is not assumed. This bundle predates modern service autowiring. On modern Symfony, define the client service yourself and skip the bundle, or expect to patch services.xml — the bundle will not be discovered by Flex.
• Silent misconfiguration is the #1 debugging trap. Check host, port (default 8125), and namespace first; then confirm traffic with tcpdump -i lo udp port 8125 or a UDP listener. Metric names appearing without your namespace usually mean the namespace config didn't load.
• Timing units are milliseconds. Sending seconds is a common mistake and skews graphs by 1000x. Keep the conversion in one helper.
• High cardinality kills dashboards. Never interpolate user IDs, request IDs, or raw URLs into metric names. Bucket or normalize.
• Short-lived PHP requests still flush immediately (each call sends a UDP packet), so no shutdown hook is needed — but it also means high-frequency loops generate real per-call network overhead. Batch where you can, or use counters aggregated in-process where the client supports it.
• Extension points: override the bundle's service definition in your own services.yml (same service ID) to substitute a different client, decorate it for logging in dev, and use a no-op subclass in test — this is the safest way to neutralize metrics in test suites.
• Check the client version before relying on tags/labels. Older StatsD clients only support a flat metric.name — no tag syntax. If you need tags, verify against the underlying client's method signatures.