README

Lightweight error tracking and tracing SDK for Symfony applications with OpenTelemetry-compatible distributed tracing. Capture exceptions, request traces, spans, breadcrumbs, logs, and performance data - all unified and linked together.

Features

• 🔗 Unified Tracing - Spans, breadcrumbs, logs, and stack traces linked by trace/span IDs
• 🌐 Distributed Tracing - W3C Trace Context (traceparent) header support
• 🔍 OTEL Compatible - OpenTelemetry-style spans with semantic conventions
• 🔐 Fingerprinting - Hash-based deduplication for cost optimization
• 📊 Monolog Integration - Automatic log capture linked to spans
• ⚡ Performance - Batching, compression, and sampling
• 🧩 Symfony Integrations - Doctrine, Messenger, Mailer, Security, Forms, Twig, Cache, Console

Feature Tiers

To enable OTEL spans (paid feature):

stacktracer:
    capture:
        spans: true

Installation

composer require stacktracer/stacktracer-symfony

Quick Setup

1. Add environment variables

Add to your .env file:

STACKTRACER_ENDPOINT=https://api.stacktracer.io/v1/traces
STACKTRACER_API_KEY=your-api-key-here
STACKTRACER_SERVICE_NAME=my-service
STACKTRACER_SERVICE_VERSION=1.0.0

2. Create configuration file

Create config/packages/stacktracer.yaml:

stacktracer:
    transport:
        endpoint: '%env(STACKTRACER_ENDPOINT)%'
        api_key: '%env(STACKTRACER_API_KEY)%'
    service:
        name: '%env(STACKTRACER_SERVICE_NAME)%'
        version: '%env(STACKTRACER_SERVICE_VERSION)%'

That's it! The bundle will automatically:

• Capture all unhandled exceptions with fingerprinting
• Track request performance with OTEL spans
• Capture Monolog logs linked to spans
• Propagate trace context for distributed tracing
• Send traces to your Stacktracer endpoint

Configuration Options

stacktracer:
    enabled: true                    # Enable/disable globally
    
    transport:
        endpoint: '%env(STACKTRACER_ENDPOINT)%'  # Required
        api_key: '%env(STACKTRACER_API_KEY)%'    # Required
        batch_size: 50               # Traces per batch
        flush_interval_ms: 5000      # Max wait before flush
        max_queue_size: 500          # Queue size limit
        timeout: 5                   # HTTP timeout (seconds)
        compress: true               # Gzip compression
        max_retries: 3               # Retry attempts
    
    exclude_patterns:                # Paths to ignore
        - '#^/_profiler#'
        - '#^/_wdt#'
    
    capture:
        request: true                # Track requests
        exception: true              # Track exceptions
        exception_context_lines: 5   # Code lines around error
        stacktrace_context_lines: 5  # Code lines per frame
        spans: false                 # 💰 OTEL spans (paid feature, disabled by default)
    
    performance:
        sample_rate: 1.0             # 0.1 = 10% sampling
        max_stack_frames: 50         # Stack depth limit
        capture_code_context: true   # Include code snippets
        filter_vendor_frames: true   # Collapse vendor frames
        capture_request_headers: true
        sensitive_keys:              # Keys to redact
            - password
            - token
            - secret
    
    # OTEL service identification
    service:
        name: '%env(STACKTRACER_SERVICE_NAME)%'
        version: '%env(STACKTRACER_SERVICE_VERSION)%'
    
    # Monolog integration
    logging:
        enabled: true                # Capture logs
        level: debug                 # Minimum level
        capture_context: true        # Include log context
        exclude_channels:            # Channels to ignore
            - event
            - doctrine

Manual Usage

Inject the service and use it directly:

use Stacktracer\SymfonyBundle\Service\TracingService;
use Stacktracer\SymfonyBundle\Model\Trace;
use Stacktracer\SymfonyBundle\Model\Span;

class MyController
{
    public function __construct(
        private TracingService $stacktracer
    ) {}
    
    public function someAction()
    {
        // Add breadcrumbs for debugging (linked to current span)
        $this->stacktracer->addBreadcrumb('user', 'User clicked checkout');
        
        // Create a span for a unit of work
        $this->stacktracer->withSpan('process-order', function(Span $span) {
            $span->setAttribute('order.id', $orderId);
            
            // Nested span for database query
            $this->stacktracer->withSpan('db.query', function($dbSpan) {
                $dbSpan->setAttribute('db.statement', 'SELECT * FROM orders');
                // ... database work
            }, Span::KIND_CLIENT);
            
            // ... process order
        });
        
        try {
            // Your code
        } catch (\Exception $e) {
            // Capture exception (auto-linked to current span)
            $this->stacktracer->captureException($e, [
                'order_id' => $orderId,
            ]);
        }
        
        // Capture a custom message
        $this->stacktracer->captureMessage(
            'Order completed',
            Trace::LEVEL_INFO,
            ['order_id' => $orderId]
        );
    }
}

Feature Flags & Experiments

