Logging Integration

Purpose and Scope

This document provides an overview of how the Hypervel Sentry integration extends the framework's logging system to send log messages to Sentry.io. The integration registers custom Monolog drivers that enable applications to route log messages through Sentry's event capture system, providing centralized error tracking and log aggregation.

For detailed information about the feature registration mechanism, see Feature System Overview. For information about how logs are processed and batched, see Logs Handler. For channel-specific implementation details, see Log Feature and Channels.

---

Architecture Overview

The logging integration consists of two primary components: the LogFeature that registers custom Monolog drivers, and the channel implementations that configure Monolog loggers to send events to Sentry. The system provides two distinct channels with different capabilities:

Sources: src/Features/LogFeature.php1-29 src/LogChannel.php1-29

---

Channel Registration

The LogFeature class implements the feature lifecycle pattern and registers two custom Monolog drivers with Hypervel's logging system during the registration phase:

Channel Name	Class	Handler Type	Use Case
sentry	LogChannel	Sentry\Monolog\Handler	Standard error reporting with immediate event capture
sentry_logs	LogsLogChannel	LogsHandler	Advanced log aggregation with batching and filtering

The registration occurs in the register() method using the Log::extend() facade:

The isApplicable() method always returns true at src/Features/LogFeature.php13-16 meaning this feature is always enabled when the Sentry integration is active.

Sources: src/Features/LogFeature.php11-28

---

Standard Sentry Channel

The sentry channel uses the LogChannel class, which extends Hypervel\Log\LogManager to create Monolog logger instances configured with Sentry's standard handler.

Channel Factory Implementation

The factory method at src/LogChannel.php14-27 performs the following steps:

1. Hub Retrieval: Obtains the current Sentry Hub instance via SentrySdk::getCurrentHub() at src/LogChannel.php17
2. Handler Creation: Instantiates Sentry\Monolog\Handler with the hub and configured log level (defaulting to Logger::DEBUG) at src/LogChannel.php16-19
3. Handler Preparation: Calls prepareHandler() to apply any additional configuration at src/LogChannel.php24
4. Logger Instantiation: Creates a Monolog Logger with the parsed channel name and configured handler at src/LogChannel.php21-26

The prepareHandler() method is inherited from Hypervel\Log\LogManager and applies formatters and processors defined in the configuration.

Sources: src/LogChannel.php5-28

---

Advanced Logs Channel

The sentry_logs channel uses LogsLogChannel with a custom LogsHandler that provides enhanced capabilities:

Feature	Description
Batch Processing	Consolidates multiple related log entries into a single Sentry event to reduce noise
PII Filtering	Applies privacy filters to log data before transmission
Exception Bypass	Prevents duplicate events when exceptions are captured separately through error handlers
Logger Aggregator	Uses Sentry's structured logging API for richer log context

The LogsHandler integrates with Sentry's Logger Aggregator rather than directly capturing events through the Hub. This approach allows for:

• Structured log data with preserved context
• Automatic batching of consecutive log messages
• Enhanced filtering capabilities
• Better integration with Sentry's logs feature

Sources: High-level system diagrams (Diagram 6: Logging Integration Architecture)

---

Event Flow

The following diagram illustrates how log events flow through the system from application code to Sentry:

Sources: src/LogChannel.php1-29 High-level system diagrams (Diagram 6: Logging Integration Architecture)

---

Configuration

To use the Sentry logging channels, configure them in the application's config/logging.php file:

Standard Sentry Channel Configuration

The sentry channel requires minimal configuration:

The level parameter at src/LogChannel.php18 defaults to Logger::DEBUG if not specified, but is typically set to error or warning to avoid sending verbose logs to Sentry.

Advanced Logs Channel Configuration

The sentry_logs channel supports the same configuration parameters but uses the more sophisticated handler:

Multi-Channel Configuration

Both channels can be used simultaneously with Hypervel's stack driver:

This configuration writes logs to both the local file system and Sentry, providing redundant log storage.

Sources: src/LogChannel.php14-19 src/Features/LogFeature.php20-26

---

Integration with Sentry Features

The logging integration interacts with other Sentry components to provide enriched event context:

When a log message is sent to Sentry through either channel:

1. Scope Context: The current scope's user information, tags, and extra data are automatically attached to the event
2. Breadcrumbs: Previously recorded breadcrumbs (from cache operations, HTTP requests, etc.) are included for debugging context
3. Trace Context: If a performance transaction is active, the log event is associated with that transaction's trace
4. Coroutine Isolation: In Hypervel's coroutine environment, each coroutine maintains its own Sentry scope stack, ensuring logs from concurrent operations don't interfere

Sources: src/LogChannel.php17 High-level system diagrams (Diagram 4: Event Capture and Reporting Flow)

---

Handler Initialization

The LogChannel class retrieves the current Hub instance using the SentrySdk singleton at src/LogChannel.php17 This ensures that the Monolog handler uses the same Hub configuration established by the SentryServiceProvider:

This design allows the logging integration to:

• Respect the global Sentry configuration (DSN, environment, release, etc.)
• Share the same transport layer for efficient event batching
• Maintain consistent scope and context across all Sentry capture methods
• Support dynamic Hub replacement for testing scenarios

Sources: src/LogChannel.php16-19

---

Channel Name Resolution

The LogChannel class uses the parseChannel() method inherited from Hypervel\Log\LogManager to determine the channel name at src/LogChannel.php22 This method:

1. Extracts the channel name from the configuration array
2. Falls back to the application name if no channel name is specified
3. Ensures the channel name is valid and sanitized

The resolved channel name is used by Monolog to identify the logger instance and appears in Sentry events as the logger name, helping to distinguish between different log sources in the Sentry UI.

Sources: src/LogChannel.php21-26