Configuration

Purpose and Scope

This document explains the configuration system for the hypervel/sentry package. It details all available configuration options in config/sentry.php and describes how the Switcher class provides runtime control over Sentry features, breadcrumbs, and tracing behavior.

For information about how features use these configuration settings, see Feature System Overview. For information about the service provider that initializes the configuration, see Service Provider.

---

Configuration File Structure

The package's configuration is defined in config/sentry.php1-135 This file serves two purposes: configuring the underlying Sentry PHP SDK and controlling package-specific features like breadcrumb capture and performance tracing.

Configuration File Organization

Sources: config/sentry.php1-135

---

Core SDK Settings

These settings configure the underlying Sentry PHP SDK and are passed directly to the SDK's Options object after specific keys are removed (see Hub and Factories for details on configuration merging).

Basic Configuration

Configuration Key	Environment Variable	Type	Default	Description
dsn	SENTRY_DSN	string	''	Sentry Data Source Name - the endpoint for sending events
release	SENTRY_RELEASE	string	null	Release version identifier (e.g., git commit hash)
environment	APP_ENV	string	'production'	Application environment name
default_integrations	SENTRY_DEFAULT_INTEGRATIONS	bool	false	Whether to enable Sentry SDK's default integrations
send_default_pii	SENTRY_SEND_DEFAULT_PII	bool	false	Whether to send personally identifiable information

Sources: config/sentry.php20-30 config/sentry.php54-55 config/sentry.php22-23

Sampling Configuration

Sampling controls what percentage of events and traces are sent to Sentry, allowing cost and performance optimization.

Configuration Key	Environment Variable	Type	Default	Description
sample_rate	SENTRY_SAMPLE_RATE	float	1.0	Error event sampling rate (0.0-1.0)
traces_sample_rate	SENTRY_TRACES_SAMPLE_RATE	float	1.0	Transaction/trace sampling rate (0.0-1.0)
profiles_sample_rate	SENTRY_PROFILES_SAMPLE_RATE	float	null	Profiling sampling rate (0.0-1.0)

Configuration Flow Diagram

Sources: config/sentry.php32-49

Logging Configuration

Configuration Key	Environment Variable	Type	Default	Description
enable_logs	SENTRY_ENABLE_LOGS	bool	false	Enable log aggregation feature (requires Sentry plan support)

Sources: config/sentry.php51-52

---

Feature Control System

The enable configuration section provides high-level toggles for package features. Currently, only coroutine context propagation is configurable here.

Enable Configuration Structure

Configuration Key	Environment Variable	Type	Default	Description
enable.coroutine	SENTRY_ENABLE_COROUTINE	bool	true	Enable Sentry context propagation in coroutines

Sources: config/sentry.php57-59

---

Breadcrumb Configuration

Breadcrumbs are lightweight event logs that provide context for errors. The breadcrumbs configuration section controls which framework operations generate breadcrumbs.

Breadcrumb Configuration Mapping

Configuration Key	Environment Variable	Default	Captured Operations
breadcrumbs.cache	SENTRY_BREADCRUMBS_CACHE	true	Cache hits, misses, writes, deletes
breadcrumbs.sql_queries	SENTRY_BREADCRUMBS_SQL_QUERIES	true	SQL query execution
breadcrumbs.sql_bindings	SENTRY_BREADCRUMBS_SQL_BINDINGS	true	SQL query parameter values
breadcrumbs.sql_transaction	SENTRY_BREADCRUMBS_SQL_TRANSACTION	true	Transaction begin, commit, rollback
breadcrumbs.queue_info	SENTRY_BREADCRUMBS_QUEUE_INFO_ENABLED	true	Queue job dispatch and processing
breadcrumbs.notifications	SENTRY_BREADCRUMBS_NOTIFICATIONS_ENABLED	true	Notification sending events
breadcrumbs.guzzle	SENTRY_BREADCRUMBS_GUZZLE	true	Guzzle HTTP client requests

Sources: config/sentry.php61-76

Breadcrumb Flow Through Switcher

Sources: config/sentry.php61-76 src/Switcher.php20-23

---

Tracing Configuration

The tracing configuration section controls performance monitoring. Tracing captures operation duration as spans, allowing performance analysis in Sentry.

Global Tracing Toggle

Configuration Key	Environment Variable	Type	Default	Description
enable_tracing	SENTRY_ENABLE_TRACING	bool	true	Master switch for all performance tracing

Per-Feature Tracing Configuration

Configuration Key	Environment Variable	Default	Traced Operations
tracing.queue_jobs	SENTRY_TRACE_QUEUE_JOBS_ENABLED	true	Queue jobs on sync driver
tracing.queue_job_transactions	SENTRY_TRACE_QUEUE_ENABLED	true	Queue jobs as root transactions
tracing.cache	SENTRY_TRACE_CACHE_ENABLED	true	Cache operations (get, set, etc.)
tracing.notifications	SENTRY_TRACE_NOTIFICATIONS_ENABLED	true	Notification sending
tracing.redis_commands	SENTRY_TRACE_REDIS_COMMANDS	true	Redis command execution
tracing.redis_origin	SENTRY_TRACE_REDIS_ORIGIN_ENABLED	true	Source code origin for Redis commands

