Configuration

All configuration lives in config/spectra.php, published during installation. Every option can be controlled via environment variables. This page provides a complete reference for all available settings.

Master Switch

'enabled' => env('SPECTRA_ENABLED', true),

When set to false, Spectra does nothing — no request interception, no tracking, no database writes, and no dashboard routes. This allows you to disable observability entirely in specific environments without removing the package from your application.

Storage

Controls how and what Spectra persists to the database. These settings let you balance storage consumption, privacy requirements, and debugging needs.

'storage' => [
    'connection'           => env('SPECTRA_DB_CONNECTION'),
    'chunk'                => 1000,
    'store_requests'       => env('SPECTRA_STORE_REQUESTS', true),
    'store_responses'      => env('SPECTRA_STORE_RESPONSES', true),
    'store_prompts'        => env('SPECTRA_STORE_PROMPTS', true),
    'store_system_prompts' => env('SPECTRA_STORE_SYSTEM_PROMPTS', true),
    'store_frames'         => env('SPECTRA_STORE_FRAMES', true),
    'store_tools'          => env('SPECTRA_STORE_TOOLS', true),
    'max_prompt_length'    => env('SPECTRA_MAX_PROMPT_LENGTH', 10000),
    'max_response_length'  => env('SPECTRA_MAX_RESPONSE_LENGTH', 10000),
],

Key	Type	Default	Description
connection	string|null	null	Database connection name. null uses the application default. Set to a separate connection for high-volume applications to isolate observability writes.
chunk	int	1000	Batch size for bulk operations such as exports and cleanup.
store_requests	bool	true	Persist request payloads (the JSON body sent to the provider). Disable to reduce storage for high-volume applications.
store_responses	bool	true	Persist response payloads (the JSON returned by the provider).
store_prompts	bool	true	Store user prompt text and chat messages. Disable for privacy compliance (GDPR, CCPA).
store_system_prompts	bool	true	Store system prompts separately. These often contain proprietary business logic.
store_frames	bool	true	Capture the code location (file, line number, call chain) where each request originated. Useful for debugging but adds storage overhead.
store_tools	bool	true	Store function and tool definitions sent to the AI provider. These can be large for complex tool schemas.
max_prompt_length	int	10000	Maximum characters for stored prompts. Content beyond this limit is truncated. Set to 0 to disable truncation.
max_response_length	int	10000	Maximum characters for stored responses. Set to 0 to disable truncation.

Media Persistence

Some AI endpoints return media with expiring URLs — for example, DALL-E images expire after approximately one hour, and Sora videos include an expires_at timestamp. When media persistence is enabled, Spectra downloads and stores generated media to a Laravel filesystem disk before the URLs expire.

'storage' => [
    'media' => [
        'enabled' => env('SPECTRA_MEDIA_ENABLED', false),
        'disk'    => env('SPECTRA_MEDIA_DISK', 'local'),
        'path'    => env('SPECTRA_MEDIA_PATH', 'spectra-media'),
    ],
],

Key	Type	Default	Description
media.enabled	bool	false	Enable automatic media download and persistence.
media.disk	string	local	Laravel filesystem disk to store media on. Use s3 or another cloud disk in production for accessibility across servers.
media.path	string	spectra-media	Directory path within the disk.

API Keys

Optional explicit API keys per provider. These take highest priority in the resolution chain and are used by both the HTTP macros (Http::openai(), etc.) and internal operations such as media downloads.

'api_keys' => [
    'openai'    => env('SPECTRA_OPENAI_API_KEY'),
    'anthropic' => env('SPECTRA_ANTHROPIC_API_KEY'),
    // ...
],

For the full resolution chain showing how API keys are discovered from multiple configuration sources, see API Key Auto-Discovery.

Queue

Controls whether request persistence happens synchronously, after the HTTP response, or via a background queue job.

'queue' => [
    'enabled'        => env('SPECTRA_QUEUE_ENABLED', false),
    'connection'     => env('SPECTRA_QUEUE_CONNECTION'),
    'queue'          => env('SPECTRA_QUEUE_NAME'),
    'delay'          => env('SPECTRA_QUEUE_DELAY'),
    'after_response' => env('SPECTRA_AFTER_RESPONSE', false),
],

Key	Type	Default	Description
enabled	bool	false	Dispatch a PersistSpectraRequestJob instead of writing synchronously.
connection	string|null	null	Queue connection name. null uses the application default.
queue	string|null	null	Queue name to dispatch to.
delay	int|null	null	Seconds to delay before processing the job.
after_response	bool	false	When queue is disabled, persist after the HTTP response is sent to the client. Has no effect when queue is enabled or in non-HTTP contexts.

