Spotlight Implementation Specification

Overview

This document specifies how SDKs should implement support for Sentry Spotlight, a local development tool that provides real-time observability for errors, traces, logs, and performance data during development.

File Location

Create the specification document at develop-docs/sdk/expected-features/spotlight.mdx following the format of other expected-features documents like rate-limiting.mdx.

Document Structure

The document should include:

1. Introduction - Brief overview of Spotlight and its purpose
2. Configuration Options - Detailed specification of the spotlight configuration attribute(s)
3. Environment Variable Handling - Specification for SENTRY_SPOTLIGHT environment variable
4. Precedence Rules - Clear rules for how config options and env vars interact
5. Data Collection Behavior - How Spotlight mode affects sampling, PII, and data collection
6. Default Values - Default Spotlight URL and behavior
7. Error Handling - How to handle unreachable Spotlight servers
8. Implementation Examples - Reference implementation patterns

Key Requirements to Document

Configuration Attribute

• Single attribute approach: spotlight: Optional[boolean|string]
• Alternative two-attribute approach: spotlight: Optional[boolean] and spotlightUrl: Optional[string]
• If using two attributes, setting any truthy spotlightUrl implies spotlight: true unless explicitly set to false

Environment Variable (SENTRY_SPOTLIGHT)

• Truthy values: "true", "t", "y", "yes", "on", "1" → treat as spotlight: true
• Falsy values: "false", "f", "n", "no", "off", "0" → treat as spotlight: false
• Any other string → use as Spotlight backend URL
• Reference Python implementation: sentry_sdk/utils.py lines 90-103

Precedence Rules

1. Config option takes precedence over env var, except:

• If spotlight: true (boolean, no URL) AND SENTRY_SPOTLIGHT is set to a URL string → use env var URL

2. If spotlight is set to a string URL → it overrides env var
3. If spotlightUrl config and env var are both set → prefer config value (spotlightUrl)
4. If spotlight: false explicitly set → ignore spotlightUrl value and the env var

Data Collection

• Send copy of every envelope to Spotlight server
• Enable 100% sample rate for Spotlight pipeline (without affecting upstream Sentry rates)
• Enable all PII data collection for Spotlight (without affecting upstream)
• Enable profiling data and logs for Spotlight
• Ideal: separate pipeline that ignores sampling settings
• Fallback: enable manually if no DSN in development mode

Default Values

• Default Spotlight URL: http://localhost:8969/stream

Error Handling

• If Spotlight server unreachable: log error with exponential backoff retry
• Output debug log statement ideally once
• Do not affect normal Sentry operation

Implementation Tasks

1. Create develop-docs/sdk/expected-features/spotlight.mdx with comprehensive specification
2. Include code examples showing configuration patterns
3. Document edge cases and precedence clearly
4. Reference the Python SDK implementation as an example
5. Add appropriate frontmatter (title, sidebar_order)
6. Link to Spotlight documentation and GitHub repository