Sdk Symfony Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require allstak/sdk-symfony
   

   For Symfony Flex projects, the bundle auto-registers. For manual setups, add to config/bundles.php:

   AllStak\SymfonyBundle\AllStakBundle::class => ['all' => true],
   

2. Configure API Key Add to .env:

   ALLSTAK_API_KEY=allstak_live_your_key_here
   

   Restart your Symfony server. The bundle auto-captures all observability data (errors, HTTP, DB, logs, etc.).

3. First Use Case Trigger an error (e.g., throw new \RuntimeException('Test')) and verify the event appears in your AllStak dashboard. Check the Traces tab for HTTP requests and Errors for exceptions.

Implementation Patterns

Core Workflow

1. Auto-Instrumentation

   • No manual instrumentation: The bundle auto-wires the allstak/sdk-php core SDK into Symfony’s container and event system.
   • Default Enabled: All integrations (HTTP, DB, logs, etc.) are on by default. Toggle via allstak.yaml.

2. Configuration-Driven Customization Use config/packages/allstak.yaml to:

   allstak:
       api_key: '%env(ALLSTAK_API_KEY)%'
       sample_rate: 0.5  # Send 50% of exceptions (reduce noise)
       enable_offline_queue: true  # Persist events for later sync
       integrations:
           http: true       # Auto-capture HTTP requests/responses
           db: true         # Auto-capture Doctrine DB queries
           logs: true       # Auto-capture Monolog logs
           messenger: false # Disable Messenger integration
   

3. Context Enrichment Add custom context to traces/spans via Symfony’s event system:

   use AllStak\SymfonyBundle\Event\SpanEvent;
   
   // In a controller or service:
   $this->eventDispatcher->dispatch(new SpanEvent('my.custom.span', [
       'user_id' => $user->id,
       'custom_data' => 'value',
   ]));
   

4. Environment-Specific Behavior Use %kernel.environment% to toggle features per environment:

   allstak:
       environment: '%kernel.environment%'
       sample_rate: '%env(default::0.1)%'  # 10% in dev, 100% in prod
   

5. Messenger Integration Auto-captures async messages. Disable if needed:

   allstak:
       integrations:
           messenger: false
   

Gotchas and Tips

Pitfalls

1. API Key Leaks

   • Risk: Hardcoding ALLSTAK_API_KEY in allstak.yaml exposes it in Git.
   • Fix: Always use %env(ALLSTAK_API_KEY)% and add .env to .gitignore.

2. Offline Queue Overhead

   • Issue: enable_offline_queue: true persists events to disk, increasing I/O.
   • Mitigation: Disable in non-critical environments or monitor queue size.

3. Sample Rate Misconfiguration

   • Problem: Setting sample_rate: 0 disables all error reporting.
   • Fix: Use 0.1 (10%) for staging, 1.0 for production.

4. PII Data Exposure

   • Default: send_default_pii: false scrubs sensitive data (e.g., passwords).
   • Warning: Custom spans/logs may inadvertently include PII. Review before enabling.

5. Symfony 6.4/7.x Only

   • Error: Installing on Symfony 5.x+ fails silently.
   • Fix: Verify compatibility in composer.json or README.

Debugging Tips

1. Verify Integration Status Check if the SDK is active:

   use AllStak\SDK\AllStak;
   
   if (AllStak::isActive()) {
       AllStak::captureMessage('Debug: SDK is running');
   }
   

2. Log Level Control Override Monolog handlers to filter AllStak logs:

   monolog:
       handlers:
           allstak:
               type: fingers_crossed
               action_level: error
               handler: nested
   

3. Offline Queue Inspection View persisted events (Linux/macOS):

   ls -lah var/cache/allstak_offline_queue/
   

4. Disable Specific Integrations Debug performance issues by disabling integrations one by one in allstak.yaml:

   allstak:
       integrations:
           http: false  # Disable HTTP tracing
   

Extension Points

1. Custom Span Attributes Extend the SDK via events:

   // src/EventListener/AllStakListener.php
   use AllStak\SymfonyBundle\Event\SpanEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class AllStakListener implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               SpanEvent::class => 'onSpanCreated',
           ];
       }
   
       public function onSpanCreated(SpanEvent $event) {
           if ($event->getName() === 'http.request') {
               $event->addAttribute('custom_header', $this->getRequestHeader());
           }
       }
   }
   

2. Override Transport Layer Replace the default HTTP transport (e.g., for proxy support):

   allstak:
       transport:
           class: App\AllStak\CustomTransport
           options:
               proxy_url: '%env(HTTP_PROXY)%'
   

3. Release Tracking Tag deployments with ALLSTAK_RELEASE:

   ALLSTAK_RELEASE=2024-05-30-v1.2.0
   

   View release-specific metrics in the AllStak dashboard.

4. Custom Error Handling Override exception capture logic:

   use AllStak\SDK\AllStak;
   use Symfony\Component\HttpKernel\Event\ExceptionEvent;
   
   $dispatcher->addListener(KernelEvents::EXCEPTION, function (ExceptionEvent $event) {
       $exception = $event->getThrowable();
       if ($exception instanceof \Some\CustomException) {
           AllStak::captureException($exception, [
               'custom_context' => 'value',
           ]);
       }
   });