Opentracing Bundle Guzzle Laravel Package

Getting Started

Minimal Setup

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

   composer require auxmoney/opentracing-bundle
   

2. Add the Guzzle extension:

   composer require auxmoney/opentracing-bundle-guzzle
   

3. Enable the bundle (Symfony 4+):

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

   For Symfony Flex, no manual configuration is needed.

First Use Case

Inject tracing into a Guzzle HTTP client automatically. Example:

use GuzzleHttp\Client;

// Your existing client (will be auto-enhanced)
$client = new Client(['base_uri' => 'https://api.example.com']);

// Send a request - tracing headers are injected automatically
$response = $client->get('/endpoint');

Implementation Patterns

1. Automatic Middleware Injection

• The bundle automatically decorates all GuzzleHttp\Client instances with tracing middleware via a compiler pass.
• No manual middleware setup required for standard clients.

2. Custom Client Integration

For factory-created clients (e.g., via GuzzleHttp\ClientFactory), explicitly decorate them:

use Auxmoney\OpentracingGuzzleBundle\Middleware\TracingMiddleware;

// Create client with tracing middleware
$client = new Client([
    'handler' => HandlerStack::create([
        new TracingMiddleware(),
        // Other middleware...
    ]),
]);

3. Span Nesting & Context Propagation

• Parent spans (e.g., from Symfony controllers) are automatically propagated to child spans (HTTP requests).
• Useful for distributed tracing across microservices.

4. Async Requests (Promises)

• Supports Guzzle Promises with onRejected handlers for error tracing.
• Example:

  $promise = $client->getAsync('/endpoint')
      ->then(function ($response) { /* ... */ })
      ->otherwise(function ($exception) { /* Tracing context preserved */ });
  

5. Conditional Tracing

Disable tracing for specific clients by excluding middleware:

$client = new Client([
    'handler' => HandlerStack::create([
        // Skip TracingMiddleware for this client
    ]),
]);

Gotchas and Tips

Pitfalls

1. Missing Core Bundle:

   • This package requires auxmoney/opentracing-bundle. Install it first or tracing won’t work.
   • Error: Class 'Auxmoney\OpentracingBundle\Tracer' not found.

2. Guzzle Version Mismatch:

   • The bundle supports Guzzle 6/7. Using an unsupported version may break middleware injection.
   • Fix: Update Guzzle or check the changelog for compatibility.

3. Factory-Created Clients:

   • Clients created via factories (e.g., GuzzleHttp\ClientFactory) won’t auto-decorate unless manually configured (see Implementation Patterns).

4. Span Nesting Issues:

   • If spans aren’t nested correctly, verify:
     • The parent span (e.g., from a Symfony controller) is active when the request is made.
     • No custom middleware is removing or overriding tracing headers.

5. Error Tracing:

   • Async errors (onRejected) may not propagate tracing context if not handled explicitly. Use:

     $promise->otherwise(function ($exception) use ($tracer) {
         $tracer->getActiveSpan()->log(['error' => $exception->getMessage()]);
     });
     

Debugging Tips

• Check Active Spans:

  $tracer = $container->get('opentracing.tracer');
  $activeSpan = $tracer->getActiveSpan();
  

• Log Headers: Inspect outgoing requests to verify tracing headers (e.g., uber-trace-id):

  $client->get('/endpoint', ['debug' => true]);
  

• Disable Tracing Temporarily: Use a feature flag or environment variable to bypass tracing during development:

  if (!$this->isTracingEnabled()) {
      $client = new Client(['handler' => new HandlerStack()]);
  }
  

Extension Points

1. Custom Span Tags: Add metadata to spans via middleware:

   $span->setTag('http.url', $request->getUri());
   $span->setTag('http.method', $request->getMethod());
   

2. Header Overrides: Modify tracing headers before injection:

   $middleware = new TracingMiddleware();
   $middleware->setHeaderName('custom-trace-id', 'your-value');
   

3. Span Naming: Override default span names (e.g., for API endpoints):

   $span->setOperationName('api.payment.process');
   

4. Integration with Other Bundles: Combine with Sentry or Monolog to correlate traces with logs/errors:

   $span->setTag('logger', 'monolog');