Overview

Purpose and Scope

This document provides a high-level introduction to the Hypervel Sentry integration package (hypervel/sentry). This package integrates the Sentry error tracking and application performance monitoring (APM) platform with the Hypervel PHP framework, enabling automatic capture of errors, exceptions, logs, and distributed traces across asynchronous operations.

This page covers the package's purpose, key capabilities, architectural components, and how it integrates with Hypervel applications. For detailed configuration options, see Configuration. For information about specific monitoring features (cache, queue, Redis, etc.), see Monitoring Features. For logging integration details, see Logging Integration.

Sources: composer.json:1-49, README.md:1-2

What is Hypervel Sentry

The Hypervel Sentry integration is a library that bridges the official Sentry PHP SDK (sentry/sentry) with Hypervel's asynchronous, coroutine-based runtime environment. It provides automatic instrumentation for Hypervel applications to capture:

• Exceptions and Errors: Uncaught exceptions and PHP errors are automatically reported to Sentry
• Performance Traces: Distributed tracing across HTTP requests, queue jobs, cache operations, database queries, and Redis commands
• Breadcrumbs: Context about user actions and system events leading up to errors
• Logs: Integration with Hypervel's Monolog-based logging system
• Cron Monitoring: Check-ins for scheduled console commands

The package is designed specifically to handle Hypervel's coroutine concurrency model, ensuring that Sentry context is properly isolated between concurrent operations and propagated across asynchronous boundaries (e.g., when dispatching queue jobs).

Sources: composer.json:1-49, Diagram 1 (Overall System Architecture), Diagram 4 (Event Capture and Reporting Flow)

Key Capabilities

Capability	Description	Primary Component
Error Tracking	Automatic capture of exceptions and errors with stack traces	SentryServiceProvider, Hub
Distributed Tracing	Trace requests across HTTP, queue jobs, and external services	QueueFeature, CoroutineAspect
Cache Monitoring	Track cache hits/misses and performance with spans	CacheFeature
Queue Job Tracing	Monitor queue job execution and failures with context propagation	QueueFeature
Redis Instrumentation	Trace Redis commands with PII redaction	RedisFeature
Database Query Tracing	Monitor SQL query performance	DbQueryFeature
Log Aggregation	Send application logs to Sentry with batch processing	LogFeature, LogsHandler
Scheduled Command Monitoring	Track cron job execution and failures	ConsoleSchedulingFeature
Async Event Submission	Non-blocking event transmission using connection pools	HttpPoolTransport

Sources: Diagram 1 (Overall System Architecture), Diagram 3 (Feature System Architecture), Diagram 5 (Performance Monitoring Architecture)

System Architecture

The following diagram shows the main architectural layers and how they relate to concrete code entities in the package:

Architecture Description:

1. Application Layer: Hypervel applications interact with various framework components (HTTP, Queue, Cache, Redis, Database)
2. Bootstrap Layer: SentryServiceProvider initializes the integration using configuration from config/sentry.php
3. Core SDK Layer: Central components manage the Sentry client and hub instances
4. Feature Layer: Modular features instrument specific framework components
5. Transport Layer: Custom async transport handles event submission to Sentry
6. External Service: Events are sent to the Sentry.io platform for storage and analysis

Sources: composer.json:22-48, Diagram 1 (Overall System Architecture), Diagram 2 (Service Provider Initialization Flow), Diagram 7 (Configuration and Factory System)

Core Components

The following table maps high-level system concepts to their concrete implementations in code:

