README

Enhanced Sentry tracing package with automatic child span capture and listener phase tracking for Symfony applications.

🚀 Key Features

🔍 Automatic Child Span Capture

Database queries (DBAL) automatically nested under event phases
Cache operations (Redis, APCu) traced hierarchically
Template rendering (Twig) performance tracking
HTTP client calls monitored automatically
Zero configuration - works out of the box!

📊 Listener Phase Tracking

Traces Symfony kernel event phases as Sentry spans
Measures execution time of all event listeners
Performance categorization (fast/normal/slow/very_slow)
Detailed breadcrumbs with execution metrics

👤 Enhanced User Context

Automatic user identification in Sentry after JWT authentication
Enhanced user information capture with EnhancedUserInterface
Request/response metadata capture
Exception context enrichment
Security-aware PII handling

📦 Installation

composer require amarc-sudo/sentry-enhanced-tracing

🔧 Requirements

This bundle requires LexikJWTAuthenticationBundle to be installed and configured:

composer require lexik/jwt-authentication-bundle

The bundle automatically hooks into JWT authentication events to capture user context after successful authentication.

📝 Bundle Registration

Add the bundle to your config/bundles.php:

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

🎯 How It Works

Automatic Span Hierarchy

The bundle creates a magical hierarchy in Sentry by setting event phase spans as "current spans":

POST /api/resources (500ms)
├── Event Listeners Phase: kernel.request (50ms)
│   ├── db.query: SELECT users WHERE id=? (15ms)
│   ├── cache.get: user:permissions:123 (2ms)
│   └── security.check (30ms)
├── Event Listeners Phase: kernel.controller (200ms)  
│   ├── db.query: SELECT resources WHERE category=? (80ms)
│   ├── cache.set: resources:category:456 (5ms)
│   └── business.logic (115ms)
└── Event Listeners Phase: kernel.response (100ms)
    ├── twig.render: response.html.twig (85ms)
    └── cache.set: rendered:template:hash (3ms)

🔧 No Code Changes Required!

The bundle uses Sentry Hub manipulation to automatically capture:

SQL queries from Doctrine DBAL
Cache operations from Symfony Cache
Template rendering from Twig
HTTP client requests
Redis commands
Custom integrations

📋 What You Get

🎭 Event Listeners

SentryListenerPhasesTracer - Core phase tracking with child span capture
SentryUserContextListener - Enhanced user context and request metadata

⚡ Performance Optimization

ChangeSentryListenerPriorityPass - Optimized Sentry listener priorities
High-priority execution (99999-99995) for proper data capture
Minimal performance overhead

📊 Rich Metrics

Execution time categorization
Memory usage tracking
Request/response size analysis
Performance breadcrumbs
Exception context enrichment

🔧 Configuration

The bundle works zero-config but you can customize behavior:

# config/packages/sentry_enhanced_tracing.yaml
sentry_enhanced_tracing:
    # Configuration options (if needed)

🔐 JWT Authentication Integration

The bundle automatically captures user context after successful JWT authentication by listening to the lexik_jwt_authentication.on_jwt_authenticated event.

👤 Enhanced User Interface

To provide richer user context in Sentry, implement the EnhancedUserInterface in your User entity:

<?php

namespace App\Entity;

use AmarcSudo\SentryEnhancedTracing\User\EnhancedUserInterface;
use Symfony\Component\Security\Core\User\UserInterface;

class User implements UserInterface, EnhancedUserInterface
{
    // ... your existing User entity code

    public function getEnhancedFirstname(): ?string
    {
        return $this->firstname;
    }

    public function getEnhancedLastname(): ?string
    {
        return $this->lastname;
    }

    public function getEnhancedEmail(): ?string
    {
        return $this->email;
    }
}

This will automatically enrich your Sentry traces with:

User ID: From getUserIdentifier() (used as UUID)
Full Name: Combination of first and last name
Email: User's email address
Auth Method: Set to 'jwt' for JWT-authenticated users

🎨 Example Output

In your Sentry dashboard, you'll see:

Transaction: POST /api/users/123/resources
Duration: 450ms
Spans:

🔵 Event Listeners Phase: kernel.request (45ms)
- 🟢 db.query: SELECT * FROM users WHERE id = ? (12ms)
- 🟠 cache.get: user:123:permissions (3ms)
🔵 Event Listeners Phase: kernel.controller (320ms)
- 🟢 db.query: SELECT * FROM resource WHERE user_id = ? (85ms)
- 🟠 cache.set: resource:user:123 (5ms)
- 🟡 business.validation (180ms)
🔵 Event Listeners Phase: kernel.response (75ms)
- 🟣 twig.render: templates/api/resource.json.twig (65ms)

🛡️ Security & Privacy

PII data handling following Sentry best practices
Configurable data sanitization
User context capture with privacy controls
No sensitive data in breadcrumbs by default

📄 License

MIT License. See LICENSE for details.

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md for details.

🆘 Support

📧 Email: aurelien_marc@icloud.com
🐛 Issues: GitHub Issues
📚 Docs: Documentation

Made with ❤️ by Aurelien Marc

amarc-sudo / sentry-enhanced-tracing

Maintainers

Details