Opentracing Bundle Php Http Httplug Bundle Laravel Package

Getting Started

Minimal Setup

1. Prerequisites: Ensure you have auxmoney/opentracing-bundle-core and php-http/httplug-bundle installed.

   composer require auxmoney/opentracing-bundle-core php-http/httplug-bundle
   

2. Install the bundle:

   composer require auxmoney/opentracing-bundle-php-http-httplug-bundle
   

   • For Symfony Flex, the bundle auto-enables.
   • For manual setup (Symfony 3+):

     // config/bundles.php
     Auxmoney\OpentracingHttplugBundle\OpentracingHttplugBundle::class => ['all' => true],
     

3. First Use Case: Send an HTTP request via Httplug (e.g., Guzzle, Symfony HTTP client) and verify tracing headers are injected automatically. Example:

   use Http\Client\Common\Plugin\PluginClient;
   use Http\Client\Common\PluginClientFactory;
   
   $client = $container->get('httplug.client'); // Auto-injected with tracing plugin
   $response = $client->request('GET', 'https://api.example.com');
   

Key Files to Review

• Bundle Configuration: config/packages/auxmoney_opentracing.yaml (if extended).
• Compiler Pass: src/DependencyInjection/Compiler/OpentracingHttplugPass.php (how plugins are injected).
• Plugin: src/Plugin/OpentracingPlugin.php (core header injection logic).

Implementation Patterns

Core Workflow

1. Automatic Plugin Injection: The bundle decorates PluginClientFactory during container compilation, injecting OpentracingPlugin into all Httplug clients. No manual client configuration is needed.

2. Tracing Headers: Outgoing requests automatically include OpenTracing headers (uber-trace-id, x-request-id, etc.). Example:

   // Headers are injected transparently; no manual setup required.
   $response = $client->request('GET', 'https://api.example.com');
   

3. Custom Clients: For non-container-managed clients (e.g., created in services), manually add the plugin:

   use Auxmoney\OpentracingHttplugBundle\Plugin\OpentracingPlugin;
   
   $client = new PluginClient(
       $baseClient,
       [new OpentracingPlugin($tracer)] // Inject tracer from OpentracingBundle
   );
   

Integration Tips

• Symfony HTTP Client: If using Symfony’s HTTP client (built on Httplug), the bundle works out-of-the-box. Example:

  $response = $this->httpClient->request('GET', 'https://api.example.com');
  

• Testing: Mock the OpentracingPlugin to verify header injection:

  $plugin = new OpentracingPlugin($mockTracer);
  $this->assertArrayHasKey('uber-trace-id', $plugin->getHeaders($request));
  

• Conditional Tracing: Disable tracing for specific clients by excluding the plugin:

  # config/packages/httplug.yaml
  httplug.client.my_client:
      factory: ['@httplug.client_factory', 'createClient']
      plugins: [] # Exclude OpentracingPlugin
  

• Custom Headers: Extend OpentracingPlugin to add/override headers:

  class CustomOpentracingPlugin extends OpentracingPlugin
  {
      public function getHeaders(RequestInterface $request): array
      {
          $headers = parent::getHeaders($request);
          $headers['x-custom-header'] = 'value';
          return $headers;
      }
  }
  

Gotchas and Tips

Pitfalls

1. Missing Dependencies:

   • Forgetting to install auxmoney/opentracing-bundle-core or php-http/httplug-bundle will cause failures. Verify with:

     composer why auxmoney/opentracing-bundle-core
     

2. Symfony Version Mismatch:

   • The bundle supports Symfony 5.4+ and 6.x. Older versions (e.g., 4.4) may require downgrading to v0.1.1.
   • Check composer.json for supported versions.

3. Plugin Order:

   • If other plugins modify headers (e.g., authentication), ensure OpentracingPlugin runs last to avoid header corruption. Reorder in PluginClientFactory:

     $client = new PluginClient($baseClient, [
         new AuthPlugin(),
         new OpentracingPlugin($tracer), // Last
     ]);
     

4. Tracer Unavailability:

   • If the OpenTracing tracer isn’t initialized (e.g., in tests), the plugin silently skips header injection. Add a guard:

     if (!$this->tracer->isActive()) {
         return [];
     }
     

Debugging

• Verify Headers: Log outgoing requests to confirm headers:

  $client->getEmitter()->attach(
      function (RequestInterface $request) {
          error_log('Headers: ' . print_r($request->getHeaders(), true));
      }
  );
  

• Check Tracer: Ensure the tracer is active:

  $this->tracer->inject(
      $spanContext,
      'http_headers',
      $carrier = []
  );
  $this->assertNotEmpty($carrier);
  

• Compiler Pass Issues: If the plugin isn’t injected, clear the cache and check for errors:

  php bin/console cache:clear
  php bin/console debug:container httplug.client | grep OpentracingPlugin
  

Extension Points

1. Custom Plugin: Override OpentracingPlugin to modify behavior (e.g., header naming):

   class CustomPlugin extends OpentracingPlugin
   {
       protected function getTraceIdHeader(): string
       {
           return 'x-custom-trace-id'; // Override default
       }
   }
   

2. Dynamic Header Injection: Conditionally inject headers based on request attributes:

   public function getHeaders(RequestInterface $request): array
   {
       if (!$request->hasAttribute('skip_tracing')) {
           return parent::getHeaders($request);
       }
       return [];
   }
   

3. Span Naming: Customize span names for specific endpoints:

   $this->tracer->startSpan('custom-span-name')->withTag('http.url', $request->getUri());
   

Configuration Quirks

• No YAML Config: The bundle requires zero configuration, but you can disable it by removing the compiler pass (not recommended).

• Flex Auto-Enable: If using Symfony Flex, ensure auto-config and auto-register are enabled in config/bundles.php.

• PHP 8 Attributes: The bundle uses PHP 8 features (e.g., constructor property promotion). Downgrade to v0.1.1 for PHP 7.4.

```markdown
### Pro Tips
1. **Performance**:
   Header injection adds minimal overhead (~1ms per request). Benchmark with:
   ```bash
   php bin/console debug:autowiring Http\Client\Common\PluginClient

2. Distributed Tracing: Pair with Jaeger or Zipkin for visualization. Example Jaeger setup:

   # config/packages/auxmoney_opentracing.yaml
   auxmoney_opentracing:
       exporter: jaeger
       jaeger:
           agent_host: localhost
           agent_port: 6831
   

3. Testing: Use OpentracingBundle's test utilities to mock tracers:

   $mockTracer = $this->createMock(TracerInterface::class);
   $mockTracer->method('inject')->willReturn([]);
   $plugin = new OpentracingPlugin($mockTracer);