Configuration

Purpose and Scope

This document provides comprehensive documentation of Telescope's configuration system, covering all available settings in the config/telescope.php configuration file. It explains core settings, watcher-specific options, and filtering/privacy controls that govern Telescope's behavior.

For information about how the configuration is loaded and applied during bootstrap, see Service Provider and Bootstrap. For details on individual watcher implementations, see Watchers System.

Sources: config/telescope.php1-222

---

Configuration File Overview

Telescope uses a single configuration file located at config/telescope.php that controls all aspects of the system's behavior. The configuration is organized into several logical groups:

• Master Controls: Global enable/disable switches
• Web Interface Settings: Domain, path, and middleware configuration
• Storage Configuration: Database driver and connection settings
• Performance Tuning: Deferred storage and queue configuration
• Path Filtering: URI and command filtering rules
• Watcher Settings: Individual watcher enable/disable and options

The configuration file supports environment variable overrides using the env() helper function, allowing different settings across development, staging, and production environments without modifying the configuration file itself.

Configuration Loading and Access Pattern

Configuration Access Methods:

Method	Code Reference	Purpose
Telescope::isEnabled()	src/Telescope.php	Checks master enabled flag
config('telescope.path')	Throughout codebase	Retrieves specific config values
$this->options	Watcher classes	Accesses watcher-specific options

Sources: config/telescope.php1-222 src/Telescope.php src/TelescopeServiceProvider.php

---

Core Settings

Master Switch

The enabled configuration option provides a single control point to disable all Telescope functionality regardless of individual watcher settings. When set to false, no watchers will record data and the Telescope system becomes dormant.

Configuration Key	Environment Variable	Default	Type	Purpose
enabled	TELESCOPE_ENABLED	true	boolean	Master switch for all Telescope functionality

Use Cases:

• Completely disable Telescope in production without uninstalling the package
• Temporarily halt all monitoring during maintenance windows
• Override all individual watcher settings with a single flag

Sources: config/telescope.php22

---

Web Interface Access Control

Telescope's web interface is accessible via HTTP routes that can be customized using domain and path settings. These settings control where the Vue.js dashboard is mounted within your application.

Configuration Key	Environment Variable	Default	Type	Purpose
domain	TELESCOPE_DOMAIN	null	string|null	Subdomain for Telescope UI (null = same domain as app)
path	TELESCOPE_PATH	'telescope'	string	URI path where Telescope is accessible

Examples:

• Default: https://yourapp.com/telescope
• Custom path: Set TELESCOPE_PATH=admin/debug → https://yourapp.com/admin/debug
• Custom subdomain: Set TELESCOPE_DOMAIN=telescope.yourapp.com → https://telescope.yourapp.com/telescope

Sources: config/telescope.php35-48

---

Storage Configuration

Telescope uses a driver-based storage system with database as the default driver. The storage configuration defines which persistence mechanism is used and its connection parameters.

Configuration Key	Environment Variable	Default	Type	Purpose
driver	TELESCOPE_DRIVER	'database'	string	Storage driver identifier
storage.database.connection	DB_CONNECTION	'mysql'	string	Database connection name
storage.database.chunk	-	1000	integer	Batch insert chunk size

Driver Details:

• database: Stores entries in MySQL/PostgreSQL using three tables (see Database Schema)
• The chunk setting controls how many entries are inserted in a single batch query to optimize performance
• Custom drivers can be implemented by extending the repository interfaces (see Repository Pattern)

Sources: config/telescope.php61-68

---

Deferred Storage and Queue Configuration

To minimize performance impact on the host application, Telescope supports deferred storage where entry persistence is handled asynchronously via queue jobs.

Deferred Storage Settings

Configuration Key	Environment Variable	Default	Type	Purpose
defer	TELESCOPE_STORE_DEFER	true	boolean	Enable asynchronous storage via queue

When defer is enabled, Telescope dispatches ProcessPendingUpdates jobs to handle database writes in the background, preventing the monitoring overhead from blocking request responses.

Queue Configuration Settings

Configuration Key	Environment Variable	Default	Type	Purpose
queue.connection	TELESCOPE_QUEUE_CONNECTION	null	string|null	Queue connection to use (null = default)
queue.queue	TELESCOPE_QUEUE	null	string|null	Queue name (null = default queue)
queue.delay	TELESCOPE_QUEUE_DELAY	10	integer	Delay in seconds before processing jobs

Deferred Storage Configuration Flow

Code References:

• Deferred storage: src/Telescope.php
• Job class: src/Jobs/ProcessPendingUpdates.php
• Queue configuration: config/telescope.php93-97

Sources: config/telescope.php80-97 src/Telescope.php src/Jobs/ProcessPendingUpdates.php

Delay Strategy: The default 10-second delay allows multiple entries from related operations to be batched together, reducing database write operations.

