Getting Started

Minimal Setup

Install the Bundle Requires the core auxmoney/opentracing-bundle first. Install via Composer:
```
composer require auxmoney/opentracing-bundle auxmoney/opentracing-bundle-jaeger
```

Enable the Bundle Add to config/bundles.php:

return [
    // ...
    Auxmoney\OpentracingBundle\OpentracingBundle::class => ['all' => true],
    Auxmoney\OpentracingBundle\Jaeger\JaegerBundle::class => ['all' => true],
];

Configure Environment Variables Set sampling strategy in .env (default: ConstSampler with true):

AUXMONEY_OPENTRACING_SAMPLER_CLASS=Jaeger\Sampler\ProbabilisticSampler
AUXMONEY_OPENTRACING_SAMPLER_VALUE="0.1"  # Sample 10% of requests

Verify Jaeger Integration Ensure your services.yaml includes the Jaeger tracer:

auxmoney_opentracing.tracer.class: Auxmoney\OpentracingBundle\Jaeger\Tracer\JaegerTracer

First Use Case Inject the tracer into a controller/service and start a span:

use OpenTracing\Span;
use OpenTracing\TracerInterface;

class MyController extends AbstractController {
    public function __construct(private TracerInterface $tracer) {}

    public function index(): Response {
        $span = $this->tracer->buildSpan('my-operation')->start();
        try {
            // Business logic here
            $span->setTag('http.method', 'GET');
        } finally {
            $span->finish();
        }
        return new Response('Tracing enabled!');
    }
}

Implementation Patterns

Core Workflows

Request Tracing Automatically traces HTTP requests via Symfony’s event system. Use KernelEvents::REQUEST to inject custom tags:

use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;

$eventDispatcher->addListener(KernelEvents::REQUEST, function (RequestEvent $event) {
    $span = $event->getRequest()->get('tracer')->buildSpan('http.request');
    $span->setTag('http.url', $event->getRequest()->getUri());
    $span->start();
    // ...
});

Database Operations Integrate with Doctrine via Doctrine\DBAL\Connection events:

$connection->getEventManager()->addListener(
    \Doctrine\DBAL\Connection::EVENT_QUERY,
    function ($eventArgs) use ($tracer) {
        $span = $tracer->buildSpan('db.query')->start();
        $span->setTag('db.query', $eventArgs->getSql());
        $span->finish();
    }
);

Microservice Communication Propagate trace context via HTTP headers (e.g., uber-trace-id):

$spanContext = $tracer->extract(
    \OpenTracing\FORMAT_HTTP_HEADERS,
    $request->headers->all()
);
$tracer->inject($spanContext, \OpenTracing\FORMAT_HTTP_HEADERS, $response->headers);

Custom Spans Create reusable span factories:

class SpanFactory {
    public function __construct(private TracerInterface $tracer) {}

    public function createDatabaseSpan(string $query): Span {
        $span = $this->tracer->buildSpan('db.query');
        $span->setTag('db.query', $query);
        return $span;
    }
}

Integration Tips

Symfony Flex: Use symfony/flex recipes for seamless installation:

composer require auxmoney/opentracing-bundle-jaeger --with-all-dependencies

PSR-18 Clients: Leverage HttpClientInterface for outbound HTTP tracing:

$client = $container->get('http_client');
$client->withOptions([
    'headers' => [
        'uber-trace-id' => $tracer->extract(
            \OpenTracing\FORMAT_HTTP_HEADERS,
            []
        )['uber-trace-id'] ?? ''
    ]
]);

Async Workers: Use OpenTracing\GlobalTracer for background jobs (e.g., Symfony Messenger):

$messageBus->dispatch(new MyMessage());
// Ensure GlobalTracer is set before dispatching.

Gotchas and Tips

Pitfalls

Sampler Misconfiguration
- Issue: Probabilistic sampler (ProbabilisticSampler) with 0.0 rate drops all traces.
- Fix: Validate AUXMONEY_OPENTRACING_SAMPLER_VALUE in .env:
```
AUXMONEY_OPENTRACING_SAMPLER_VALUE="0.01"  # Minimum 1% sampling
```
Trace Context Propagation
- Issue: Missing uber-trace-id headers break distributed tracing.
- Fix: Ensure headers are injected/extracted in middleware:
```
$tracer->inject($spanContext, \OpenTracing\FORMAT_HTTP_HEADERS, $response->headers);
```

Resource Leaks

Issue: Unfinished spans consume memory.

Fix: Use try-finally blocks or decorate services with SpanDecorator:

class SpanDecorator {
    public function __construct(private TracerInterface $tracer) {}

    public function __invoke(callable $service, ...$args) {
        $span = $this->tracer->buildSpan('service.call')->start();
        try {
            return $service(...$args);
        } finally {
            $span->finish();
        }
    }
}

Jaeger Agent Unreachable
- Issue: Traces fail silently if Jaeger agent is down.
- Fix: Configure retry logic or fallback to NullTracer:
```
auxmoney_opentracing.tracer.class: Auxmoney\OpentracingBundle\Jaeger\Tracer\FallbackJaegerTracer
```

Debugging Tips

Enable Debug Mode Add to config/packages/dev/opentracing.yaml:
```
auxmoney_opentracing:
    debug: true
```
Logs spans to var/log/dev.log.
Inspect Traces Use Jaeger UI (http://localhost:16686) to verify spans. Filter by:
- operation_name (e.g., http.request).
- tags.http.method (e.g., GET).

Common Tags Add metadata to spans for better observability:

$span->setTag('user.id', $user->id);
$span->setTag('component', 'auth-service');

Extension Points

Custom Samplers Extend Jaeger\Sampler\SamplerInterface for dynamic sampling:

class CustomSampler implements SamplerInterface {
    public function isSampled(spanContext $context): bool {
        return rand(0, 100) < 5; // 5% sampling
    }
}

auxmoney_opentracing.sampler.class: App\Sampler\CustomSampler

Span Processors Add custom logic to spans before they’re sent to Jaeger:

$processor = new class implements SpanProcessorInterface {
    public function onFinish(Span $span) {
        $span->setTag('custom.metric', 'value');
    }
};
$tracer->registerSpanProcessor($processor);

Jaeger Client Configuration Override default Jaeger client settings:

auxmoney_opentracing.jaeger.client:
    host: 'jaeger-collector'
    port: 6831
    sampling: { type: 'const', param: 1 }

Opentracing Bundle Jaeger Laravel Package