Logs Handler

Purpose and Scope

The LogsHandler is a custom Monolog handler that provides advanced log processing for the Sentry integration. It extends the standard Sentry Monolog handler with two key features: batch consolidation to reduce noise by grouping related log messages, and exception filtering to prevent duplicate events when exceptions are also captured separately through Sentry's error tracking.

For information about how log channels are registered and configured, see Log Feature and Channels. For broader context on the logging integration architecture, see Logging Integration.

Sources: src/Logs/LogsHandler.php1-119

Overview

The LogsHandler class is used by the sentry_logs log channel to send application logs to Sentry's structured logging system. Unlike the standard sentry channel which uses Sentry's built-in Monolog handler for error reporting, LogsHandler is designed specifically for structured log data and implements specialized processing logic.

Diagram: LogsHandler in the Logging Flow

The handler sits between Monolog and Sentry's logger aggregator, processing log records before they are transmitted to the Sentry platform.

Sources: src/Logs/LogsHandler.php15-17 Diagram 6 from high-level architecture

Class Structure

The LogsHandler extends Monolog's AbstractProcessingHandler and uses Sentry's CompatibilityProcessingHandlerTrait for cross-version compatibility with the Sentry SDK.

Component	Type	Purpose
AbstractProcessingHandler	Base Class	Provides Monolog handler lifecycle
CompatibilityProcessingHandlerTrait	Trait	Ensures compatibility across Sentry SDK versions
$batchFormatter	Property	Formatter for consolidating multiple log records

Diagram: LogsHandler Class Structure

Sources: src/Logs/LogsHandler.php15-17

Batch Processing

The handleBatch() method processes multiple log records together, consolidating them into a single Sentry event. This reduces noise when an application generates multiple related log messages in quick succession.

Batch Processing Algorithm

Diagram: Batch Processing Flow

The algorithm works as follows:

1. Filter by Level src/Logs/LogsHandler.php28-34: Records below the handler's minimum level are discarded.

2. Find Highest Severity src/Logs/LogsHandler.php41-50: The record with the highest severity level becomes the "main" record. This ensures the Sentry event is categorized appropriately.

3. Process All Records src/Logs/LogsHandler.php53-56: Each record is processed through Monolog's record processor pipeline.

4. Format Batch src/Logs/LogsHandler.php58: All records are formatted using the batchFormatter (defaults to LineFormatter if not set).

5. Add to Context src/Logs/LogsHandler.php58: The formatted batch string is added to the main record's context under the key logs.

6. Handle Main Record src/Logs/LogsHandler.php60: The enriched main record is passed to the standard handle() method.

Batch Formatter Configuration

The batch formatter can be customized using setBatchFormatter() and getBatchFormatter():

Method	Purpose	Default
setBatchFormatter(FormatterInterface $formatter)	Set custom formatter for batch consolidation	-
getBatchFormatter()	Get current formatter, creating default if needed	LineFormatter

Sources: src/Logs/LogsHandler.php24-83

Exception Filtering

The doWrite() method implements exception filtering to prevent duplicate events. When a log record contains an exception in its context, the log is not sent to Sentry's logger aggregator. This is because exceptions are typically captured separately through Sentry's error tracking mechanism, and sending them as logs would create duplicate events.

Diagram: Exception Filtering Logic

The filtering logic src/Logs/LogsHandler.php90-96:

This prevents scenarios where:

• An exception is thrown
• The exception is logged (e.g., via Log::error($message, ['exception' => $e]))
• The exception is also captured by Sentry's error handler

Without this filter, Sentry would receive both an error event and a log event for the same exception.

Sources: src/Logs/LogsHandler.php90-96

Logger Aggregator Integration

The doWrite() method integrates with Sentry's logger aggregator system, which provides structured log data separate from error events. The aggregator collects log records and attaches them to the active transaction or event context.

Diagram: Logger Aggregator Integration

The integration src/Logs/LogsHandler.php98-106:

Key aspects:

• Sentry Logger Factory: \Sentry\logger() returns Sentry's global logger instance
• Aggregator: The aggregator() method provides access to the structured log collector
• Level Conversion: Monolog's integer level is converted to Sentry's Severity, then to LogLevel
• Context Merging: Both context and extra arrays from the Monolog record are merged and passed as context data

Sources: src/Logs/LogsHandler.php98-106

Severity Mapping

The LogsHandler converts between Monolog's numeric severity levels and Sentry's LogLevel enumeration through a two-step process:

1. Monolog Level → Sentry Severity: Handled by getSeverityFromLevel() from the CompatibilityProcessingHandlerTrait src/Logs/LogsHandler.php100-101

2. Sentry Severity → Sentry LogLevel: Handled by the private getLogLevelFromSeverity() method src/Logs/LogsHandler.php109-118

Mapping Table

Monolog Level	Sentry Severity	Sentry LogLevel
DEBUG (100)	Severity::debug()	LogLevel::debug()
INFO (200)	Severity::info()	LogLevel::info()
NOTICE (250)	Severity::info()	LogLevel::info()
WARNING (300)	Severity::warning()	LogLevel::warn()
ERROR (400)	Severity::error()	LogLevel::error()
CRITICAL (500)	Severity::fatal()	LogLevel::fatal()
ALERT (550)	Severity::fatal()	LogLevel::fatal()
EMERGENCY (600)	Severity::fatal()	LogLevel::fatal()

Conversion Implementation

Diagram: Severity Conversion Pipeline

The mapping uses a PHP match expression src/Logs/LogsHandler.php111-117 for precise type-safe conversion:

Note that Severity::warning() maps to LogLevel::warn() (not "warning"), following Sentry's LogLevel naming convention.

Sources: src/Logs/LogsHandler.php109-118

Usage Example

The LogsHandler is automatically configured when using the sentry_logs log channel. Application code can write logs that will be processed by this handler:

The handler ensures efficient transmission to Sentry while preventing duplicate events and reducing noise from related log messages.

Sources: src/Logs/LogsHandler.php1-119 Diagram 6 from high-level architecture