Spotlight Sidecar

The Spotlight Sidecar is a small proxy server that allows (development) servers to send data to Spotlight.

Installation

``js
npm install @spotlightjs/sidecar
`

Usage

$3

`js
import { setupSidecar } from '@spotlightjs/sidecar';

// When you start your dev server
await setupSidecar();
`

$3

`bash


Start with default settings (port 8969)

spotlight-sidecar

Start on a custom port

spotlight-sidecar --port 3000

or

spotlight-sidecar -p 3000

Enable debug logging

spotlight-sidecar --debug

or

spotlight-sidecar -d

Combine options

spotlight-sidecar --port 3000 --debug

Show help

spotlight-sidecar --help
`

$3

- -p, --port - Port to listen on (default: 8969)
- -d, --debug - Enable debug logging
- -h, --help - Show help message

MCP (Model Context Protocol) Integration

Spotlight Sidecar includes MCP tools for accessing local debugging data through Claude Code and other MCP clients.

$3

#### Error Debugging
- search_errors - Retrieve recent application errors with stack traces
- search_logs - Access application logs for behavior analysis

#### Performance & Tracing
- search_traces - List recent traces with performance summaries
- get_traces - Get detailed span tree and timing for specific traces

$3

1. List Recent Traces
`
Use search_traces to see trace summaries:
- Trace IDs (first 8 characters shown)
- Root transaction names
- Duration and span counts
- Error counts per trace
- Timestamps for debugging specific periods
`

2. Examine Specific Trace
`
Use get_traces with a trace ID:
- Complete hierarchical span tree
- Individual span durations and operations
- Error context within trace timeline
- Chronological flow of operations
`

$3

To see trace data, ensure your application has:
- Sentry SDK with performance monitoring enabled
- Transaction instrumentation generating trace events
- Recent activity that creates spans (API calls, database queries, etc.)

$3

`bash


Start sidecar with debug logging to see trace data flow

spotlight-sidecar --debug

In Claude Code or MCP client:

1. List recent traces

search_traces({ filters: { timeWindow: 300 } })

2. Get details for a specific trace

get_traces({ traceId: "71a8c5e4" })
``