Sources: config/sentry.php36 config/sentry.php111-124

Tracing Decision Logic

Sources: src/Switcher.php25-32

---

Integration and Feature Lists

The configuration defines which Sentry SDK integrations and package features are registered during service provider initialization.

Integrations Array

The integrations array lists Sentry SDK integration classes that enrich events with contextual information.

Integration Class	Purpose
RequestIntegration	Enriches events with HTTP request data when PII sending is enabled
TransactionIntegration	Manages transaction state in the SDK
FrameContextifierIntegration	Adds source code context to stack frames
EnvironmentIntegration	Captures environment variables

For more details on RequestIntegration, see Request Integration.

Sources: config/sentry.php78-83

Features Array

The features array lists package feature classes that provide framework-specific monitoring capabilities.

Feature Class	Purpose	Documentation
CacheFeature	Cache operation monitoring	Cache Monitoring
QueueFeature	Queue job tracing and breadcrumbs	Queue Monitoring
NotificationsFeature	Notification sending monitoring	Monitoring Features
LogFeature	Log channel integration	Log Feature and Channels
ConsoleSchedulingFeature	Scheduled task monitoring	Console Scheduling
DbQueryFeature	SQL query and Redis command tracing	Redis Monitoring

Sources: config/sentry.php85-92

Feature Registration Flow

Sources: config/sentry.php85-92

---

Ignore Lists

Ignore lists allow filtering out specific exceptions, transactions, or commands from being reported to Sentry.

Ignore Exceptions

The ignore_exceptions array lists exception classes that should not be captured.

Sources: config/sentry.php94-96

Ignore Transactions

The ignore_transactions array lists transaction name patterns that should not be captured. This is useful for excluding health check endpoints or internal routes.

Sources: config/sentry.php98-99

Ignore Commands

The ignore_commands array lists console command patterns that should not create transactions. Wildcard patterns (*) are supported.

Sources: config/sentry.php101-108

---

HTTP and Transport Configuration

These settings control how the package communicates with the Sentry API.

HTTP Timeout

Configuration Key	Environment Variable	Type	Default	Description
http_timeout	SENTRY_HTTP_TIMEOUT	float	2.0	HTTP request timeout in seconds

Sources: config/sentry.php126

Connection Pool Configuration

The pool configuration controls the HTTP connection pool used by HttpPoolTransport for efficient connection reuse.

Pool Setting	Type	Default	Description
min_objects	int	1	Minimum number of pooled connections
max_objects	int	10	Maximum number of pooled connections
wait_timeout	float	3.0	Maximum seconds to wait for available connection
max_lifetime	float	60.0	Maximum seconds a connection can live

Sources: config/sentry.php128-134

Connection Pool Architecture

Sources: config/sentry.php128-134

---

The Switcher Class

The Switcher class provides a centralized API for checking configuration state at runtime. Features use this class to determine whether to capture breadcrumbs or create spans.

Switcher Class Structure

Sources: src/Switcher.php1-33

Method Reference

isEnabled(string $key, bool $default = true): bool

Checks if a feature is enabled under the sentry.enable.* configuration namespace.

Configuration key: sentry.enable.{$key}
Returns: Boolean value from configuration, or $default if not set

Example Usage:

Sources: src/Switcher.php15-18

isBreadcrumbEnable(string $key): bool

Checks if breadcrumb capture is enabled for a specific operation type.

Configuration key: sentry.breadcrumbs.{$key}
Returns: Boolean value from configuration, defaults to true

Example Usage:

Sources: src/Switcher.php20-23

isTracingEnable(string $key): bool

Checks if tracing is enabled for a specific operation type. This method implements two-level checking:

1. First checks the global sentry.enable_tracing flag
2. If enabled, checks the specific sentry.tracing.{$key} flag

Configuration keys: 
 - sentry.enable_tracing (global)
 - sentry.tracing.{$key} (specific)
Returns: true only if both checks pass

Example Usage:

Sources: src/Switcher.php25-32

Configuration Key Resolution

The following diagram shows how Switcher method calls map to configuration keys:

Sources: src/Switcher.php15-32

Switcher Usage in Features

Features inject the Switcher class and use it to make runtime decisions about breadcrumb and span creation:

Sources: src/Switcher.php1-33

---

Configuration Best Practices

Environment-Specific Configuration

Use environment variables to manage configuration across development, staging, and production:

Sources: config/sentry.php1-135

Performance Optimization

Reduce overhead by disabling unnecessary breadcrumbs and tracing in high-traffic scenarios:

Sources: config/sentry.php32-49 config/sentry.php61-76

Privacy Considerations

When handling sensitive data, disable PII sending and SQL binding capture:

Sources: config/sentry.php54-55 config/sentry.php66-67