Redis Monitoring

The RedisFeature class provides automatic tracing for Redis command execution in Hyperf applications. It captures performance metrics, connection pool statistics, and command details as Sentry spans for distributed tracing and performance analysis.

Related documentation: Cache monitoring is covered in page 3.2, feature system architecture in page 3.1.

Overview

The RedisFeature class listens to Hyperf's CommandExecuted events from the Redis layer and creates child spans under the current transaction. Each span captures command details, execution timing, connection pool metrics, and optional code origin information. Session key masking prevents sensitive data leakage in span data.

Sources: src/Features/RedisFeature.php1-148

Component Architecture

Component interaction diagram showing code entities:

Sources: src/Features/RedisFeature.php1-148

Feature Activation

Feature lifecycle and configuration:

The isApplicable() method checks if redis_commands tracing is enabled via the Switcher. When applicable, onBoot() ensures database.connections.redis.event is enabled and registers handleRedisCommands() as a listener for CommandExecuted events.

Sources: src/Features/RedisFeature.php23-36

Command Processing Pipeline

The handleRedisCommands() method processes each Redis command execution:

Sources: src/Features/RedisFeature.php38-99

Span Data Structure

Each Redis command span contains the following data fields:

Field	Source	Description
coroutine.id	Coroutine::id()	Current coroutine ID for async tracking
db.system	Static	Always 'redis'
db.statement	Computed	Uppercase command + key (e.g., "GET {sessionKey}")
db.redis.connection	event->connectionName	Connection pool name
db.redis.database_index	config['redis.{connection}']['db']	Redis database number (default 0)
db.redis.parameters	event->parameters	Command arguments (optionally masked)
db.redis.pool.name	event->connectionName	Pool identifier
db.redis.pool.max	pool->getOption()->getMaxConnections()	Maximum pool size
db.redis.pool.max_idle_time	pool->getOption()->getMaxIdleTime()	Connection idle timeout
db.redis.pool.idle	pool->getConnectionsInChannel()	Available connections
db.redis.pool.using	pool->getCurrentConnections()	Active connections
duration	event->time * 1000	Execution time in milliseconds

SpanContext Configuration

The span context is configured with:

• Operation: 'db.redis'
• Origin: 'auto.cache.redis'
• Description: Uppercase command with masked key
• Start timestamp: microtime(true) - event->time / 1000
• End timestamp: Start timestamp + execution time

Command Description Construction

The db.statement field is constructed from the command and first parameter:

1. Command is converted to uppercase via strtoupper($event->command)
2. First parameter is used as key description if it is a string without newlines
3. Session keys are replaced with '{sessionKey}' placeholder via replaceSessionKey()
4. Result is trimmed: rtrim(strtoupper($event->command) . ' ' . $keyForDescription)

Empty or complex parameters result in '{empty key}' as the key description.

Sources: src/Features/RedisFeature.php50-83 src/Features/RedisFeature.php140-147

Privacy and PII Handling

Session Key Masking

The RedisFeature masks session keys to prevent sensitive session identifiers from being sent to Sentry:

Key Methods:

• getSessionKey(): Retrieves the current session ID via Session::getId(). Returns null if session is unavailable. Catches generic exceptions to prevent application breakage.

• replaceSessionKey(): Replaces a single value with '{sessionKey}' if it matches the session ID. Returns '{empty key}' for non-string values.

• replaceSessionKeys(): Applies masking to an array of values using array_map().

Application Points:

1. Command description (db.statement): Always masked via replaceSessionKey() on the first parameter
2. Parameter array (db.redis.parameters): Masked via replaceSessionKeys() only when shouldSendDefaultPii() returns true

Sources: src/Features/RedisFeature.php85-87 src/Features/RedisFeature.php104-147

Origin Resolution

When the redis_origin tracing configuration is enabled, the feature adds code origin information to each span:

The resolveEventOrigin() method is provided by the ResolvesEventOrigin trait (documented in page 6.2). It analyzes the debug backtrace to identify the source code location (file, line, function) that triggered the Redis command.

Origin data is conditionally merged into the span data only when:

1. switcher->isTracingEnable('redis_origin') returns true
2. resolveEventOrigin() successfully resolves origin information (returns non-null)

Sources: src/Features/RedisFeature.php13 src/Features/RedisFeature.php89-95

Integration Points

Event System Integration

The feature integrates with Hyperf's event dispatcher to listen for CommandExecuted events from the Redis layer. It requires Redis event emission to be enabled in the database configuration.

Configuration Dependencies

• Switcher Configuration: Controls feature activation and origin resolution
• Database Configuration: Must enable Redis events
• Redis Configuration: Provides connection-specific settings
• Container Services: Accesses PoolFactory, ConfigInterface, Dispatcher, and Session

Sentry SDK Integration

The feature creates child spans under existing transactions with:

• Operation type: db.redis
• Origin: auto.cache.redis
• Timestamps calculated from event timing data
• Comprehensive metadata attached as span data

Sources: src/Features/RedisFeature.php28-36 src/Features/RedisFeature.php78-98