Sources: config/telescope.php80-97

---

Middleware Configuration

Telescope's web routes are protected by a middleware stack that controls access to the dashboard. The default configuration includes web middleware for session handling and the Authorize middleware for access control.

Configuration Key	Environment Variable	Default	Type	Purpose
middleware	-	['web', Authorize::class]	array	Middleware stack for Telescope routes

Middleware Components:

• web: Provides session, CSRF protection, and cookie encryption (standard Hypervel middleware group)
• Authorize: Custom authorization middleware that determines who can access Telescope (see src/Http/Middleware/Authorize.php)

Customization: You can add additional middleware to this array or replace the Authorize middleware with your own custom authorization logic.

Sources: config/telescope.php110-113 src/Http/Middleware/Authorize.php

---

Watcher Configuration

Telescope monitors application behavior through a plugin architecture of specialized watchers. Each watcher can be independently enabled, disabled, and configured through the watchers array in the configuration file.

Watcher Configuration Patterns

Watchers follow two configuration patterns:

Pattern 1: Simple Boolean Enable/Disable

Pattern 2: Array Configuration with Options

Watcher Registration and Configuration Flow

Code References:

• Watcher registration: src/TelescopeServiceProvider.php
• Watcher base class: src/Watcher.php
• Individual watchers: src/Watchers/

Sources: config/telescope.php147-221 src/TelescopeServiceProvider.php src/Watcher.php

---

Complete Watcher Configuration Reference

The following table documents all available watchers and their configuration options:

Watcher Class	Environment Variable	Default	Configuration Options
Watchers\BatchWatcher	TELESCOPE_BATCH_WATCHER	true	Simple boolean
Watchers\CacheWatcher	TELESCOPE_CACHE_WATCHER	true	enabled, hidden array
Watchers\ClientRequestWatcher	TELESCOPE_GUZZLE_HTTP_CLIENT_ASPECT	true	Simple boolean
Watchers\CommandWatcher	TELESCOPE_COMMAND_WATCHER	true	enabled, ignore array
Watchers\DumpWatcher	TELESCOPE_DUMP_WATCHER	true	enabled, always boolean
Watchers\EventWatcher	TELESCOPE_EVENT_WATCHER	true	enabled, ignore array
Watchers\ExceptionWatcher	TELESCOPE_EXCEPTION_WATCHER	true	Simple boolean
Watchers\GateWatcher	TELESCOPE_GATE_WATCHER	true	enabled, ignore_abilities, ignore_packages, ignore_paths
Watchers\HttpClientWatcher	TELESCOPE_HTTP_CLIENT_WATCHER	true	enabled, request_size_limit, response_size_limit
Watchers\JobWatcher	TELESCOPE_JOB_WATCHER	true	Simple boolean
Watchers\LogWatcher	TELESCOPE_LOG_WATCHER	true	enabled, level string
Watchers\MailWatcher	TELESCOPE_MAIL_WATCHER	true	Simple boolean
Watchers\ModelWatcher	TELESCOPE_MODEL_WATCHER	true	enabled, hydrations boolean
Watchers\NotificationWatcher	TELESCOPE_NOTIFICATION_WATCHER	true	Simple boolean
Watchers\QueryWatcher	TELESCOPE_QUERY_WATCHER	true	enabled, ignore_packages, ignore_paths, slow integer
Watchers\RedisWatcher	TELESCOPE_REDIS_WATCHER	true	Simple boolean
Watchers\RequestWatcher	TELESCOPE_REQUEST_WATCHER	true	enabled, size_limit, ignore_http_methods, ignore_status_codes
Watchers\ScheduleWatcher	TELESCOPE_SCHEDULE_WATCHER	true	Simple boolean
Watchers\ViewWatcher	TELESCOPE_VIEW_WATCHER	true	Simple boolean

Sources: config/telescope.php148-221

---

Watcher-Specific Options

Cache Watcher Options

Option	Type	Purpose
hidden	array	List of cache keys to hide from recording (privacy control)

Sources: config/telescope.php150-153

---

Command Watcher Options

Option	Type	Purpose
ignore	array	Command names to exclude from recording

Sources: config/telescope.php157-160

---

Dump Watcher Options

Option	Type	Purpose
always	boolean	If true, always record dumps; if false, only record during Telescope sessions

Sources: config/telescope.php162-165

---

Event Watcher Options

Option	Type	Purpose
ignore	array	Event class names to exclude from recording

Sources: config/telescope.php167-170

---

Gate Watcher Options

Option	Type	Purpose
ignore_abilities	array	Ability names to exclude from recording
ignore_packages	boolean	Exclude authorization checks originating from vendor packages
ignore_paths	array	Request paths to exclude from gate recording

Sources: config/telescope.php174-179

---

HTTP Client Watcher Options

