Last indexed: 14 February 2026 (15d5ca)

Configuration and Feature Flags

This document details the Sentry component's configuration system and feature flag architecture. The Sentry integration provides fine-grained control over which subsystems are enabled through a centralized Feature class and a comprehensive configuration file structure with 40+ toggleable features.

For information about the tracing architecture and how these flags control instrumentation behavior, see Distributed Tracing Architecture. For details on the AOP-based instrumentation that respects these flags, see AOP-Based Instrumentation.

Configuration File Overview

The Sentry configuration is published to config/autoload/sentry.php and consists of multiple sections controlling different aspects of the integration. The configuration supports both explicit values and environment variable defaults.

Primary Configuration Sections:

Section	Purpose	Configuration Keys
Core Settings	DSN, release, environment, sampling	`dsn`, `release`, `environment`, `sample_rate`, `traces_sample_rate`, `profiles_sample_rate`
Integration Toggles	Enable/disable subsystem tracing	`enable.*` (6 keys)
Breadcrumbs	Control breadcrumb collection	`breadcrumbs.*` (11 keys)
Tracing	Transaction-level tracing control	`tracing.*` (8 keys)
Tracing Spans	Span-level instrumentation control	`tracing_spans.*` (10 keys)
Tracing Tags	Additional span data inclusion	`tracing_tags.*` (7 keys)
Metrics	Metrics collection configuration	`enable_metrics`, `enable_*_metrics` (5 keys)
Crons	Cron monitoring configuration	`crons.*` (4 keys)
Transport	Transport layer settings	`transport_channel_size`, `transport_concurrent_limit`, `http_timeout`

Sources: src/sentry/publish/sentry.php1-186

Environment Variables and Defaults

The configuration file maps environment variables to configuration keys with sensible defaults. All boolean flags default to true to enable comprehensive monitoring out-of-the-box.

Core Environment Variables:

SENTRY_DSN - The Sentry DSN endpoint (required)
SENTRY_RELEASE - Application version identifier
SENTRY_SAMPLE_RATE - Error sampling rate (default: 1.0)
SENTRY_TRACES_SAMPLE_RATE - Transaction sampling rate (default: 1.0)
SENTRY_PROFILES_SAMPLE_RATE - Profiling sampling rate (default: null)
APP_ENV - Fallback for environment detection

Sources: src/sentry/publish/sentry.php14-44

The Feature Class

The Feature class provides a centralized interface for runtime feature flag checks. It abstracts the underlying configuration access and provides specialized methods for different flag categories.

Feature Class Methods:

Method	Configuration Path	Return Type	Purpose
`isEnabled(key, default)`	`sentry.enable.{key}`	bool	Check integration toggles
`isBreadcrumbEnabled(key, default)`	`sentry.breadcrumbs.{key}`	bool	Check breadcrumb collection
`isTracingEnabled(key, default)`	`sentry.tracing.{key}`	bool	Check transaction-level tracing
`isTracingSpanEnabled(key, default)`	`sentry.tracing_spans.{key}`	bool	Check span instrumentation (requires active span)
`isTracingTagEnabled(key, default)`	`sentry.tracing_tags.{key}`	bool	Check whether to include specific span tags
`isMetricsEnabled(default)`	`sentry.enable_metrics`	bool	Check overall metrics collection
`isDefaultMetricsEnabled(default)`	`sentry.enable_default_metrics`	bool	Check default metrics collection
`isCommandMetricsEnabled(default)`	`sentry.enable_command_metrics`	bool	Check command metrics
`isPoolMetricsEnabled(default)`	`sentry.enable_pool_metrics`	bool	Check pool metrics
`isQueueMetricsEnabled(default)`	`sentry.enable_queue_metrics`	bool	Check queue metrics
`getMetricsInterval(default)`	`sentry.metrics_interval`	int	Get metrics flush interval (min: 5s)
`isCronsEnabled()`	`sentry.crons.enable`	bool	Check cron monitoring

Sources: src/sentry/src/Feature.php1-133

Integration Toggle Configuration

The enable configuration section controls which high-level subsystems create transactions. These toggles determine whether entire categories of operations are traced.

Configuration Structure:

Integration Toggle Usage:

When an integration is disabled, the corresponding event handler returns early without creating a transaction. This prevents the creation of trace data for entire subsystems.

Sources: src/sentry/publish/sentry.php96-103 src/sentry/src/Tracing/Listener/EventHandleListener.php269-270 src/sentry/src/Tracing/Listener/EventHandleListener.php369-370 src/sentry/src/Tracing/Listener/EventHandleListener.php509-510

Breadcrumbs Configuration

Breadcrumbs capture contextual information during request processing. The breadcrumbs configuration controls which types of operations generate breadcrumb entries.

Breadcrumbs Configuration Structure:

Breadcrumb Aspects:

Aspect	Checks Flag	Breadcrumb Category	Data Captured
`LoggerAspect`	`breadcrumbs.logs`	`log.{level}`	Level, message, context
`BreadcrumbAspect` (cache)	`breadcrumbs.cache`	`cache`	Operation, key, hit/miss
`BreadcrumbAspect` (filesystem)	`breadcrumbs.filesystem`	`filesystem`	Operation, path
`BreadcrumbAspect` (guzzle)	`breadcrumbs.guzzle`	`http`	Method, URL, status
`BreadcrumbAspect` (SQL)	`breadcrumbs.sql_queries`	`query`	SQL, bindings, duration
`BreadcrumbAspect` (Redis)	`breadcrumbs.redis`	`redis`	Command, arguments, result

Sources: src/sentry/publish/sentry.php106-118 src/sentry/src/Aspect/LoggerAspect.php42-44

Tracing Configuration

The tracing configuration controls transaction-level tracing for different subsystems. These flags determine which event types create transactions.

