Integrations and Aspects

This page provides an overview of cross-cutting concerns handled through Sentry integrations and Aspect-Oriented Programming (AOP) aspects. These components extend Sentry's core capabilities and automatically instrument framework operations without requiring modifications to application code.

See page 5.1 for detailed documentation of RequestIntegration, and page 5.2 for detailed documentation of CoroutineAspect.

Overview

The package provides two primary mechanisms for cross-cutting monitoring functionality:

Sentry Integrations implement IntegrationInterface from the Sentry SDK and register global event processors that enrich or modify events before transmission to Sentry. The integration registers during client initialization and processes every event.

AOP Aspects use Hyperf's Aspect-Oriented Programming system to intercept framework method calls and inject monitoring functionality. Aspects wrap target methods using ProceedingJoinPoint to execute code before, after, or around the original method execution.

Architecture Overview

Integration Pipeline

This diagram shows how aspects intercept framework operations to create Sentry events, which then flow through the integration pipeline for enrichment before transmission.

Sources: src/Integrations/RequestIntegration.php1-39 src/Aspects/CoroutineAspect.php1-62

Integration Components

The package currently provides one custom integration:

Integration	Registration	Purpose
RequestIntegration	Registered in ClientBuilderFactory	Enriches events with user IP address when PII sending is enabled

The RequestIntegration implements the standard Sentry integration pattern by registering a global event processor in its setupOnce() method. The processor runs for every event and conditionally adds user IP information based on the send_default_pii configuration option.

Sources: src/Integrations/RequestIntegration.php14-38

AOP Aspect Components

Aspect Interception Architecture

This diagram shows how CoroutineAspect uses Hyperf's AOP system to intercept coroutine creation and inject Sentry context management.

The package provides one AOP aspect:

Aspect	Target Method	Purpose
CoroutineAspect	Hyperf\Coroutine\Coroutine::create	Propagates Sentry context across coroutines and captures exceptions

The CoroutineAspect intercepts all coroutine creation calls to ensure that Sentry's Hub and HTTP request context are properly propagated from parent to child coroutines. This is critical for maintaining accurate tracing in async operations.

Sources: src/Aspects/CoroutineAspect.php1-62

Registration and Lifecycle

Integration Registration

Integrations are registered during Sentry client initialization by the ClientBuilderFactory. The standard Sentry integration lifecycle:

1. Integration class is instantiated and registered with the client
2. setupOnce() method is called during client initialization
3. Integration registers global event processors via Scope::addGlobalEventProcessor()
4. Event processors execute for every event before transmission

Event Processing Flow

Sources: src/Integrations/RequestIntegration.php15-37

Aspect Registration

AOP aspects are registered by the SentryServiceProvider during the registration phase. The aspect lifecycle:

1. Aspect class is discovered by Hyperf's annotation scanner
2. DI container injects dependencies (e.g., Switcher)
3. Aspect intercepts matching method calls via ProceedingJoinPoint
4. Aspect checks feature toggle before executing logic
5. Modified callable is executed with Sentry instrumentation

Sources: src/Aspects/CoroutineAspect.php26-35

Feature Toggle Integration

Both integrations and aspects support feature toggling through the Switcher component:

Configuration Control:

• CoroutineAspect checks coroutine feature flag src/Aspects/CoroutineAspect.php33
• Integrations can be conditionally enabled/disabled
• Feature flags control whether processing occurs

Runtime Behavior:

• If feature is disabled, aspects bypass processing entirely
• Integrations may still run but with reduced functionality
• Configuration changes don't require application restart

Sources: src/Aspects/CoroutineAspect.php26-35