Statsd Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require birkof/statsd-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Birkof\StatsdBundle\BirkofStatsdBundle::class => ['all' => true],
   ];
   

2. Configure in config/packages/birkof_statsd.yaml

   birkof_statsd:
       host: 'localhost'
       port: 8125
       prefix: 'myapp.'
       namespace: 'default'
   

3. First Metric Inject StatsdClientInterface and use:

   use Birkof\StatsdBundle\Client\StatsdClientInterface;
   
   class MyController
   {
       public function __construct(private StatsdClientInterface $statsd) {}
   
       public function index()
       {
           $this->statsd->increment('user.visits');
           $this->statsd->timing('user.visit.duration', 150); // ms
       }
   }
   

4. Verify Check StatsD UI (e.g., Grafana + Prometheus) or use netcat:

   nc -ul 8125
   

Implementation Patterns

Core Workflows

1. Event-Driven Metrics Bind metrics to Symfony events (e.g., kernel.request):

   # config/packages/birkof_statsd.yaml
   birkof_statsd:
       listeners:
           kernel.request: ['user.visits']
           kernel.exception: ['errors.total']
   

   Or programmatically:

   $this->statsd->addEventListener('kernel.request', 'user.visits');
   

2. Contextual Metrics Use tags (via StatsdClientInterface):

   $this->statsd->increment('user.visits', ['source' => 'web', 'user_id' => 123]);
   

3. Timing Critical Paths Measure execution time:

   $this->statsd->timing('api.response.time', $this->stopwatch->lap());
   

4. Gauge for Dynamic Values Track real-time metrics (e.g., queue size):

   $this->statsd->gauge('queue.size', count($queue));
   

Integration Tips

• Dependency Injection Prefer constructor injection over service locator:

  public function __construct(private StatsdClientInterface $statsd) {}
  

• Configuration Overrides Use environment variables for dynamic config:

  birkof_statsd:
      host: '%env(STATSD_HOST)%'
      port: '%env(int:STATSD_PORT)%'
  

• Async vs. Sync StatsD is UDP by default (async). For reliability, consider:

  • Retry logic for critical metrics.
  • Fallback to a local cache (e.g., Redis) if StatsD is down.

• Metric Naming Use a consistent prefix (e.g., app.) and avoid special chars:

  $this->statsd->increment('app.user.auth.success');
  

Gotchas and Tips

Pitfalls

1. UDP Packet Loss StatsD drops packets silently. Mitigate by:

   • Using a higher port (e.g., 8125 is default but may be blocked).
   • Running a local StatsD instance (e.g., statsd Docker container) to buffer metrics.

2. Namespace Collisions Ensure prefix in config is unique to your app to avoid mixing metrics with others.

3. Event Listener Order Metrics bound to events fire after the event is dispatched. For pre-event metrics, use a custom listener:

   $dispatcher->addListener('kernel.request', function () {
       $this->statsd->increment('request.started');
   });
   

4. Deprecated Methods Avoid StatsdClient (old class). Use StatsdClientInterface for type safety.

Debugging

1. Check Connection Test StatsD connectivity:

   telnet localhost 8125
   

   Or use nc to monitor traffic:

   nc -ul 8125 | strings
   

2. Log Metrics Locally Temporarily log metrics to monolog for debugging:

   birkof_statsd:
       debug: true
   

3. Common Errors

   • Connection refused: StatsD server not running.
   • No metrics appearing: Check prefix and namespace in config.
   • High latency: Ensure StatsD is not overloaded (default flush interval: 1s).

Extension Points

1. Custom Metric Types Extend StatsdClientInterface to add custom methods:

   $this->statsd->custom('app.custom.metric', $value);
   

2. Dynamic Prefixes Override the prefix per request:

   $this->statsd->setPrefix("app.{$request->get('env')}.");
   

3. StatsD Backend Swap Replace the underlying client (e.g., for testing):

   services:
       Birkof\StatsdBundle\Client\StatsdClientInterface: '@test.statsd_client'
   

4. Batch Processing For high-volume apps, batch metrics before sending:

   $this->statsd->flush(); // Force send buffered metrics