Opentracing Bundle Doctrine Dbal Laravel Package

Getting Started

Minimal Setup

1. Prerequisite: Install the core auxmoney/opentracing-bundle via Composer:

   composer require auxmoney/opentracing-bundle
   

2. Add this bundle:

   composer require auxmoney/opentracing-bundle-doctrine-dbal
   

   For Symfony 4+, enable it in config/bundles.php:

   Auxmoney\OpentracingDoctrineDBALBundle\OpentracingDoctrineDBALBundle::class => ['all' => true],
   

   For Symfony 3.x, add to AppKernel.php.

3. Verify Configuration: Ensure OpentracingBundle is properly configured (e.g., tracer setup in config/packages/opentracing.yaml).

First Use Case

Run a DBAL query to see automatic tracing:

use Doctrine\DBAL\Connection;

// In a controller or service:
$connection = $this->getDoctrine()->getConnection();
$stmt = $connection->executeQuery('SELECT * FROM users WHERE id = :id', ['id' => 1]);
$results = $stmt->fetchAll();

Check your tracing backend (e.g., Jaeger, Zipkin) for a new span with tags like db.statement and db.parameters.

Implementation Patterns

Core Workflow

1. Automatic Span Creation:

   • The bundle decorates Doctrine\DBAL\Connection and Doctrine\DBAL\Driver\Statement to inject OpenTracing spans.
   • Spans are created for every query execution, including:
     • executeQuery()
     • executeStatement()
     • fetchAll(), fetchOne(), etc.

2. Tagging Strategy: Configure via environment variables or config/packages/opentracing.yaml:

   auxmoney_opentracing:
       doctrine:
           tag_full_statement: true
           tag_parameters: true
           tag_row_count: false  # Use cautiously (see Limitations)
           tag_user: true
   

   Tags added to spans:

   • db.statement: Raw SQL (if enabled).
   • db.parameters: Bound parameters (sanitized).
   • db.row_count: Affected rows (driver-dependent).
   • db.user: Database username.

3. Integration with ORM:

   • Works seamlessly with Doctrine ORM (e.g., EntityManager::createQuery()).
   • Spans reflect the underlying DBAL queries.

4. Transaction Handling:

   • Spans are nested under the active trace context.
   • Supports in-flight transactions (see #11).

Advanced Patterns

• Custom Span Naming: Override span names via a subscriber or event listener:

  use Auxmoney\OpentracingDoctrineDBALBundle\Event\SpanEvent;
  
  $eventDispatcher->addListener(SpanEvent::NAME, function (SpanEvent $event) {
      $event->setSpanName('custom.query.name');
  });
  

• Conditional Tracing: Disable tracing for specific queries:

  $connection->getWrappedConnection()->setTracingEnabled(false);
  $stmt = $connection->executeQuery('SELECT * FROM sensitive_data');
  

• Multi-Database Setups: Configure per-connection tracing via ConnectionOptions:

  $connection = DriverManager::getConnection([
      'url' => 'mysql://user:pass@localhost/db',
      'wrapperClass' => \Auxmoney\OpentracingDoctrineDBALBundle\DBAL\Connection::class,
      'wrapperOptions' => [
          'tracing' => [
              'tag_full_statement' => false,
          ],
      ],
  ]);
  

Gotchas and Tips

Pitfalls

1. Row Count Limitations:

   • db.row_count may return incorrect values for SELECT queries (driver-dependent).
   • Workaround: Disable (tag_row_count: false) or handle manually:

     $rowCount = $stmt->rowCount();
     $span->setTag('db.row_count', $rowCount);
     

2. Parameter Sanitization:

   • Sensitive parameters (e.g., passwords) are not masked by default.
   • Fix: Use a custom ParameterConverter or filter parameters:

     $event->setParameters(array_filter($event->getParameters(), fn($key) => !str_starts_with($key, 'password')));
     

3. Performance Overhead:

   • Tracing adds minimal overhead (~1-5ms per query). Monitor in production.

4. Symfony 6+ Compatibility:

   • Ensure OpentracingBundle v1.x is used (see #23).

Debugging Tips

• Missing Spans:

  • Verify the core OpentracingBundle is active and configured.
  • Check for errors in var/log/dev.log or stderr.

• Incorrect Tags:

  • Use bin/console debug:container auxmoney_opentracing.doctrine to verify configuration.
  • Override tags via a subscriber if defaults are insufficient.

• Driver-Specific Issues:

  • Test with PDO and native drivers (e.g., pdo_mysql, pdo_pgsql).
  • For SQLite, rowCount() may return 0 for SELECT queries (expected behavior).

Extension Points

1. Custom Tagging: Extend TracingStatement to add domain-specific tags:

   use Auxmoney\OpentracingDoctrineDBALBundle\DBAL\TracingStatement;
   
   class CustomTracingStatement extends TracingStatement {
       public function __construct(Statement $statement, array $options) {
           parent::__construct($statement, $options);
           $this->addTag('custom.tag', 'value');
       }
   }
   

   Register via DI or override the bundle’s factory.

2. Span Lifecycle Control: Use SpanEvent to hook into span creation/finishing:

   $dispatcher->addListener(SpanEvent::START, function (SpanEvent $event) {
       $event->getSpan()->setBaggageItem('custom.baggage', 'value');
   });
   

3. Testing: Mock the tracer in tests:

   $this->container->set('opentracing.tracer', $this->createMock(TracerInterface::class));
   

   Use OpentracingTestTrait from the core bundle for assertions.

Configuration Quirks

• Environment Variables: Prefix with AUXMONEY_OPENTRACING_DOCTRINE_ (e.g., AUXMONEY_OPENTRACING_DOCTRINE_TAG_FULL_STATEMENT=true). Note: Boolean values accept true/false, on/off, or 1/0.

• Flex Auto-Configuration: If using Symfony Flex, ensure config/packages/opentracing.yaml exists or the bundle will auto-configure with defaults.

• Doctrine Event Listeners: Avoid conflicts with other DBAL listeners (e.g., logging, profiling). Order matters:

  # config/packages/doctrine.yaml
  dbal:
      event_listeners:
          tracing: [auxmoney_opentracing_dbal_listener, 16] # Lower priority = earlier execution