Persistence Modes

Mode	Config	Behavior	Best For
Sync (default)	Both false	Write to database immediately	Development, low-volume applications
After Response	after_response: true	Write after HTTP response is sent	Production web applications without queues
Queue	enabled: true	Dispatch PersistSpectraRequestJob	High-volume production applications

WARNING

After-response mode only works during web requests. Console commands, queue workers, and scheduled tasks always persist synchronously unless queue mode is enabled.

Tracking Context

Configure what contextual information Spectra captures automatically with each tracked request.

'tracking' => [
    'auto_track_user'    => true,
    'capture_ip'         => true,
    'capture_user_agent' => true,
    'capture_request_id' => true,
],

Key	Type	Default	Description
auto_track_user	bool	true	Automatically associate requests with the authenticated user via the polymorphic trackable relationship.
capture_ip	bool	true	Store the client's IP address. Disable for GDPR or CCPA compliance.
capture_user_agent	bool	true	Store the client's user agent string.
capture_request_id	bool	true	Capture or generate a request ID for correlation. Uses the X-Request-ID header if present.

Dashboard

Configure the built-in SPA dashboard.

'dashboard' => [
    'domain'      => env('SPECTRA_DOMAIN'),
    'enabled'     => env('SPECTRA_DASHBOARD_ENABLED', true),
    'path'        => env('SPECTRA_PATH', 'spectra'),
    'middleware'   => ['web'],
    'layout'      => env('SPECTRA_DASHBOARD_LAYOUT', 'full'),
    'date_format' => env('SPECTRA_DATE_FORMAT', 'M j, Y g:i:s A'),
],

Key	Type	Default	Description
domain	string|null	null	Optional subdomain for the dashboard (e.g., spectra serves it at spectra.yourdomain.com).
enabled	bool	true	Enable or disable the web dashboard. Set to false for headless (API tracking only) mode.
path	string	spectra	URI path where the dashboard is served.
middleware	array	['web']	Middleware applied to dashboard routes. Add 'auth' to require authentication.
layout	string	full	Which model types the dashboard displays. Options: full, text, embedding, image, video, audio.
date_format	string	M j, Y g:i:s A	PHP date format string for timestamps in the dashboard.

Costs

Configure cost calculation, pricing tiers, and the pricing lookup cache.

'costs' => [
    'enabled'         => true,
    'currency'        => 'USD',
    'currency_symbol' => '$',

    'provider_settings' => [
        'openai' => [
            'default_tier' => env('SPECTRA_OPENAI_PRICING_TIER', 'standard'),
        ],
        'anthropic' => [
            'default_tier' => env('SPECTRA_ANTHROPIC_PRICING_TIER', 'standard'),
        ],
    ],

    'cache' => [
        'enabled' => env('SPECTRA_PRICING_CACHE_ENABLED', true),
        'store'   => env('SPECTRA_PRICING_CACHE_STORE'),
        'ttl'     => env('SPECTRA_PRICING_CACHE_TTL', 3600),
    ],
],

Key	Type	Default	Description
enabled	bool	true	Calculate and store costs for each tracked request.
currency	string	USD	Currency code for display purposes. Does not perform any conversion.
currency_symbol	string	$	Symbol shown before cost values in the dashboard.
provider_settings.*.default_tier	string	standard	Default pricing tier for each provider. Used when no explicit tier is specified.
cache.enabled	bool	true	Cache pricing lookups to avoid repeated database queries. Recommended for production.
cache.store	string|null	null	Cache store name. null uses the default cache driver.
cache.ttl	int	3600	Cache duration in seconds (1 hour default).

Budget

Configure budget enforcement defaults. These values apply when individual budgets do not specify their own thresholds.

'budget' => [
    'enabled'            => env('SPECTRA_BUDGET_ENABLED', true),
    'default_provider'   => 'openai',
    'default_model'      => 'gpt-4',
    'warning_threshold'  => 80,
    'critical_threshold' => 95,
    'hard_limit'         => true,
    'notification_queue' => 'default',
],

Key	Type	Default	Description
enabled	bool	true	Enable budget checking and enforcement.
default_provider	string	openai	Fallback provider when the budget middleware cannot determine the provider from route parameters.
default_model	string	gpt-4	Fallback model for cost estimation in budget checks.
warning_threshold	int	80	Usage percentage at which a BudgetThresholdReached event fires. Set to 0 to disable.
critical_threshold	int	95	Usage percentage for the critical threshold event. Set to 0 to disable.
hard_limit	bool	true	Block requests when budget is exceeded. Set to false for soft limits that only fire events.
notification_queue	string	default	Queue name for dispatching budget notification jobs.

