 |
VOOZH | about |
|
VOOZH | about |
This document explains the Hub and client management components that form the core of the Sentry integration. The Hub class serves as the central API for all Sentry operations in the application, providing methods for capturing events, managing scopes, and handling distributed tracing. The SentrySdk singleton provides global access to the Hub instance. The factory classes (HubFactory and ClientBuilderFactory) implement the factory pattern to create properly configured Hub and Sentry Client instances through Hypervel's dependency injection container.
For information about how the service provider registers these components, see Service Provider. For details on how features use the Hub to create spans and breadcrumbs, see Feature System Overview.
The Hub and client management system consists of three key components working together:
Sources: src/Hub.php31-440 class_map/SentrySdk.php14-66 src/Factory/HubFactory.php11-17 src/Factory/ClientBuilderFactory.php24-188
The Hub class at src/Hub.php31-440 implements the Sentry\State\HubInterface and acts as the primary interface for all Sentry operations. Unlike the standard Sentry SDK Hub, this implementation is designed to work with Hypervel's coroutine-based architecture by storing scope and context information in Hypervel's Context system rather than static variables.
Sources: src/Hub.php31-440
The Hub exposes several categories of operations:
| Category | Methods | Purpose |
|---|---|---|
| Event Capture | captureMessage, captureException, captureEvent, captureLastError | Send error and message events to Sentry |
| Breadcrumbs | addBreadcrumb | Add contextual information that will be included with events |
| Scope Management | pushScope, popScope, configureScope, withScope | Isolate context and data per execution scope |
| Tracing | startTransaction, getTransaction, setSpan, getSpan | Manage distributed tracing transactions and spans |
| Monitoring | captureCheckIn | Send cron job monitoring check-ins |
| Client Access | getClient, bindClient, getIntegration | Access underlying Sentry client and integrations |
Sources: src/Hub.php84-381
A critical design decision in the Hub implementation is its use of Hypervel's Context system to store scope stacks and metadata. This enables proper isolation in coroutine-based concurrent execution environments.
The Hub defines three context keys at src/Hub.php33-37:
Hub::CONTEXT_STACK_KEY = 'sentry.stack'
Hub::CONTEXT_LAST_EVENT_ID_KEY = 'sentry.last_event_id'
Hub::CONTEXT_REQUEST_COROUTINE_ID_KEY = 'sentry.coroutine_id'
Sources: src/Hub.php58-82 src/Hub.php383-400
The scope stack implementation at src/Hub.php58-82 uses Context::override() to atomically modify the stack, ensuring thread-safety in coroutine environments. The popScope() method prevents popping the last scope to maintain invariants.
The Hub provides four primary capture methods that delegate to the underlying Sentry client:
Sources: src/Hub.php84-135
Each capture method follows the same pattern:
getClient() src/Hub.php43-46EventId in the context at key CONTEXT_LAST_EVENT_ID_KEY src/Hub.php89-92EventId or null if no client is configuredThe addBreadcrumb() method at src/Hub.php137-161 has additional logic:
max_breadcrumbs is greater than 0before_breadcrumb callback to allow modification or filteringtrue if the breadcrumb was added, false otherwiseSources: src/Hub.php137-161
The startTransaction() method at src/Hub.php172-313 is the most complex method in the Hub, implementing the complete sampling decision logic:
Sources: src/Hub.php172-313
The sampling decision hierarchy at src/Hub.php196-218 is:
traces_sampler) - highest priority, set via sampleSource = 'config:traces_sampler'traces_sample_rate) - fallback defaultThe actual sampling decision at src/Hub.php259 compares a random float (sampleRand) against the determined sample rate.
The SentrySdk class at class_map/SentrySdk.php14-66 provides global access to the Hub instance through a singleton pattern. This class is a custom implementation that replaces the standard Sentry SDK's static access pattern with one that integrates with Hypervel's dependency injection system.
Sources: class_map/SentrySdk.php14-66
The SentrySdk provides four static methods for Hub access:
| Method | Purpose | Implementation |
|---|---|---|
init() | Initialize the singleton Hub if not already set | Resolves HubInterface from container via make() at class_map/SentrySdk.php28-35 |
getCurrentHub() | Get the current Hub instance, initializing if needed | Calls init() if hub is null at class_map/SentrySdk.php40-47 |
setCurrentHub() | Explicitly set the Hub instance | Stores provided hub in static property at class_map/SentrySdk.php52-57 |
getHub() | Get the hub without auto-initialization | Returns static hub property directly at class_map/SentrySdk.php62-65 |
Sources: class_map/SentrySdk.php28-65
Sources: class_map/SentrySdk.php28-47
The singleton pattern ensures that all application code references the same Hub instance, while still allowing the Hub to be resolved through dependency injection. This approach provides the convenience of global access while maintaining testability and proper separation of concerns.
The factory pattern enables lazy initialization and proper dependency injection for complex objects like the Hub and Sentry Client.
The HubFactory at src/Factory/HubFactory.php11-17 is straightforward:
Sources: src/Factory/HubFactory.php11-17
The factory simply returns a new Hub instance without parameters at src/Factory/HubFactory.php15 The Hub will lazily resolve the ClientInterface from the container when needed via getClient() at src/Hub.php43-46 This lazy resolution is critical because it allows the Hub to be created before the Sentry client is fully configured.
The ClientBuilderFactory at src/Factory/ClientBuilderFactory.php24-188 is more complex, handling configuration merging and integration registration.
Sources: src/Factory/ClientBuilderFactory.php37-85
The factory defines SPECIFIC_OPTIONS at src/Factory/ClientBuilderFactory.php26-35 that are removed from configuration before passing to the Sentry SDK:
| Option | Purpose |
|---|---|
breadcrumbs | Hypervel-specific breadcrumb configuration |
crons | Hypervel-specific cron monitoring configuration |
enable | Feature enable/disable flag |
ignore_commands | Console commands to exclude from monitoring |
integrations | Custom integrations array |
tracing | Hypervel-specific tracing configuration |
features | Feature discovery array |
pool | HTTP connection pool configuration |
These options are used by other parts of the integration (service provider, features, switcher) but are not recognized by the Sentry SDK itself.
Sources: src/Factory/ClientBuilderFactory.php26-35 src/Factory/ClientBuilderFactory.php42-46
The resolveIntegrations() method at src/Factory/ClientBuilderFactory.php87-157 configures which Sentry integrations are active.
Sources: src/Factory/ClientBuilderFactory.php87-157
The factory removes several default Sentry SDK integrations at src/Factory/ClientBuilderFactory.php110-134:
ErrorListenerIntegration - Removed because Hypervel handles errors through its exception handlerExceptionListenerIntegration - Removed for the same reasonFatalErrorListenerIntegration - Removed for the same reasonRequestIntegration - Removed and replaced with a custom version that uses RequestFetcher to resolve the request from Hypervel's container rather than global stateAt src/Factory/ClientBuilderFactory.php140-148 the factory adds three custom integrations:
Hypervel\Sentry\Integrations\Integration - Base integration for Hypervel-specific functionalityExceptionContextIntegration - Adds exception context data to eventsRequestIntegration - Enriches events with request data and user IPSources: src/Factory/ClientBuilderFactory.php87-157
The factories are registered in the DI container by the SentryServiceProvider (see Service Provider). The binding structure creates a resolution chain that supports both dependency injection and singleton access:
Sources: class_map/SentrySdk.php28-47 src/Factory/HubFactory.php13-16 src/Factory/ClientBuilderFactory.php37-85
Application code can access the Hub through two patterns:
| Pattern | Method | Use Case | Example |
|---|---|---|---|
| Singleton | SentrySdk::getCurrentHub() | Quick access in utility functions, commands, and helpers | class_map/SentrySdk.php40-47 |
| Dependency Injection | Constructor injection or make(HubInterface::class) | Testable classes, features, integrations | Throughout feature classes |
The Hub uses lazy client resolution at src/Hub.php43-46 only retrieving the ClientInterface from the container when first needed. This prevents circular dependencies and allows the Hub to be constructed before the client is fully configured.
The Hub provides two methods for accessing the Sentry client:
If no client is explicitly bound to the Hub instance, getClient() resolves it from the DI container via ApplicationContext. This enables the Hub to work correctly even when client configuration changes at runtime.
The bindClient() method allows explicitly setting a client instance, which takes precedence over container resolution. This is useful for testing or creating Hub instances with specific client configurations.
Sources: src/Hub.php43-51
The Hub and factory classes implement a sophisticated architecture for Sentry integration:
Context system for coroutine isolationThe design leverages Hypervel's dependency injection container to enable loose coupling while maintaining proper initialization order and supporting the framework's coroutine-based concurrency model.
Sources: src/Hub.php31-440 src/Factory/HubFactory.php11-17 src/Factory/ClientBuilderFactory.php24-188
Refresh this wiki