Spotlight Sidecar

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

Installation

npm install @spotlightjs/sidecar

Usage

As a Library

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

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

As a CLI

# 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

CLI Options

-p, --port <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.

Available Tools

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

Trace Viewing Workflow

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

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

Prerequisites

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.)

Example Usage

# 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" })

Détail du package

@spotlightjs/sidecar

readme