Watcher

Configure automatic HTTP request interception.

'watcher' => [
    'enabled'  => env('SPECTRA_WATCHER_ENABLED', true),
    'watchers' => [
        Spectra\Watchers\HttpWatcher::class,
        Spectra\Watchers\OpenAiWatcher::class,
        Spectra\Watchers\GuzzleWatcher::class,
    ],
],

Key	Type	Default	Description
enabled	bool	true	Enable automatic request interception by watchers.
watchers	array	See above	List of watcher classes to register. Remove a class to disable that specific watcher.

Watcher	Intercepts	Mechanism
HttpWatcher	Laravel Http facade requests	Global event listener on ResponseReceived
OpenAiWatcher	openai-php/laravel SDK calls	Decorates the OpenAI client with a tracking handler stack
GuzzleWatcher	Direct Guzzle HTTP client usage	Provides a Guzzle middleware for tracked handler stacks

Providers

Map provider names to their provider classes. Each provider defines hosts, endpoints, and handlers for detecting and extracting data from AI API responses.

'providers' => [
    'openai'     => Spectra\Providers\OpenAI\OpenAI::class,
    'anthropic'  => Spectra\Providers\Anthropic\Anthropic::class,
    'google'     => Spectra\Providers\Google\Google::class,
    'ollama'     => Spectra\Providers\Ollama\Ollama::class,
    'openrouter' => Spectra\Providers\OpenRouter\OpenRouter::class,
    'cohere'     => Spectra\Providers\Cohere\Cohere::class,
    'groq'       => Spectra\Providers\Groq\Groq::class,
    'xai'        => Spectra\Providers\XAi\XAi::class,
    'elevenlabs' => Spectra\Providers\ElevenLabs\ElevenLabs::class,
    'replicate'  => Spectra\Providers\Replicate\Replicate::class,
],

Add custom providers by extending AbstractProvider and adding an entry here. See Custom Providers for a complete guide.

Integrations

Configure external integrations. Currently supports OpenTelemetry trace export. See OpenTelemetry for a detailed setup guide.

'integrations' => [
    'opentelemetry' => [
        'enabled'             => env('SPECTRA_OTEL_ENABLED', false),
        'endpoint'            => env('SPECTRA_OTEL_ENDPOINT', 'http://localhost:4318/v1/traces'),
        'headers'             => [],
        'service_version'     => env('SPECTRA_OTEL_SERVICE_VERSION', '1.0.0'),
        'resource_attributes' => [],
        'timeout'             => env('SPECTRA_OTEL_TIMEOUT', 10),
    ],
],

Environment Variables

A quick reference of all environment variables supported by Spectra:

# Master switch
SPECTRA_ENABLED=true

# Storage
SPECTRA_DB_CONNECTION=
SPECTRA_STORE_REQUESTS=true
SPECTRA_STORE_RESPONSES=true
SPECTRA_STORE_PROMPTS=true
SPECTRA_STORE_SYSTEM_PROMPTS=true
SPECTRA_STORE_FRAMES=true
SPECTRA_STORE_TOOLS=true
SPECTRA_MAX_PROMPT_LENGTH=10000
SPECTRA_MAX_RESPONSE_LENGTH=10000

# Media
SPECTRA_MEDIA_ENABLED=false
SPECTRA_MEDIA_DISK=local
SPECTRA_MEDIA_PATH=spectra-media

# Queue / persistence mode
SPECTRA_QUEUE_ENABLED=false
SPECTRA_QUEUE_CONNECTION=
SPECTRA_QUEUE_NAME=
SPECTRA_QUEUE_DELAY=
SPECTRA_AFTER_RESPONSE=false

# Dashboard
SPECTRA_DOMAIN=
SPECTRA_DASHBOARD_ENABLED=true
SPECTRA_PATH=spectra
SPECTRA_DASHBOARD_LAYOUT=full
SPECTRA_DATE_FORMAT="M j, Y g:i:s A"

# Watcher
SPECTRA_WATCHER_ENABLED=true

# Costs
SPECTRA_OPENAI_PRICING_TIER=standard
SPECTRA_ANTHROPIC_PRICING_TIER=standard
SPECTRA_PRICING_CACHE_ENABLED=true
SPECTRA_PRICING_CACHE_STORE=
SPECTRA_PRICING_CACHE_TTL=3600

# Budget
SPECTRA_BUDGET_ENABLED=true

# Integrations
SPECTRA_OTEL_ENABLED=false
SPECTRA_OTEL_ENDPOINT=http://localhost:4318/v1/traces
SPECTRA_OTEL_SERVICE_VERSION=1.0.0
SPECTRA_OTEL_TIMEOUT=10