Monitoring Features

Purpose and Scope

This document provides an overview of the monitoring features system in the hypervel/sentry package. Monitoring features are modular, pluggable components that integrate with specific Hypervel framework subsystems (cache, queues, Redis, scheduled tasks, etc.) to automatically capture telemetry data and send it to Sentry.

The feature system provides:

• Automatic discovery and registration of monitoring capabilities
• Granular control over which features are enabled
• Conditional creation of breadcrumbs and tracing spans
• Event-driven architecture for capturing framework operations

For detailed information about specific features, see:

• Cache monitoring: Cache Monitoring
• Queue monitoring: Queue Monitoring
• Redis monitoring: Redis Monitoring
• Console scheduling: Console Scheduling
• Logging integration: Logging Integration

For information about the underlying service provider that orchestrates features, see Service Provider.

---

Feature System Architecture

The feature system is organized around a base Feature class that provides common functionality, with concrete feature implementations extending this base class. Features are discovered from configuration, registered with the DI container, and booted during application startup.

Feature Architecture Diagram

Sources: src/SentryServiceProvider.php110-142 src/Features/CacheFeature.php32-44

---

Feature Lifecycle

Features go through a two-phase initialization process managed by the SentryServiceProvider:

1. Registration Phase: Features are bound to the DI container and their register() method is called
2. Boot Phase: Features' boot() method is called to set up event listeners and framework integrations

Feature Lifecycle Sequence

Sources: src/SentryServiceProvider.php110-142 src/Features/CacheFeature.php40-81

---

Feature Discovery and Registration

Features are discovered from the sentry.features configuration array. The service provider iterates through this list, binding each feature class to the container and calling its lifecycle methods.

Registration Process

The registration process is defined in SentryServiceProvider:

registerFeatures() → for each feature:
 1. Bind feature class to container
 2. Resolve feature instance from container
 3. Call feature->register()
 4. Catch and suppress any exceptions

Key Implementation Details:

Aspect	Implementation	Location
Feature list source	$this->app->get(ConfigInterface::class)->get('sentry.features', [])	src/SentryServiceProvider.php112
Container binding	$this->app->bind($feature, $feature)	src/SentryServiceProvider.php114
Exception handling	try { ... } catch (Throwable $e) { }	src/SentryServiceProvider.php118-125
Purpose of suppression	Ensures features do not break the application	src/SentryServiceProvider.php124

Boot Process

After registration, features are booted in the same order:

bootFeatures() → for each feature:
 1. Resolve feature instance from container
 2. Call feature->boot()
 3. Feature checks if it's applicable
 4. Feature registers event listeners
 5. Catch and suppress any exceptions

The boot() method calls the template method onBoot() after checking applicability via isApplicable(). Each feature implements onBoot() to perform its specific initialization.

Sources: src/SentryServiceProvider.php110-142

---

Conditional Activation via Switcher

The Switcher class provides three-level control over feature activation:

1. Feature-level enablement: Whether the entire feature is active
2. Breadcrumb enablement: Whether breadcrumbs should be created
3. Tracing enablement: Whether tracing spans should be created

Switcher Decision Tree

Switcher Methods

Method	Purpose	Configuration Key	Default
isEnabled(string $key)	Check if a feature is globally enabled	sentry.enable.{key}	true
isBreadcrumbEnable(string $key)	Check if breadcrumbs are enabled for a feature	sentry.breadcrumbs.{key}	true
isTracingEnable(string $key)	Check if tracing is enabled for a feature	sentry.tracing.{key} and sentry.enable_tracing	true

Example from CacheFeature:

The CacheFeature determines applicability by checking if either breadcrumbs or tracing are enabled:

If applicable, it registers different event listeners based on which capabilities are enabled (see src/Features/CacheFeature.php55-80).

Sources: src/Switcher.php1-34 src/Features/CacheFeature.php40-44

---

Common Feature Patterns

All features follow common patterns for integrating with the framework and Sentry:

Event Listener Pattern

