DOCSEARCHbyAlgolia
Submit Docs

Spotlight

repository·main·Indexed 20 days ago

https://github.com/getsentry/spotlight

Sentry for Development is a tool that brings real-time observability—including errors, traces, logs, and performance—into local development environments. It provides a local proxy server (Sidecar) to process telemetry from Sentry SDKs, which can be viewed via a web UI, a native Electron app for macOS, or a CLI. The CLI supports streaming events via the `tail` command, executing applications with `run`, and providing an MCP server for AI coding assistants.

Tokens
35.1K
Snippets
140
Records
177
Agent score
69%

What's inside Spotlight

  1. Overview of Spotlight MCP Tools

    main

    Spotlight provides four Model Context Protocol (MCP) tools that allow AI coding assistants to query application runtime data. These tools enable an AI to find errors, query logs, list performance traces, and inspect detailed trace hierarchies.

    ToolPurposeReturns
    search_errorsFind runtime errorsErrors with stack traces
    search_logsQuery application logsLog entries with context
    search_tracesList performance tracesTrace summaries
    get_tracesGet trace detailsFull span tree and timing

  2. Use @spotlightjs/spotlight for full Spotlight functionality

    main
    The @spotlightjs/spotlight package is the primary entry point for using Spotlight. It provides a complete implementation by combining the UI components from @spotlightjs/overlay and the sidecar functionality from @spotlightjs/sidecar into a single package.

  3. Three ways to use Spotlight

    main

    Spotlight can be integrated into your development workflow in three primary ways:

    1. Local Development Tool: A real-time debugging UI (via Desktop App or browser) for inspecting errors, traces, logs, and profiles as they happen.
    2. MCP Server: A Model Context Protocol integration that allows AI coding assistants (like Cursor or Claude) to access your application's runtime data for automated error investigation and context-aware debugging.
    3. CLI (Command Line Interface): A tool to run applications with automatic instrumentation or to tail events (logs, traces) directly in your terminal. Useful for backend services, CI/CD, and headless environments.

  4. What is the Spotlight Sidecar?

    main

    The Spotlight Sidecar is a lightweight local proxy server that acts as the backbone for Spotlight's real-time debugging. It sits between your application (via Sentry SDKs) and the Spotlight UI.

    Core Responsibilities:

    1. Receives telemetry data (errors, traces, logs) from Sentry SDKs.
    2. Stores events in memory for quick session-based access.
    3. Streams events to connected UIs (Browser, Desktop App, MCP clients) using Server-Sent Events (SSE).
    4. Provides APIs for querying historical data.

    Key Characteristics:

    • In-Memory Only: Events are buffered in memory for speed and automatic cleanup. They are lost when the sidecar stops. This is intended for active development, not long-term storage.
    • Real-Time: Uses SSE to push events instantly without polling.
    • Multi-Client Support: A single instance can simultaneously serve a browser UI, a desktop application, and MCP clients (like Cursor or Claude).

  7. Understand the Spotlight repository structure

    main

    The Spotlight repository is organized as a monorepo under the packages/ directory:

    • packages/spotlight (@spotlightjs/spotlight): The main package containing the UI, sidecar, CLI, and Electron app.
    • packages/website (@spotlightjs/website): The documentation website.
    spotlight
└── packages
    ├── spotlight    // @spotlightjs/spotlight - main package (UI, sidecar, CLI, Electron app)
    └── website      // @spotlightjs/website   - documentation website

  8. Supported Spotlight clients

    main

    A single running Sidecar can serve multiple types of clients at once. Depending on your workflow, you can consume telemetry via:

    • Browser: Access the web UI at http://localhost:8969.
    • Desktop App: A dedicated application with a built-in UI.
    • CLI: Use the spotlight tail command to stream events directly to your terminal.
    • MCP (Model Context Protocol): Allows AI assistants to query and interact with your telemetry events.

  9. How Spotlight works under the hood

    main

    Spotlight is composed of two primary components bundled within the @spotlightjs/spotlight package:

    1. Sidecar Server: A local HTTP server that acts as the central hub. It receives telemetry from your application via the Sentry SDK and streams that data to connected clients using Server-Sent Events (SSE).
    2. UI: A React-based application used to visualize telemetry data in real-time. You can access the UI via a dedicated Desktop App or through a web browser at http://localhost:8969.

    All incoming events are stored in an in-memory store within the Sidecar, allowing multiple clients to consume the same data stream simultaneously.

    Your App → Sentry SDK → Sidecar (port 8969) → UI
                              ↓
                        [In-memory store]
                              ↓
                    Desktop App / Browser / MCP

  10. Auto-detection of scripts and Docker Compose

    main

    When running spotlight run without an explicit command, Spotlight uses the following logic:

    1. package.json Detection

    It searches for the first available script in your package.json in this order:

    1. dev
    2. develop
    3. serve
    4. start

    2. Docker Compose Detection

    It looks for Docker Compose files in the current directory or via the COMPOSE_FILE environment variable. Supported filenames include:

    • docker-compose.yml / docker-compose.yaml
    • compose.yml / compose.yaml

    When Docker Compose is detected, Spotlight:

    • Uses host.docker.internal instead of localhost so containers can reach the host.
    • Injects SENTRY_SPOTLIGHT, NEXT_PUBLIC_SENTRY_SPOTLIGHT, and SENTRY_TRACES_SAMPLE_RATE into all services.
    • Adds extra_hosts mapping (host.docker.internal:host-gateway) for Linux compatibility.

    Note: Docker Compose auto-detection requires Docker version 20.10.0 or higher.

    Conflict Resolution

    If both a package.json and a Docker Compose project are detected, Spotlight will prompt you to choose which one to use. To avoid this in non-interactive environments (like CI), specify the command explicitly:

    spotlight run docker compose up
# or
spotlight run npm run dev

  11. Understand the Starlight project structure

    main

    A Starlight project is built on Astro and follows a specific directory structure for content and assets:

    • src/content/docs/: The primary directory for documentation. Starlight automatically exposes .md or .mdx files in this folder as routes based on their filenames.
    • src/content/config.ts: Configuration for content collections.
    • src/assets/: Place images here to embed them in Markdown using relative links.
    • public/: Place static assets that do not need processing (like favicons) here.
    • astro.config.mjs: The main configuration file for the Astro project.
    • package.json: Defines project dependencies and scripts.
    .
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   ├── docs/
│   │   └── config.ts
│   └── env.d.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json