Option	Type	Purpose
request_size_limit	integer	Maximum kilobytes of request body to record
response_size_limit	integer	Maximum kilobytes of response body to record

Size limits prevent memory issues when recording large payloads. Bodies exceeding the limit are truncated with a note indicating the truncation.

Sources: config/telescope.php181-185

---

Log Watcher Options

Option	Type	Purpose
level	string	Minimum log level to record (debug, info, notice, warning, error, critical, alert, emergency)

Sources: config/telescope.php189-192

---

Model Watcher Options

Option	Type	Purpose
hydrations	boolean	Record Eloquent model hydration events (can be verbose for large result sets)

Sources: config/telescope.php196-199

---

Query Watcher Options

Option	Type	Purpose
ignore_packages	boolean	Exclude queries originating from vendor packages
ignore_paths	array	Request paths to exclude from query recording
slow	integer	Threshold in milliseconds to flag queries as slow (visual indicator in UI)

Sources: config/telescope.php203-208

---

Request Watcher Options

Option	Type	Purpose
size_limit	integer	Maximum kilobytes of response body to record
ignore_http_methods	array	HTTP methods to exclude (e.g., ['OPTIONS'])
ignore_status_codes	array	Status codes to exclude (e.g., [404, 500])

Sources: config/telescope.php212-217

---

Filtering and Privacy

Telescope provides multiple layers of filtering to control what data is recorded and what sensitive information is hidden from entries.

Path-Based Filtering

Path filtering allows you to include or exclude specific URI paths from Telescope monitoring. This is useful for focusing on specific areas of your application or excluding noisy endpoints.

Configuration Options

Configuration Key	Type	Purpose	Example
only_paths	array	Whitelist of URI patterns to monitor (if set, only these paths are recorded)	['api/*', 'admin/*']
ignore_paths	array	Blacklist of URI patterns to exclude from monitoring	['/health', '/metrics']
ignore_commands	array	Console command names to exclude from monitoring	['queue:work', 'schedule:run']

Path Matching Rules:

