Opentracing Bundle Emagtechlabs Rabbitmqbundle Laravel Package

Getting Started

Minimal Steps

1. Prerequisites Check:

   • Ensure you have auxmoney/opentracing-bundle-core installed and configured in your Symfony project.
   • Confirm you are using emag-tech-labs/rabbitmq-bundle (version ^2.0).

2. Installation:

   composer require auxmoney/opentracing-bundle-emagtechlabs-rabbitmqbundle
   

3. Enable the Bundle: Add to config/bundles.php (Symfony 4+):

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

4. First Use Case:

   • Publish a message via eMAGTechLabs/RabbitMqBundle producer.
   • Consume the message via a configured consumer.
   • Verify tracing headers are automatically propagated and spans are created in your OpenTracing-compatible backend (e.g., Jaeger, Zipkin).

Implementation Patterns

Usage Patterns

1. Automatic Tracing:

   • The bundle automatically decorates RabbitMQ producers/consumers, injecting OpenTracing spans for each message lifecycle (publish/consume).
   • No manual instrumentation required for basic use.

2. Header Propagation:

   • Tracing context (e.g., uber-trace-id, baggage) is automatically extracted from incoming messages and injected into outgoing messages.
   • Works seamlessly with distributed tracing across microservices.

3. Integration with OpenTracingBundle:

   • Leverages auxmoney/opentracing-bundle-core for global tracing configuration (e.g., Tracer setup, middleware).
   • Example workflow:

     // Producer (automatically traced)
     $this->rabbitMqProducer->publish('exchange', 'routing_key', $message);
     
     // Consumer (automatically traced)
     $this->rabbitMqConsumer->consume(function (Message $message) {
         // Business logic here
     });
     

4. Custom Span Naming:

   • Override default span names by extending the bundle’s decorator or configuring the underlying OpentracingBundle-core.

5. Error Handling:

   • Spans are automatically tagged with error=true if exceptions occur during message processing.

Workflows

• Microservice Communication: Use the bundle to trace requests flowing through RabbitMQ between services (e.g., order-service → payment-service).
• Async Task Tracking: Track long-running background jobs (e.g., PDF generation, report processing) with spans tied to their RabbitMQ messages.
• Debugging: Correlate logs, metrics, and traces using the propagated trace_id across services.

Integration Tips

1. With Symfony Messenger: If using symfony/messenger + emag-tech-labs/rabbitmq-bundle, ensure the bundle’s decorators are loaded after Messenger’s RabbitMQ transport.
2. With Other Tracers: Configure OpentracingBundle-core to use your preferred tracer (e.g., Jaeger, Zipkin) via config/packages/opentracing.yaml.
3. Testing: Mock the tracer in unit tests to avoid real network calls:

   $this->tracer = $this->createMock(\OpenTracing\TracerInterface());
   $this->container->set('opentracing.tracer', $this->tracer);
   

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • This package is abandoned in favor of auxmoney/OpentracingBundle-amqplib-RabbitMq. Migrate if possible.
   • The underlying eMAGTechLabs/RabbitMqBundle is also abandoned; consider alternatives like php-amqplib or symfony/messenger with AMQP transport.

2. Configuration Overrides:

   • The bundle does not expose configuration options. Customization requires extending the decorator or patching the core bundle.
   • Example: To change span names, override the RabbitMqProducerDecorator or RabbitMqConsumerDecorator classes.

3. Header Conflicts:

   • RabbitMQ messages have a 128-byte header limit. Large tracing headers (e.g., extensive baggage) may truncate or fail.
   • Mitigation: Limit baggage keys or use a separate header for trace context.

4. Symfony 5+ Compatibility:

   • Tested up to Symfony 4.4. Later versions may require manual adjustments due to dependency constraints (e.g., emag-tech-labs/rabbitmq-bundle).

5. Consumer Lifecycle:

   • Spans are created per message, not per consumer instance. Ensure consumers are stateless or handle span cleanup explicitly.

Debugging

1. Missing Spans:

   • Verify the tracer is injected into the bundle:

     bin/console debug:container opentracing.tracer
     

   • Check for errors in var/log/dev.log or enable debug mode for OpentracingBundle-core.

2. Header Propagation Issues:

   • Use a tool like rabbitmqctl list_queues or a packet sniffer to inspect message headers.
   • Test with a minimal message:

     $message = new Message(['traceparent' => '00-abc123...'], ['content_type' => 'text/plain']);
     

3. Performance Overhead:

   • Profile with Xdebug or Blackfire to measure tracing impact. Disable in production if needed via OPENTRACING_ENABLED=0.

Tips

1. Span Context:

   • Explicitly set span tags for critical operations:

     $span->setTag('message.type', $message->getRoutingKey());
     

2. Custom Propagation:

   • Extend the bundle to support additional headers (e.g., x-request-id):

     // In a custom decorator
     $propagator = new CompositeTextMapAdapter([...]);
     $propagator->inject($span->getContext(), $headers);
     

3. Legacy Systems:

   • For non-Symfony consumers, manually extract headers and inject them into the tracer:

     $context = $propagator->extract(
         \OpenTracing\FORMAT_TEXT_MAP,
         $message->getHeaders()
     );
     $tracer->scopeManager()->activate($context, function() {
         // Process message
     });
     

4. Monitoring:

   • Use OpenTracing-compatible tools (e.g., Jaeger UI) to visualize RabbitMQ message flows:
     • Filter spans by component=rabbitmq or span.kind=producer/consumer.

5. Fallback for Errors:

   • Implement a fallback tracer in OpentracingBundle-core to log errors when tracing fails:

     # config/packages/opentracing.yaml
     opentracing:
         tracer:
             fallback: true