Sentry Transport Plugin

[butschster]

Implemented: https://github.com/roadrunner-plugins/sentry-transport

The Sentry Transport plugin for RoadRunner is designed to handle Sentry event transmission asynchronously, eliminating the performance impact of blocking HTTP requests in PHP applications. The plugin receives Sentry events via RPC calls from PHP and manages their transmission to Sentry services using efficient Go routines with built-in rate limiting and retry mechanisms.

Motivation

Current Problems

• PHP applications experience performance degradation when sending Sentry events synchronously
• Blocking HTTP requests in PHP increase response times
• Manual rate limiting implementation in each PHP application
• No centralized configuration for Sentry DSN and transport settings
• Limited retry mechanisms and error handling in PHP

Proposed Solution

• Asynchronous event processing using Go routines
• Centralized Sentry configuration in RoadRunner
• Built-in rate limiting based on Sentry response headers
• Automatic retry mechanisms with exponential backoff
• RPC interface for seamless PHP integration
• Support for multiple Sentry projects/DSNs

Project Structure

roadrunner-sentry-transport/
├── plugin.go              # Main plugin implementation
├── config.go              # Configuration structures
├── rpc.go                 # RPC methods for PHP communication
├── transport.go           # HTTP transport with rate limiting
├── rate_limiter.go        # Rate limiting implementation
├── queue.go               # Event queue management
├── retry.go               # Retry mechanism implementation
├── types.go               # Event and response type definitions
├── go.mod                 # Go module dependencies
├── go.sum                 # Dependencies checksum
├── README.md              # Plugin documentation
└── examples/
    ├── .rr.yaml           # Example RoadRunner configuration
    ├── velox.toml         # Velox build configuration
    └── php/
        └── sentry_client.php  # PHP integration example

Core Components

1. Plugin Core (plugin.go)

• Purpose: Main plugin lifecycle management
• Interfaces: Service, Named, Provider
• Dependencies: Logger, Config
• Responsibilities:
  • Plugin initialization and configuration loading
  • Event queue initialization
  • Worker pool management for async processing
  • Graceful shutdown handling

2. Configuration (config.go)

• Purpose: Plugin configuration management
• Features:
  • Sentry DSN support
  • Rate limiting configuration
  • Retry policy settings
  • Timeout and connection settings

3. RPC Interface (rpc.go)

• Purpose: PHP communication endpoint
• Methods:
  • SendBatch(events []SentryEvent) - Send multiple events

4. HTTP Transport (transport.go)

• Purpose: Sentry HTTP API communication
• Features:
  • HTTP client with proper headers
  • Gzip compression support
  • Custom User-Agent identification
  • Connection pooling and keep-alive
  • SSL/TLS configuration

5. Rate Limiter (rate_limiter.go)

• Purpose: Respect Sentry rate limiting headers
• Features:
  • Parse X-Sentry-Rate-Limits header
  • Category-specific rate limiting (error, transaction, etc.)
  • Retry-After header handling
  • Automatic backoff calculation
  • Rate limit status tracking

6. Event Queue (queue.go)

• Purpose: Asynchronous event processing
• Features:
  • Buffered channel-based queue
  • Priority handling for different event types
  • Queue metrics and monitoring
  • Overflow handling strategies
  • Batch processing optimization

7. Retry Mechanism (retry.go)

• Purpose: Handle failed event transmissions
• Features:
  • Exponential backoff algorithm
  • Dead letter queue for failed events
  • Configurable retry attempts
  • Permanent failure detection
  • Metrics for retry operations

Configuration Schema

sentry_transport:
  # Enable/disable the plugin
  enabled: true
  
  # Sentry DSN
  dsn: "https://key@sentry.io/project"
  
  # HTTP transport settings
  transport:
    # Request timeout
    timeout: "30s"
    # Connection timeout
    connect_timeout: "10s"
    # Enable gzip compression
    compression: true
    # SSL verification
    ssl_verify: true
    # Proxy settings
    proxy: ""
    proxy_auth: ""
  
  # Retry configuration
  retry:
    # Maximum retry attempts
    max_attempts: 3
    # Initial backoff duration
    initial_backoff: "1s"
    # Backoff multiplier
    backoff_multiplier: 2
    # Maximum backoff duration
    max_backoff: "300s"
    # Enable dead letter queue
    dead_letter_queue: true
  
  # Logging configuration
  logging:
    # Log level for plugin operations
    level: "info"

Data Structures

Sentry Event Structure

type SentryEvent struct {
    ID          string                 `json:"event_id"`
    Type        string                 `json:"type"`
    Payload     string                 `json:"payload"` // JSON payload generated on PHP side. Does not requre modificarion, just proxy it as is
}

Sequence Diagram

sequenceDiagram
    participant PHP as PHP Application
    participant RPC as RR Sentry RPC
    participant Queue as Event Queue
    participant Worker as Worker Pool
    participant RL as Rate Limiter
    participant Sentry as Sentry API
    
    PHP->>RPC: SendEvent(sentryEvent)
    RPC->>RPC: Validate Event
    RPC->>Queue: Enqueue Event
    RPC-->>PHP: Acknowledge (immediate)
    
    Queue->>Worker: Dequeue Event
    Worker->>RL: Check Rate Limits
    
    alt Rate Limited
        RL-->>Worker: Wait/Backoff
        Worker->>Worker: Schedule Retry
    else Not Rate Limited
        Worker->>Sentry: HTTP POST Event
        
        alt Success Response
            Sentry-->>Worker: 200 OK
            Worker->>RL: Update Rate Limits
        else Rate Limit Response
            Sentry-->>Worker: 429 + Headers
            Worker->>RL: Parse Rate Limit Headers
            Worker->>Queue: Requeue with Delay
        else Error Response
            Sentry-->>Worker: 4xx/5xx Error
            Worker->>Worker: Schedule Retry
        end
    end
    
    Note over Worker: Metrics & Logging

Loading

Integration Examples

PHP Integration

<?php
// Using RoadRunner RPC client
$rpc = new RoadRunner\RPC\RPC('tcp://127.0.0.1:6001');

$sentryEvent = [
    'event_id' => uniqid(),
    'type' => '...',
    'payload' => \json_encode([
	    'timestamp' => time(),
	    'level' => 'error',
	    'message' => 'Database connection failed',
	    'environment' => 'production',
	    'tags' => ['component' => 'database'],
	    'extra' => ['query' => 'SELECT * FROM users']
    ])
];

// Async send - non-blocking
$result = $rpc->call('sentry_transport.SendBatch', [$sentryEvent]);