Tracing Configuration Structure:

Tracing vs Enable Distinction:

enable.* - Controls whether the EventHandleListener handles events at all
tracing.* - Controls whether specific event handlers create transactions (checked after enable.*)

Example: enable.request=false prevents all HTTP request handling, while tracing.request=false with enable.request=true allows event handling without creating transactions.

Sources: src/sentry/publish/sentry.php135-144

Tracing Spans Configuration

The tracing_spans configuration provides granular control over which operations create child spans within a transaction. Each span type corresponds to a specific AOP aspect.

Tracing Spans Configuration Structure:

Span Creation Flow:

Key Implementation Detail: isTracingSpanEnabled() returns false if no active span exists, automatically disabling span instrumentation outside of transaction contexts.

Sources: src/sentry/publish/sentry.php147-159 src/sentry/src/Feature.php91-98 src/sentry/src/Tracing/Aspect/DbConnectionAspect.php41-42 src/sentry/src/Tracing/Aspect/RedisConnectionAspect.php41-42

Tracing Tags Configuration

The tracing_tags configuration controls whether sensitive or verbose data is included in span attributes. These flags default to false for security and performance.

Tracing Tags Configuration Structure:

Tag Inclusion Logic:

The db.sql.bindings flag defaults to true because query parameter visibility is valuable for debugging. Other result flags default to false to prevent accidental exposure of sensitive data.

Sources: src/sentry/publish/sentry.php162-171 src/sentry/src/Tracing/Listener/EventHandleListener.php200-202

Metrics Configuration

The metrics system provides hierarchical configuration with an overall toggle and subsystem-specific flags.

Metrics Configuration Structure:

Metrics Feature Check Hierarchy:

Method	Checks	Returns `false` if
`isMetricsEnabled()`	`enable_metrics`	Base flag is false
`isDefaultMetricsEnabled()`	`enable_metrics` AND `enable_default_metrics`	Either flag is false
`isCommandMetricsEnabled()`	`enable_metrics` AND `enable_command_metrics`	Either flag is false
`isPoolMetricsEnabled()`	`enable_metrics` AND `enable_pool_metrics`	Either flag is false
`isQueueMetricsEnabled()`	`enable_metrics` AND `enable_queue_metrics`	Either flag is false

Metrics Interval: The metrics_interval determines how frequently metrics are flushed to Sentry. The minimum value is 5 seconds.

Sources: src/sentry/publish/sentry.php54-70 src/sentry/src/Feature.php34-84 src/sentry/src/Metrics/Listener/RequestWatcher.php45-46

Crons Monitoring Configuration

The crons configuration controls Sentry's cron check-in monitoring feature, which tracks scheduled task execution.

Crons Configuration Structure:

Cron Monitoring Parameters:

Parameter	Type	Default	Purpose
`enable`	bool	`true`	Enable/disable cron monitoring
`checkin_margin`	int	`5`	Minutes of acceptable delay before alert
`max_runtime`	int	`15`	Maximum expected runtime in minutes
`timezone`	string	System timezone	Timezone for schedule evaluation

Per-crontab configuration can override these defaults through the options array on crontab definitions.

Sources: src/sentry/publish/sentry.php174-179 src/sentry/src/Crons/Listener/EventHandleListener.php79-84 src/sentry/src/Crons/Listener/EventHandleListener.php131-154

Additional Configuration Options

Ignored Exceptions:

Exceptions matching these classes are not captured by Sentry.

Ignored Transactions:

Transactions matching these patterns are not sent to Sentry.

Ignored Commands:

Commands matching these patterns (supports wildcards via Str::is()) do not create transactions.

Sources: src/sentry/publish/sentry.php79-132 src/sentry/src/Tracing/Listener/EventHandleListener.php68-75

Transport Configuration

The transport layer configuration controls how events are buffered and sent to Sentry.

Transport Configuration Structure:

Transport Parameters:

Parameter	Type	Default	Purpose
`transport_channel_size`	int	`65535`	Size of the channel buffer for async event transmission
`transport_concurrent_limit`	int	`1000`	Maximum concurrent HTTP requests to Sentry
`http_timeout`	float	`2.0`	HTTP request timeout in seconds

The custom CoHttpTransport uses these parameters to implement efficient async event transmission using Hyperf's coroutine features.

Sources: src/sentry/publish/sentry.php182-185

Configuration Resolution Flow

The configuration resolution process involves multiple stages from environment variables to runtime checks.

Key Resolution Points:

Environment Variables - Check for SENTRY_* variables via env() helper
Configuration File Defaults - Use hardcoded defaults if environment variable is null
Options Validation - ClientBuilderFactory filters valid Sentry SDK options using OptionsResolver
Runtime Checks - Feature class methods provide consistent access to flags

The ClientBuilderFactory uses reflection to access the private $resolver property of Sentry\Options to determine valid configuration keys, ensuring only SDK-recognized options are passed to the ClientBuilder.

Sources: src/sentry/src/Factory/ClientBuilderFactory.php30-75 src/sentry/src/Feature.php20-22

Feature Flag Usage Patterns

Pattern 1: Early Return on Disabled Feature

Pattern 2: Conditional Span Creation

Pattern 3: Conditional Data Inclusion

Pattern 4: Hierarchical Metrics Checks

Sources: src/sentry/src/Tracing/Aspect/DbConnectionAspect.php40-43 src/sentry/src/Tracing/Listener/EventHandleListener.php269-271 src/sentry/src/Tracing/Listener/EventHandleListener.php200-202 src/sentry/src/Metrics/Listener/RequestWatcher.php45-48

Refresh this wiki

URL: https://deepwiki.com/friendsofhyperf/components/2.1-configuration-and-feature-flags