Features register event listeners during the boot phase to capture framework operations:

Example Event Registration:

From CacheFeature::onBoot():

Capability	Events Listened To	Handler Method
Breadcrumbs	CacheHit, CacheMissed, KeyWritten, KeyForgotten	handleCacheEventsForBreadcrumbs
Tracing	RetrievingKey, RetrievingManyKeys, CacheHit, CacheMissed, WritingKey, WritingManyKeys, KeyWritten, KeyWriteFailed, ForgettingKey, KeyForgotten, KeyForgetFailed	handleCacheEventsForTracing

Breadcrumb Creation Pattern

Features create breadcrumbs to record significant events without detailed timing information:

Event occurs → Feature handler called → Create Breadcrumb object → 
 Integration.addBreadcrumb() → Sent to Hub

Breadcrumbs include:

• Level (info, warning, error)
• Type (default, http, navigation, etc.)
• Category (identifies the subsystem)
• Message (human-readable description)
• Data (optional structured metadata)

Tracing Span Pattern

Features create spans to measure the performance of operations:

Start Event → Create span with parent → Store span in stack →
 End Event → Finish span with status → Remove from stack

Spans include:

• Operation (e.g., cache.get, cache.put)
• Description (human-readable, often includes keys)
• Data (structured metadata like keys, TTL, etc.)
• Origin (identifies automatic instrumentation source)
• Status (ok, error, etc.)

Example Span Creation:

From CacheFeature for cache retrieval:

RetrievingKey event → Start child span with op='cache.get' →
 Store span in stack → CacheHit/CacheMissed event →
 Finish span with status=ok → Add cache.hit data

Sources: src/Features/CacheFeature.php46-81 src/Features/CacheFeature.php83-114 src/Features/CacheFeature.php116-222

---

Available Monitoring Features

The following table summarizes the monitoring features available in the package:

Feature Class	Feature Key	Purpose	Breadcrumbs	Tracing	Importance Score
CacheFeature	cache	Monitor cache operations (hits, misses, writes, deletes)	✓	✓	8.51
QueueFeature	queue	Monitor queue job lifecycle and distributed tracing	✓	✓	6.53
LogFeature	log	Route logs to Sentry via custom log channels	✗	✗	5.64
RedisFeature	redis	Monitor Redis command execution	✗	✓	N/A
ConsoleSchedulingFeature	console	Monitor scheduled tasks with cron check-ins	✗	✓	N/A
NotificationsFeature	notifications	Monitor notification sending	✗	✓	N/A

Feature-Specific Characteristics

CacheFeature:

• Redacts session keys in breadcrumbs and spans for privacy (src/Features/CacheFeature.php247-269)
• Tracks cache hit/miss ratios via span data
• Normalizes single and multiple key operations

QueueFeature:

• Modifies job payloads to propagate trace context across process boundaries
• Creates transactions for job processing
• Captures job failures as exceptions

LogFeature:

• Extends Hypervel's logging facade with Sentry channels
• Does not use the standard breadcrumb/tracing pattern
• See Logging Integration for details

RedisFeature:

• Captures Redis command names and execution time
• Integrates with Hypervel's Redis event system

ConsoleSchedulingFeature:

• Adds sentryMonitor() macro to scheduled task builder
• Sends Sentry check-in events for cron monitoring

Sources: src/Features/CacheFeature.php32-288 src/SentryServiceProvider.php110-142

---

Integration with Hub

All features ultimately send telemetry data to the Hub, which manages the Sentry client and scope. The Hub provides the central API for:

• addBreadcrumb(): Add breadcrumb to current scope
• startTransaction(): Begin a new transaction (top-level trace)
• getTransaction(): Retrieve current transaction
• Span->startChild(): Create child span
• captureException(): Send exception to Sentry
• captureMessage(): Send message to Sentry

Features typically access the Hub through dependency injection or via the Integration class's static methods.

For details on the Hub architecture, see Hub and Factories.

Sources: src/Features/CacheFeature.php105-113