Pinba Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require cedriclombardot/pinba-bundle:dev-master
   

   Register the bundle in app/Kernel.php:

   $bundles = [
       // ...
       new CedricLombardot\PinbaBundle\CedricLombardotPinbaBundle(),
   ];
   

2. Basic Configuration Ensure config.yml includes the bundle’s configuration (if needed):

   pinba:
       script_name_pattern: "{PATH_INFO}"  # Default; adjust as needed
   

3. First Use Case

   • Enable Pinba in Symfony: The bundle automatically hooks into Symfony’s HTTP kernel to log requests to Pinba.
   • Verify Pinba Server: Ensure a Pinba collector (e.g., pinba_collector) is running to receive logs.
   • Test: Trigger a request and check Pinba’s UI (e.g., http://localhost:8080/pinba) for logged data.

Implementation Patterns

Core Workflows

1. Request Logging The bundle intercepts Symfony’s onKernelRequest event to log request metadata (URI, HTTP method, headers, etc.) to Pinba. No manual instrumentation is required for basic usage.

2. Custom Script Naming Override the default script name (e.g., {PATH_INFO}) via config.yml to include dynamic segments:

   pinba:
       script_name_pattern: "api/{_route}"  # Uses Symfony’s routing syntax
   

   Use case: Group API endpoints by route names for better visualization.

3. Database Query Logging (Propel) Replace Propel’s PDO with PinbaPropelPDO to log SQL queries:

   propel:
       dbal:
           connections:
               default:
                   classname: CedricLombardot\PinbaBundle\Propel\PinbaPropelPDO
                   # ... rest of config
   

   Use case: Track slow Propel queries in Pinba’s UI.

4. Manual Instrumentation For custom logic (e.g., background jobs), manually log events:

   use CedricLombardot\PinbaBundle\Pinba\Pinba;
   
   Pinba::log('custom.event', [
       'data' => 'value',
       'context' => ['key' => 'value']
   ]);
   

Integration Tips

• Symfony Events: Extend functionality by subscribing to events (e.g., kernel.request):

  $eventDispatcher->addListener('kernel.request', function () {
      Pinba::log('custom.metric', ['value' => 42]);
  });
  

• Environment-Specific Config: Disable Pinba in non-production environments:

  # config_prod.yml
  pinba:
      enabled: true
  

  # config_dev.yml
  pinba:
      enabled: false
  

• Pinba Collector: Use Docker or a pre-built collector (e.g., pinba_collector:latest) for local development.

Gotchas and Tips

Pitfalls

1. Missing Collector

   • Issue: Logs appear in Symfony’s logs but not in Pinba’s UI.
   • Fix: Ensure the Pinba collector (e.g., pinba_collector) is running and configured to listen on the correct UDP port (default: 8126).

2. PDO Override Conflicts

   • Issue: Propel’s PinbaPropelPDO may conflict with other PDO wrappers (e.g., Doctrine’s).
   • Fix: Ensure only one PDO wrapper is active per connection. For mixed stacks, consider using a single ORM or custom instrumentation.

3. Script Name Collisions

   • Issue: Dynamic script_name_pattern may generate duplicate or ambiguous names.
   • Fix: Use unique identifiers (e.g., {_route}.{_controller}) or sanitize patterns:

     pinba:
         script_name_pattern: "route.{{ _route|replace({' ': '_'}) }}"
     

4. Performance Overhead

   • Issue: Excessive logging (e.g., every SQL query) may impact performance.
   • Fix: Use conditional logging or sample queries:

     if (rand(0, 100) < 10) { // 10% sample
         Pinba::log('slow.query', ['query' => $sql]);
     }
     

Debugging

• Log Level: Increase Symfony’s log level to debug to see Pinba-related events:

  monolog:
      handlers:
          main:
              level: debug
  

• UDP Packet Inspection: Use tcpdump to verify Pinba packets are sent:

  tcpdump -i any -n udp port 8126
  

• Bundle Debugging: Enable debug mode in CedricLombardotPinbaBundle by extending the bundle class or using a debug flag in config.

Extension Points

1. Custom Data Collectors Extend the bundle’s PinbaCollector to add custom metrics:

   class CustomPinbaCollector extends \CedricLombardot\PinbaBundle\Pinba\PinbaCollector
   {
       public function collectCustomData()
       {
           $this->log('custom.metric', ['value' => $this->getCustomValue()]);
       }
   }
   

   Register it in services.yml:

   services:
       pinba.collector:
           class: AppBundle\Pinba\CustomPinbaCollector
   

2. Event Subscribers Hook into Symfony’s events to enrich Pinba data:

   class PinbaSubscriber implements EventSubscriberInterface
   {
       public function onKernelRequest(GetResponseEvent $event)
       {
           Pinba::log('user.action', ['user_id' => $event->getRequest()->get('user_id')]);
       }
       // ...
   }
   

3. Configuration Overrides Dynamically adjust Pinba behavior via runtime config:

   $container->get('pinba')->setScriptNamePattern('dynamic.{_route}');