Cache Monitoring

Purpose and Scope

This document describes the CacheFeature implementation, which monitors Hypervel cache operations by creating breadcrumbs and performance tracing spans. The feature captures cache hits, misses, writes, and deletions, providing visibility into cache performance and usage patterns. For information about the feature system architecture and lifecycle, see Feature System Overview. For other monitoring features, see Queue Monitoring and Redis Monitoring.

The CacheFeature operates in two modes:

• Breadcrumb mode: Records cache events as context for error reports
• Tracing mode: Creates performance spans to measure cache operation timing and success rates

---

Architecture Overview

The CacheFeature extends the Feature base class and uses three utility traits to implement cache monitoring. It integrates with Hypervel's event system to intercept cache operations and report them to Sentry.

Class Composition

Component	Purpose
CacheFeature	Main feature class coordinating cache monitoring
WorksWithSpans	Provides methods to retrieve parent spans and manage tracing context
TracksPushedScopesAndSpans	Tracks span stack for proper nesting and cleanup
ResolvesEventOrigin	Determines source code location of events

Sources: src/Features/CacheFeature.php1-36

---

Feature Activation

The CacheFeature implements the isApplicable() method to determine whether it should be activated. The feature is enabled when either breadcrumb recording or tracing is enabled for the cache feature key.

During the boot phase, CacheFeature performs the following initialization:

1. Enable cache events: Sets events = true for all configured cache stores
2. Register breadcrumb listeners: If breadcrumb mode is enabled
3. Register tracing listeners: If tracing mode is enabled

Sources: src/Features/CacheFeature.php40-81

---

Cache Event Monitoring

The CacheFeature listens to ten distinct cache events that represent the complete lifecycle of cache operations. These events are emitted by Hypervel's cache system when cache operations occur.

Event Categories

Breadcrumb Events (completion events only):

• CacheHit: Cache key found and retrieved
• CacheMissed: Cache key not found
• KeyWritten: Cache key successfully written
• KeyForgotten: Cache key successfully deleted

Tracing Events (full lifecycle):

• RetrievingKey / RetrievingManyKeys: Cache retrieval initiated
• CacheHit / CacheMissed: Cache retrieval completed
• WritingKey / WritingManyKeys: Cache write initiated
• KeyWritten / KeyWriteFailed: Cache write completed
• ForgettingKey: Cache deletion initiated
• KeyForgotten / KeyForgetFailed: Cache deletion completed

Sources: src/Features/CacheFeature.php55-80

---

Breadcrumb Creation

Breadcrumbs provide context about cache operations when errors occur. The handleCacheEventsForBreadcrumbs() method creates breadcrumbs for four completion events.

Breadcrumb Format

Each breadcrumb includes:

• Level: INFO
• Type: DEFAULT
• Category: cache
• Message: Operation type and cache key (e.g., "Read: user:123")
• Data: Optional tags from the event

Operation Messages

Event	Message Prefix
CacheHit	"Read"
CacheMissed	"Missed"
KeyWritten	"Written"
KeyForgotten	"Forgotten"

Example breadcrumb trail:

cache: Written: user:123
cache: Read: user:123
cache: Missed: products:featured
cache: Forgotten: temp:xyz

Sources: src/Features/CacheFeature.php83-114

---

Performance Tracing

When tracing is enabled, CacheFeature creates child spans for each cache operation, measuring timing and recording metadata. Spans are created on operation initiation events and finished on completion events.

Span Lifecycle

The handleCacheEventsForTracing() method manages span creation and completion:

1. Check for completion events: Call maybeHandleCacheEventAsEndOfSpan() first
2. If not completion: Create new span using withParentSpanIfSampled()
3. If completion: Finish current span with status and additional data

Span Operations and Metadata

cache.get Span

• Created on: RetrievingKey, RetrievingManyKeys
• Finished on: CacheHit, CacheMissed
• Operation: cache.get
• Data:
  • cache.key: Array of cache keys
  • cache.hit: Boolean (added on finish, only for single key operations)
• Description: Comma-separated list of keys
• Origin: auto.cache

cache.put Span

• Created on: WritingKey, WritingManyKeys
• Finished on: KeyWritten, KeyWriteFailed
• Operation: cache.put
• Data:
  • cache.key: Array of cache keys
  • cache.ttl: Time-to-live in seconds
  • cache.success: Boolean (added on finish)
• Status: ok or internal_error based on success
• Description: Comma-separated list of keys
• Origin: auto.cache

cache.remove Span

• Created on: ForgettingKey
• Finished on: KeyForgotten, KeyForgetFailed
• Operation: cache.remove
• Data:
  • cache.key: Array containing single key
• Description: The cache key being removed
• Origin: auto.cache

Sources: src/Features/CacheFeature.php116-222

---

Privacy Protection: Session Key Handling

Cache keys may contain sensitive session identifiers. The CacheFeature automatically replaces session keys with the placeholder {sessionKey} to prevent PII exposure in Sentry reports.

Session Key Replacement Flow

Implementation Details

Method	Purpose
getSessionKey()	Retrieves current session ID from Hypervel's Session container
replaceSessionKey()	Replaces single key if it matches session ID
replaceSessionKeys()	Replaces session IDs in array of keys
normalizeKeyOrKeys()	Converts various key formats to string array

Exception Handling: The getSessionKey() method catches all exceptions and returns null, ensuring that session key replacement failures do not break cache monitoring. This is necessary because:

• The session container may not be bound in some contexts
• Session IDs are retrieved before session start (for session data cache retrieval)
• Multiple exception types can occur during container resolution

Sources: src/Features/CacheFeature.php224-288

---

Multi-Key Operation Support

The CacheFeature handles both single and multiple key operations, normalizing different key formats for consistent processing.

Key Normalization

The normalizeKeyOrKeys() method handles three input formats:

1. Single string key: "user:123" → ["user:123"]
2. Numeric array: ["key1", "key2"] → ["key1", "key2"]
3. Associative array: ["key1" => "value1", "key2" => "value2"] → ["key1", "key2"]

For associative arrays, the method extracts keys and discards values, as cache events may include both keys and values in the payload.

Many-Key Events

When handling RetrievingManyKeys or WritingManyKeys events:

• All keys are included in the span's cache.key data array
• The span description is a comma-separated list of all keys
• Session key replacement is applied to each key individually
• Cache hit/miss data is only added for single-key operations to avoid ambiguity

Sources: src/Features/CacheFeature.php123-143 src/Features/CacheFeature.php145-166 src/Features/CacheFeature.php279-288

---

Configuration

The CacheFeature is controlled through the Switcher system, which reads from the Sentry configuration file. Two independent flags control its behavior:

Configuration Key	Purpose	Methods Enabled
breadcrumbs.cache	Enable cache breadcrumbs	handleCacheEventsForBreadcrumbs()
tracing.cache	Enable cache performance tracing	handleCacheEventsForTracing()

Both flags can be enabled simultaneously for complete cache visibility.

Automatic Event Enablement

During the boot phase, CacheFeature automatically enables cache events for all configured cache stores by setting events = true in the cache store configuration. This is required because Hypervel's cache system only emits events when explicitly enabled.

This ensures that cache monitoring works without requiring manual configuration changes to cache store definitions.

Sources: src/Features/CacheFeature.php46-52