Request Integration

The RequestIntegration class enriches Sentry events with user IP addresses and HTTP request context when PII (Personally Identifiable Information) sending is enabled. This integration implements the Sentry SDK's IntegrationInterface and uses a global event processor to automatically attach user identification data to every event captured by the system.

For information about AOP aspects that provide cross-cutting monitoring functionality, see page 5.2. For details about the core service provider that registers this integration, see page 2.1.

Overview

The RequestIntegration operates within Sentry's event processing pipeline, intercepting events before transmission to add contextual HTTP request information. The integration respects Sentry's PII configuration settings and only enriches events when explicitly authorized to send personally identifiable information.

Key Characteristics:

Aspect	Details
Interface	Sentry\Integration\IntegrationInterface
Lifecycle Method	setupOnce()
Processing Pattern	Global Event Processor
Configuration Dependency	shouldSendDefaultPii() client option
Primary Data Source	request()->ip() Hypervel helper

The integration follows Sentry's standard integration pattern by implementing the IntegrationInterface contract and registering a global event processor during its setupOnce() lifecycle method. This processor is invoked for every event captured by the Sentry client.

Sources: src/Integrations/RequestIntegration.php1-39

Implementation Architecture

Setup and Registration

The RequestIntegration class implements the setupOnce() method at src/Integrations/RequestIntegration.php15-37 which registers a global event processor using Scope::addGlobalEventProcessor(). This method is called once during the integration lifecycle when the Sentry client is initialized.

Integration Registration Flow

The global event processor pattern allows the integration to intercept and modify every Event object before it is sent to Sentry. The processor is implemented as a closure that receives an Event and returns a potentially modified Event.

Sources: src/Integrations/RequestIntegration.php15-37

Event Processing Logic

The event processor implements a multi-stage validation and enrichment pipeline:

RequestIntegration Event Processing Pipeline

The processing logic implements several safety checks:

1. Hub Integration Validation (src/Integrations/RequestIntegration.php18-19): Retrieves the current hub and verifies the integration is registered by calling hub->getIntegration(self::class)

2. Instance Type Check (src/Integrations/RequestIntegration.php21): Ensures the retrieved integration is an instance of RequestIntegration

3. PII Configuration Check (src/Integrations/RequestIntegration.php21): Verifies shouldSendDefaultPii() is enabled on the client options before proceeding with data enrichment

4. IP Address Extraction (src/Integrations/RequestIntegration.php25): Uses Hypervel's request()->ip() helper to obtain the client IP address

5. User Data Management (src/Integrations/RequestIntegration.php27-31): Either creates a new UserDataBag or updates an existing user object with the IP address

Sources: src/Integrations/RequestIntegration.php17-36

User Data Enrichment

The integration handles user data in two scenarios:

New User Creation

When an event does not have existing user data (src/Integrations/RequestIntegration.php27-28), the integration creates a new UserDataBag using the static factory method:

UserDataBag::createFromUserIpAddress($ip)

This method is provided by the Sentry SDK and creates a user data object with the IP address as the primary identifier.

Existing User Update

When an event already contains user information (src/Integrations/RequestIntegration.php29-30), the integration preserves existing data and only updates the IP address:

$user->setIpAddress($ip)

This approach ensures that user data added by other integrations or application code is not overwritten.

User Data Assignment

In both scenarios, the final step is to attach the user data to the event using event->setUser($user) at src/Integrations/RequestIntegration.php33

Scenario	Method	Line Reference
No existing user	UserDataBag::createFromUserIpAddress()	src/Integrations/RequestIntegration.php28
Existing user	$user->setIpAddress()	src/Integrations/RequestIntegration.php30
Both scenarios	$event->setUser()	src/Integrations/RequestIntegration.php33

Sources: src/Integrations/RequestIntegration.php25-33

Configuration Requirements

PII Configuration

The RequestIntegration only enriches events when the Sentry client is configured to send default PII (Personally Identifiable Information). This is controlled by the send_default_pii option in the Sentry configuration.

The integration checks this setting by calling shouldSendDefaultPii() on the client options at src/Integrations/RequestIntegration.php21:

$hub->getClient()?->getOptions()->shouldSendDefaultPii()

If this method returns false, the integration immediately returns the event without modification.

Configuration in Hypervel

In a Hypervel application, PII sending is typically configured in config/sentry.php:

This allows the behavior to be controlled via environment variables while defaulting to privacy-preserving settings.

Configuration Options:

Setting	Effect	Default
send_default_pii: true	IP addresses are captured	Not recommended for production
send_default_pii: false	No PII data is sent	Recommended default

Sources: src/Integrations/RequestIntegration.php21

Integration Architecture

Both integrations follow Sentry's standard integration lifecycle and utilize the global event processor pattern for event enrichment.

Event Processor Registration

Integration	Event Processor Type	Registration Location
RequestIntegration	Global Event Processor	src/Integrations/RequestIntegration.php17
ExceptionContextIntegration	Static Global Event Processor	src/Integrations/ExceptionContextIntegration.php17

Data Flow Architecture

Sentry Integration Data Flow

The integrations operate within Sentry's event processing pipeline, intercepting events before they are transmitted to the Sentry service. Each integration performs its own validation and data extraction logic while maintaining the event's integrity through the processing chain.

Both integrations implement the IntegrationInterface contract, requiring implementation of the setupOnce() method for registration with the Sentry SDK. This method is called once during the integration lifecycle to establish the global event processors.

Sources: src/Integrations/RequestIntegration.php15-37 src/Integrations/ExceptionContextIntegration.php15-40