• Patterns support wildcards using * (e.g., api/* matches all paths starting with api/)
• Empty only_paths means all paths are allowed (subject to ignore_paths)
• Non-empty only_paths creates a whitelist, blocking all other paths
• ignore_paths always takes precedence over only_paths

Path Filtering Logic Flow

Code References:

• Filtering logic: src/Telescope.php
• String pattern matching: Uses Hyperf\Support\Str::is()

Sources: config/telescope.php126-134 src/Telescope.php

Implicit Filters: Some Laravel commands are always ignored by Telescope regardless of configuration, including migration commands, queue workers, and Telescope's own commands to prevent recursive recording.

Sources: config/telescope.php126-134

---

Privacy Controls and Hidden Data

Several watchers support hiding sensitive data from recorded entries to protect privacy and comply with security requirements.

Cache Watcher Hidden Keys

The hidden array allows you to specify cache keys that should not have their values recorded. The key name is still recorded, but the value is replaced with ********.

Example Configuration:

Cache Key Hiding Flow

Code References:

• Cache watcher implementation: src/Watchers/CacheWatcher.php
• Pattern matching: Uses Hyperf\Support\Str::is() with wildcard support

Sources: config/telescope.php150-153 src/Watchers/CacheWatcher.php

---

Watcher-Specific Filtering

Several watchers include built-in filtering options to reduce noise and focus on relevant data:

Query Watcher Filtering

• ignore_packages: When true, queries triggered by code in vendor/ directories are not recorded
• ignore_paths: Array of request paths where queries should not be recorded
• slow: Threshold in milliseconds; queries exceeding this duration are flagged as "slow" in the UI

Gate Watcher Filtering

• ignore_abilities: Array of authorization ability names to exclude
• ignore_packages: When true, gate checks from vendor packages are not recorded
• ignore_paths: Array of request paths where gate checks should not be recorded

Request Watcher Filtering

• ignore_http_methods: Array of HTTP methods to exclude (e.g., ['OPTIONS', 'HEAD'])
• ignore_status_codes: Array of HTTP status codes to exclude (e.g., [404, 401])

Sources: config/telescope.php174-179 config/telescope.php203-208 config/telescope.php212-217

---

Size Limits for Performance

To prevent memory issues when recording large payloads, several watchers implement configurable size limits:

HTTP Client Watcher

Request Watcher

All size limits are specified in kilobytes. When a payload exceeds the limit:

1. The content is truncated to the specified size
2. A truncation indicator is added to the recorded entry
3. The full size of the original payload is noted for reference

Recommended Size Limits:

• Development: 64-128 KB (default) - balance between detail and performance
• Production: 32-64 KB - minimize memory footprint
• Debug Sessions: Temporarily increase to 256-512 KB for detailed investigation

Sources: config/telescope.php181-185 config/telescope.php212-217

---

Configuration Environment Variables Summary

The following table provides a complete reference of all environment variables that can be used to override configuration defaults:

Environment Variable	Configuration Key	Default	Type	Purpose
TELESCOPE_ENABLED	enabled	true	boolean	Master switch
TELESCOPE_DOMAIN	domain	null	string	UI subdomain
TELESCOPE_PATH	path	'telescope'	string	UI path
TELESCOPE_DRIVER	driver	'database'	string	Storage driver
DB_CONNECTION	storage.database.connection	'mysql'	string	Database connection
TELESCOPE_STORE_DEFER	defer	true	boolean	Deferred storage
TELESCOPE_QUEUE_CONNECTION	queue.connection	null	string	Queue connection
TELESCOPE_QUEUE	queue.queue	null	string	Queue name
TELESCOPE_QUEUE_DELAY	queue.delay	10	integer	Queue delay (seconds)
TELESCOPE_BATCH_WATCHER	watchers.BatchWatcher	true	boolean	Batch watcher
TELESCOPE_CACHE_WATCHER	watchers.CacheWatcher.enabled	true	boolean	Cache watcher
TELESCOPE_GUZZLE_HTTP_CLIENT_ASPECT	watchers.ClientRequestWatcher	true	boolean	Client request watcher
TELESCOPE_COMMAND_WATCHER	watchers.CommandWatcher.enabled	true	boolean	Command watcher
TELESCOPE_DUMP_WATCHER	watchers.DumpWatcher.enabled	true	boolean	Dump watcher
TELESCOPE_DUMP_WATCHER_ALWAYS	watchers.DumpWatcher.always	false	boolean	Always record dumps
TELESCOPE_EVENT_WATCHER	watchers.EventWatcher.enabled	true	boolean	Event watcher
TELESCOPE_EXCEPTION_WATCHER	watchers.ExceptionWatcher	true	boolean	Exception watcher
TELESCOPE_GATE_WATCHER	watchers.GateWatcher.enabled	true	boolean	Gate watcher
TELESCOPE_HTTP_CLIENT_WATCHER	watchers.HttpClientWatcher.enabled	true	boolean	HTTP client watcher
TELESCOPE_HTTP_CLIENT_REQUEST_SIZE_LIMIT	watchers.HttpClientWatcher.request_size_limit	64	integer	Request size limit (KB)
TELESCOPE_HTTP_CLIENT_RESPONSE_SIZE_LIMIT	watchers.HttpClientWatcher.response_size_limit	64	integer	Response size limit (KB)
TELESCOPE_JOB_WATCHER	watchers.JobWatcher	true	boolean	Job watcher
TELESCOPE_LOG_WATCHER	watchers.LogWatcher.enabled	true	boolean	Log watcher
TELESCOPE_MAIL_WATCHER	watchers.MailWatcher	true	boolean	Mail watcher
TELESCOPE_MODEL_WATCHER	watchers.ModelWatcher.enabled	true	boolean	Model watcher
TELESCOPE_NOTIFICATION_WATCHER	watchers.NotificationWatcher	true	boolean	Notification watcher
TELESCOPE_QUERY_WATCHER	watchers.QueryWatcher.enabled	true	boolean	Query watcher
TELESCOPE_REDIS_WATCHER	watchers.RedisWatcher	true	boolean	Redis watcher
TELESCOPE_REQUEST_WATCHER	watchers.RequestWatcher.enabled	true	boolean	Request watcher
TELESCOPE_RESPONSE_SIZE_LIMIT	watchers.RequestWatcher.size_limit	64	integer	Response size limit (KB)
TELESCOPE_SCHEDULE_WATCHER	watchers.ScheduleWatcher	true	boolean	Schedule watcher
TELESCOPE_VIEW_WATCHER	watchers.ViewWatcher	true	boolean	View watcher

Sources: config/telescope.php1-222

---

Configuration Best Practices

Development Environment

Rationale:

• Immediate storage (defer=false) provides instant feedback during development
• Higher size limits allow inspection of full payloads
• All watchers enabled by default to capture complete application behavior

Staging Environment

Rationale:

• Deferred storage to simulate production performance characteristics
• Shorter queue delay for faster issue investigation
• Standard size limits to identify truncation issues before production

Production Environment

Rationale:

• Deferred storage is critical for production performance
• Longer queue delay reduces database write frequency
• Smaller size limits minimize memory usage
• Dedicated subdomain improves security (easier to restrict access)
• Selectively disable verbose watchers to reduce data volume

Temporarily Disabling Telescope

For emergency situations where Telescope needs to be disabled immediately:

Or use the pause command (see telescope:pause):

The pause command uses cache-based control and doesn't require application restart, making it ideal for runtime control.

Sources: config/telescope.php1-222