System Concept	Code Entity	File Location	Primary Responsibility
Integration Bootstrap	SentryServiceProvider	src/SentryServiceProvider.php	Registers and boots all Sentry features, configures SDK
Event Capture API	Hub	src/Hub.php	Central interface for capturing exceptions, messages, breadcrumbs
SDK Singleton	SentrySdk	src/SentrySdk.php	Global access point to the Hub instance
Client Factory	ClientBuilderFactory	src/ClientBuilderFactory.php	Creates and configures Sentry client with custom options
Hub Factory	HubFactory	src/HubFactory.php	Creates Hub instances with proper initialization
Async Transport	HttpPoolTransport	src/HttpPoolTransport.php	Non-blocking event submission using connection pools
HTTP Client Provider	HttpClientFactory	src/HttpClientFactory.php	Provides HTTP clients with SDK version headers
Cache Monitoring	CacheFeature	src/Features/CacheFeature.php	Instruments cache operations with breadcrumbs and spans
Queue Monitoring	QueueFeature	src/Features/QueueFeature.php	Traces queue jobs with distributed context propagation
Redis Monitoring	RedisFeature	src/Features/RedisFeature.php	Instruments Redis commands with span creation
Log Integration	LogFeature	src/Features/LogFeature.php	Registers custom Monolog channels for Sentry
Feature Toggle	Switcher	src/Switcher.php	Controls feature activation based on configuration

Sources: Diagram 3 (Feature System Architecture), Diagram 7 (Configuration and Factory System)

Integration with Hypervel Framework

The package integrates with Hypervel through several key mechanisms:

Service Provider Auto-Registration

The package is auto-discovered by Hypervel through the extra.hypervel.providers configuration in composer.json:

When Hypervel boots, it automatically registers SentryServiceProvider, which handles all initialization.

Sources: composer.json:39-48

Framework Component Integration

Features integrate with Hypervel by:

• Listening to Events: Features subscribe to framework events (e.g., Hypervel\Cache\Event\CacheHit)
• Extending Managers: LogFeature extends the Log manager with custom Monolog drivers
• AOP Interception: Aspects intercept coroutine creation and HTTP client calls
• Configuration Publishing: The service provider publishes config/sentry.php for user customization

Sources: Diagram 2 (Service Provider Initialization Flow), Diagram 3 (Feature System Architecture), Diagram 6 (Logging Integration Architecture)

Event Capture and Reporting Flow

The following diagram illustrates how events flow from application code to the Sentry platform:

Flow Description:

1. Application code triggers monitored operations (cache access, queue dispatch, etc.)
2. Features intercept these operations and create breadcrumbs or spans
3. When exceptions occur or manual capture is triggered, events flow through the Hub
4. The Sentry Client applies integrations and event processors to enrich events
5. HttpPoolTransport uses connection pooling for efficient async submission
6. Events are sent to Sentry.io without blocking the application

Sources: Diagram 4 (Event Capture and Reporting Flow), Diagram 1 (Overall System Architecture)

Package Structure

The repository is organized as follows:

Directory/File	Purpose
src/	Main source code directory
src/SentryServiceProvider.php	Bootstrap and lifecycle management
src/Hub.php	Core event capture API
src/Features/	Modular monitoring features
src/Integration/	Custom Sentry SDK integrations
src/Aspect/	AOP aspects for cross-cutting concerns
src/Log/	Monolog integration components
src/Traits/	Reusable utility traits
composer.json	Package metadata and dependencies
publish/sentry.php	Default configuration file template

Sources: composer.json:22-26

Key Dependencies

The package requires the following major dependencies:

Dependency	Version	Purpose
php	^8.2	Minimum PHP version
sentry/sentry	^4.15.0	Official Sentry PHP SDK
hypervel/cache	^0.3	Cache component integration
hypervel/console	^0.3	Console command integration
hypervel/core	^0.3	Core framework features
hypervel/object-pool	^0.3	Connection pooling for async transport
hypervel/support	^0.3	Framework utilities

The integration builds on top of the official Sentry SDK, adding Hypervel-specific features like coroutine context management, distributed tracing for queue jobs, and async event submission.

Sources: composer.json:27-35

How to Use This Documentation

To effectively use this documentation:

1. Getting Started: Begin with Installation and Setup to install the package, then review Configuration to configure DSN and features
2. Understanding Architecture: Read Core Architecture to understand how the service provider, Hub, and transport work together
3. Feature-Specific Documentation: Refer to Monitoring Features for detailed documentation on specific integrations (cache, queue, Redis, etc.)
4. Logging Setup: See Logging Integration to configure log channels and handlers
5. Advanced Topics: Review Integrations and Aspects for cross-cutting concerns and Utilities and Helpers for extending functionality
6. Testing: Consult Commands and Testing for testing your Sentry configuration

Sources: Diagram 1-7 (all diagrams)