Instana Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require cedricziel/instana-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       CedricZiel\InstanaBundle\InstanaBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config and adjust instana.yaml:

   php artisan vendor:publish --tag=instana:config
   

   Update with your Instana agent details (host, port, token):

   instana:
       agent:
           host: "your-instana-agent-host"
           port: 42699
           token: "your-instana-token"
   

3. First Use Case Enable tracing for a controller method:

   use OpenTracing\Tracer;
   use OpenTracing\Span;
   
   class ExampleController extends AbstractController
   {
       public function __construct(private Tracer $tracer) {}
   
       public function index(): Response
       {
           $span = $this->tracer->buildSpan('example.index')->start();
           try {
               // Your logic here
               return $this->json(['success' => true]);
           } finally {
               $span->finish();
           }
       }
   }
   

Implementation Patterns

Core Integration Workflows

1. Automatic Instrumentation The bundle auto-instruments:

   • Doctrine queries (via Doctrine\DBAL\Connection events).
   • Symfony events (via EventDispatcher).
   • Controller resolution (via ArgumentResolver/ControllerResolver).

   Example: Enable query logging in config/instana.yaml:

   instana:
       doctrine:
           enabled: true
           log_queries: true
   

2. Manual Span Creation Inject opentracing.tracer.default and create spans for custom logic:

   public function processOrder(Order $order, Tracer $tracer): void
   {
       $span = $tracer->buildSpan('order.process')->start();
       try {
           // Business logic
       } finally {
           $span->setTag('order.id', $order->getId());
           $span->finish();
       }
   }
   

3. Context Propagation Pass spans across service boundaries using SpanContext:

   public function __invoke(Request $request, Tracer $tracer): Response
   {
       $span = $tracer->extract(
           \OpenTracing\FORMAT_HTTP_HEADERS,
           $request->headers->all()
       );
       $tracer->inject(
           $span->getContext(),
           \OpenTracing\FORMAT_HTTP_HEADERS,
           $response->headers->all()
       );
       // ...
   }
   

4. Middleware for HTTP Tracing Extend InstanaHttpMiddleware to trace incoming requests:

   use CedricZiel\InstanaBundle\Middleware\InstanaHttpMiddleware;
   
   class CustomInstanaMiddleware extends InstanaHttpMiddleware
   {
       protected function getSpanName(Request $request): string
       {
           return sprintf('http.%s.%s', $request->getMethod(), $request->getPathInfo());
       }
   }
   

Gotchas and Tips

Pitfalls

1. Agent Connectivity

   • Ensure the Instana agent is running and accessible from your PHP process.
   • Debug connection issues with:

     telnet your-instana-agent-host 42699
     

   • Check for firewall rules blocking UDP/TCP traffic on the agent port.

2. Span Lifecycle Management

   • Unfinished Spans: Forgetting to call $span->finish() leaks memory and breaks traces. Fix: Use try-finally blocks or a decorator pattern.
   • Nested Spans: Avoid excessive nesting (>5 levels) to prevent performance overhead.

3. Doctrine Integration

   • Query Logging Overhead: Enabling log_queries adds ~10-20% latency to DB operations. Tip: Disable in staging/production unless debugging:

     instana:
         doctrine:
             log_queries: "%kernel.debug%"  # Only in dev
     

4. Event Dispatcher Hooks

   • Performance Impact: Tracing every event may slow down the app. Tip: Whitelist critical events in config/instana.yaml:

     instana:
         events:
             enabled: true
             whitelist:
                 - "kernel.request"
                 - "kernel.exception"
     

Debugging

1. Tracer Logs Enable verbose logging in config/instana.yaml:

   instana:
       debug: true
   

   Check logs for errors like:

   [Instana] Failed to send span: Connection refused
   

2. Span Visualization

   • Use Instana’s UI to verify traces appear.
   • Filter by span.name to locate specific operations.

3. Common Errors

   Error	Cause	Solution
   No tracer registered	Missing opentracing.tracer.default	Ensure bundle is loaded and config is valid.
   Invalid token	Wrong instana.token	Regenerate token in Instana UI.
   Span context not found	Missing context propagation	Use Tracer::extract()/inject().

Extension Points

1. Custom Span Processors Add logic to spans before they’re sent to Instana:

   // config/services.yaml
   CedricZiel\InstanaBundle\SpanProcessor\SpanProcessorInterface:
       class: App\Instana\CustomSpanProcessor
       arguments: ["@opentracing.tracer.default"]
   

2. Dynamic Tagging Attach runtime tags (e.g., user ID) via a subscriber:

   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class InstanaTagSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [
               'kernel.request' => 'onKernelRequest',
           ];
       }
   
       public function onKernelRequest(RequestEvent $event): void
       {
           $span = $event->getRequest()->attributes->get('instana.span');
           $span->setTag('user.id', $event->getRequest()->get('user_id'));
       }
   }
   

3. Sampling Control Adjust sampling rate in config/instana.yaml:

   instana:
       sampling:
           rate: 0.1  # Trace 10% of requests
           priority_sampling: true
   

4. Async Processing For high-throughput apps, use async span reporting:

   instana:
       async: true
       queue:
           driver: redis
           host: redis-host
           port: 6379