Configuration Guide

Basic Setup

1. Install the Bundle

composer require amarc-sudo/sentry-enhanced-tracing

2. Enable in Symfony

Add to config/bundles.php:

<?php

return [
    // ... other bundles
    AmarcSudo\SentryEnhancedTracing\SentryEnhancedTracingBundle::class => ['all' => true],
];

3. Configure Sentry (Required)

Make sure you have Sentry properly configured:

# config/packages/sentry.yaml
sentry:
    dsn: '%env(SENTRY_DSN)%'
    options:
        # Enhanced tracing options
        traces_sample_rate: 1.0
        profiles_sample_rate: 1.0
        max_breadcrumbs: 100
        attach_stacktrace: true
        send_default_pii: true
        max_request_body_size: 'medium'
        context_lines: 7
        integrations:
            - 'Sentry\Integration\RequestIntegration'
            - 'Sentry\Integration\TransactionIntegration'
            - 'Sentry\Integration\FrameContextifierIntegration'

4. Configure Monolog (Recommended)

For breadcrumbs and enhanced logging:

# config/packages/monolog.yaml
monolog:
    handlers:
        sentry_breadcrumbs:
            type: sentry
            level: info
            hub_id: Sentry\State\HubInterface
            fill_extra_context: true
            
        sentry_events:
            type: sentry
            level: warning
            hub_id: Sentry\State\HubInterface

Advanced Configuration

Custom Event Phases

You can customize which event phases are tracked:

# config/packages/sentry_enhanced_tracing.yaml
sentry_enhanced_tracing:
    tracked_events:
        - 'kernel.request'
        - 'kernel.controller'  
        - 'kernel.view'
        - 'kernel.response'
        - 'kernel.exception'

Performance Thresholds

Customize performance categorization:

sentry_enhanced_tracing:
    performance_thresholds:
        kernel.request: 0.05    # 50ms
        kernel.controller: 0.1  # 100ms
        kernel.view: 0.02       # 20ms
        kernel.response: 0.05   # 50ms

User Context Settings

Configure user context capture:

sentry_enhanced_tracing:
    user_context:
        capture_user_id: true
        capture_username: true
        capture_email: false    # PII - be careful!
        capture_ip: true
        capture_user_agent: true

Environment Variables

Set these in your .env file:

# Required
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id

# Optional - for enhanced tracing
SENTRY_TRACES_SAMPLE_RATE=1.0
SENTRY_PROFILES_SAMPLE_RATE=1.0
SENTRY_SEND_DEFAULT_PII=false

Verification

After installation, you should see in your Sentry dashboard:

1. Transactions with event phase spans
2. Database queries nested under appropriate phases
3. Cache operations as child spans
4. Template rendering performance
5. Rich breadcrumbs with execution metrics

Troubleshooting

No Spans Appearing

1. Check Sentry configuration is correct
2. Verify traces_sample_rate is > 0
3. Ensure bundle is enabled in bundles.php
4. Check logs for any errors

Performance Issues

1. Reduce traces_sample_rate in production
2. Adjust max_breadcrumbs if needed
3. Consider disabling in high-traffic endpoints

Missing Child Spans

1. Ensure Sentry integrations are enabled
2. Check that DBAL/Cache are properly configured
3. Verify listener priorities are not conflicting

Best Practices

1. Production: Use sampling (traces_sample_rate: 0.1)
2. Development: Use full tracing (traces_sample_rate: 1.0)
3. Security: Be careful with PII data capture
4. Performance: Monitor overhead in high-traffic apps

Messenger queue monitoring (Sentry Queues)

Activation

• No extra config when using Symfony Messenger: listeners are auto-registered.
• A queue.publish span is created on dispatch, and a queue.process transaction is started per message on the worker.

Context propagation

• Traceparent and baggage are added via SentryTraceStamp to link producer/consumer.
• The authenticated user is propagated via SentryUserStamp (id, username, email if available). To disable:

# config/services.yaml
parameters:
    sentry_enhanced_tracing.messenger.propagate_user: false

Metadata sent to Sentry

• messaging.message.id (TransportMessageIdStamp/UuidStamp)
• messaging.destination.name (transport or bus)
• messaging.message.body.size (JSON/serialize estimation)
• messaging.message.retry.count (RedeliveryStamp)
• messaging.message.receive.latency (ms, based on publish_time)

Minimal example

// Dispatch
$bus->dispatch(new EmailJob($payload));

// Worker (standard messenger:consume)
php bin/console messenger:consume async

Transactions appear in Sentry > Performance > Queues, linked to parent HTTP requests or producer jobs through the injected traceparent/baggage.