Monitor errors as you roll out features or run A/B tests. Feature flags are linked to errors, helping identify if a feature introduced issues.

use Stacktracer\SymfonyBundle\Model\FeatureFlag;

class MyController
{
    public function __construct(
        private TracingService $stacktracer
    ) {}
    
    public function checkout()
    {
        // Declare a single feature flag with variant
        $this->stacktracer->addFeatureFlag('Checkout button color', 'Blue');
        $this->stacktracer->addFeatureFlag('New checkout flow');
        
        // Declare multiple feature flags at once
        $this->stacktracer->addFeatureFlags([
            new FeatureFlag('Special offer', 'Free Coffee'),
            new FeatureFlag('Premium shipping'),
        ]);
        
        // Remove flags when features are deactivated
        $this->stacktracer->clearFeatureFlag('Checkout button color');
        
        // Clear all flags
        $this->stacktracer->clearFeatureFlags();
    }
}

LaunchDarkly Integration

$featureEnabled = $launchDarklyClient->variation('bool-flag-key', $user, false);

if ($featureEnabled) {
    $this->stacktracer->addFeatureFlag('bool-flag-key');
} else {
    $this->stacktracer->clearFeatureFlag('bool-flag-key');
}

// String variant
$variant = $launchDarklyClient->variation('button-color', $user, 'default');
$this->stacktracer->addFeatureFlag('button-color', $variant);

Split Integration

// Use an impression listener to automatically track experiments
class StacktracerImpressionListener implements \SplitIO\Sdk\ImpressionListener
{
    public function __construct(private TracingService $stacktracer) {}

    public function logImpression($data)
    {
        $this->stacktracer->addFeatureFlag(
            $data['impression']['feature'],
            $data['impression']['treatment']
        );
    }
}

Distributed Tracing

The bundle automatically propagates trace context via W3C traceparent header:

// Outgoing HTTP request - include trace context
$client->request('GET', '/api/users', [
    'headers' => [
        'traceparent' => $this->stacktracer->getTraceparent(),
    ],
]);

Incoming requests with traceparent headers are automatically linked to the parent trace.

Symfony Integrations

All integrations are enabled by default and auto-detect component availability. Configure in stacktracer.yaml:

stacktracer:
    integrations:
        doctrine:
            enabled: true
            slow_query_threshold: 100  # ms
        http_client:
            enabled: true
            propagate_context: true    # W3C traceparent
        messenger:
            enabled: true
        cache:
            enabled: true
        console:
            enabled: true
        form:
            enabled: true
        security:
            enabled: true
        mailer:
            enabled: true
        twig:
            enabled: true
            slow_threshold: 50         # ms

Available Integrations

Example: Form Validation Errors

Form validation errors are automatically captured as breadcrumbs:

// When a form fails validation, you'll see breadcrumbs like:
// [warning] Form validation failed
//   - form.name: "contact"
//   - form.error_count: 2
//   - form.errors: [{"field": "email", "message": "Invalid email"}]

Example: Security Events

Authentication events are tracked automatically:

// Login failures appear as breadcrumbs + spans:
// [warning] Login attempt failed
//   - security.event: "login_failure"
//   - security.attempted_user: "john@example.com"
//   - security.failure_reason: "Invalid credentials"

Example: Mailer Tracking

Email sending is tracked with delivery status:

// Email events appear as breadcrumbs + spans:
// [info] Email sent successfully
//   - mail.to: "user@example.com"
//   - mail.subject: "Welcome to our platform"
//   - mail.duration_ms: 234.5

Data Model

Unified Linking

All data is linked together for easy frontend navigation:

Trace
├── trace_id (OTEL 128-bit)
├── spans[]
│   ├── span_id (OTEL 64-bit)
│   ├── parent_span_id
│   ├── breadcrumbs[] (linked by span_id)
│   ├── logs[] (linked by span_id)
│   └── stack_trace[] (with fingerprints)
├── fingerprint (for deduplication)
└── group_key (for aggregation)

Fingerprinting

Stack traces and errors are fingerprinted for:

• Deduplication - Identical errors grouped together
• Cost Optimization - Store fingerprint, not full stack on repeats
• Pattern Detection - Find similar error patterns

// Fingerprints are computed automatically
$trace->getFingerprint();     // Unique error signature
$trace->getGroupKey();        // Grouping key for similar errors

API Reference

TracingService

Span Kinds (OTEL)

• Span::KIND_INTERNAL - Internal operation (default)
• Span::KIND_SERVER - Server handling request
• Span::KIND_CLIENT - Client making request
• Span::KIND_PRODUCER - Message producer
• Span::KIND_CONSUMER - Message consumer

Trace Levels

• Trace::LEVEL_DEBUG
• Trace::LEVEL_INFO
• Trace::LEVEL_WARNING
• Trace::LEVEL_ERROR
• Trace::LEVEL_FATAL

Requirements

• PHP 8.1+
• Symfony 6.4, 7.x, or 8.x
• ext-curl
• ext-json

License

MIT