diff --git a/packages/website/astro.config.mjs b/packages/website/astro.config.mjs index 4d8992e47..0a398e6ce 100644 --- a/packages/website/astro.config.mjs +++ b/packages/website/astro.config.mjs @@ -88,9 +88,21 @@ export default defineConfig({ ], }, { - label: "Setup", + label: "CLI", autogenerate: { - directory: "docs/setup", + directory: "docs/cli", + }, + }, + { + label: "MCP Server", + autogenerate: { + directory: "docs/mcp", + }, + }, + { + label: "Desktop App", + autogenerate: { + directory: "docs/desktop-app", }, }, { diff --git a/packages/website/src/content/docs/docs/about.mdx b/packages/website/src/content/docs/docs/about.mdx index 304b9603e..694ce0a87 100644 --- a/packages/website/src/content/docs/docs/about.mdx +++ b/packages/website/src/content/docs/docs/about.mdx @@ -1,12 +1,12 @@ --- title: About Spotlight -description: "Spotlight is Sentry for Development. Inspired by an old project, Django Debug Toolbar, Spotlight brings a rich debug -overlay into development environments, and it does it by leveraging the existing power of Sentry's SDKs." +description: "Spotlight is Sentry for Development. A powerful local debugging companion that brings real-time error tracking, traces, and logs to your development environment." sidebar: label: What is Spotlight? order: 0 --- import DownloadButton from '../../../components/DownloadButton.astro'; +import { LinkCard, CardGrid } from '@astrojs/starlight/components'; Spotlight started out as a [Hackweek project](https://syntax.fm/show/666/hackweek-projects-realtime-markdown-editor-and-a-hardware-recording-button) at Sentry: @@ -15,12 +15,70 @@ overlay into development environments, and it does it by leveraging the existing You get the power of Sentry's telemetry (through its SDKs) without needing Sentry's production monitoring. If you already use Sentry, that's great. All you need is enabling Spotlight in your SDK and run Spotlight locally. If you are not using Sentry, you need to install the free and open source Sentry SDKs to get started. If you want to use Sentry later on, this saves you the initial setup. Just add your Sentry DSNs into your projects and off you go! -Spotlight can show you errors, traces (including distributed traces), profiling data, configurations settings, installed dependencies, you name it. Spotlight is developed with customizablity in mind, so you can add your own integrations to it. -The main differences between Spotlight and Sentry are: +## Three Ways to Use Spotlight -1. Spotlight runs locally on your system (including the sidecar) -2. Spotlight shows you everything and in realtime whereas Sentry is all about aggregation -3. Spotlight is completely free and open source, whereas Sentry is a commercial product (with a free tier and self-hosting options) +Spotlight provides three powerful tools for debugging and development: + +### 1. Local Development Tool + +A real-time debugging overlay that displays errors, traces, logs, and profiles directly in your browser or dedicated desktop app. See everything happening in your application as it happens. + +**Perfect for:** +- Visual debugging during development +- Inspecting distributed traces +- Monitoring application performance +- Viewing real-time logs and errors + +### 2. MCP Server + +Model Context Protocol integration that connects Spotlight to AI coding assistants like Cursor, Claude, and other MCP clients. Your AI assistant can access your application's runtime data to help debug issues. + +**Perfect for:** +- AI-assisted debugging +- Letting your coding assistant analyze errors +- Getting context-aware code suggestions based on runtime data +- Automated error investigation + +### 3. CLI (Command Line Interface) + +Run your applications with Spotlight's CLI to automatically capture telemetry data, or tail events in real-time from your terminal. + +**Perfect for:** +- Running backend services with automatic instrumentation +- Streaming logs and traces to your terminal +- CI/CD integration +- Headless environments + +## Why Spotlight? + +Spotlight provides comprehensive debugging visibility: + +- **Errors** with full stack traces +- **Traces** including distributed transactions +- **Logs** with structured data +- **Profiling data** for performance analysis +- **Configuration** and dependency information +- **Customizable** with your own integrations + +### Spotlight vs Sentry + +| | Spotlight | Sentry | +|---|---|---| +| **Where it runs** | Local on your machine | Cloud or self-hosted | +| **Data display** | Real-time, shows everything | Aggregated, sampled | +| **Cost** | Free and open source | Commercial (with free tier) | +| **Use case** | Active development | Production monitoring | + +## Get Started + +Choose the approach that fits your workflow: + + + + + + + ## Quick Start diff --git a/packages/website/src/content/docs/docs/cli/index.mdx b/packages/website/src/content/docs/docs/cli/index.mdx new file mode 100644 index 000000000..54200b75d --- /dev/null +++ b/packages/website/src/content/docs/docs/cli/index.mdx @@ -0,0 +1,31 @@ +--- +title: Spotlight CLI +description: Command-line interface for running applications with Spotlight or streaming events in real-time +sidebar: + order: 0 +--- + +import { LinkCard, CardGrid } from '@astrojs/starlight/components'; + +The Spotlight CLI (`spotlight`) provides two modes for working with Spotlight in your terminal: + +## Two Modes of Operation + + + + + + + +## Quick Reference + +- [Complete CLI Reference](/docs/cli/reference/) - All commands and options + diff --git a/packages/website/src/content/docs/docs/cli/reference.mdx b/packages/website/src/content/docs/docs/cli/reference.mdx new file mode 100644 index 000000000..5de4ce00e --- /dev/null +++ b/packages/website/src/content/docs/docs/cli/reference.mdx @@ -0,0 +1,371 @@ +--- +title: CLI Reference +description: Complete reference for all Spotlight CLI commands and options +sidebar: + order: 3 +--- + +Complete reference for the Spotlight CLI (`spotlight`). + +## Global Syntax + +```bash +spotlight [command] [options] [arguments] +``` + +## Commands + +### `run` - Run Application with Spotlight + +Wraps your application and automatically configures Spotlight. + +```bash +spotlight run [options] [command...] +``` + +**Examples:** + +```bash +# Auto-detect from package.json +spotlight run + +# Run specific command +spotlight run node server.js +spotlight run python manage.py runserver +spotlight run go run main.go + +# With custom port +spotlight run -p 3000 npm start + +# With debug logging +spotlight run -d node server.js +``` + +**Behavior:** +- Starts Spotlight sidecar server +- Sets `SENTRY_SPOTLIGHT` environment variable +- Sets `SENTRY_TRACES_SAMPLE_RATE=1` +- Captures stdout/stderr as logs +- Runs the specified command + +**Auto-detection:** +If no command is provided, looks for these scripts in `package.json`: +1. `dev` +2. `develop` +3. `serve` +4. `start` + +[Learn more about run →](/docs/cli/run/) + +--- + +### `tail` - Stream Events + +Streams events from Spotlight to your terminal in real-time. + +```bash +spotlight tail [event-types...] [options] +``` + +**Event Types:** +- `errors` - Errors and exceptions +- `logs` - Application logs +- `traces` - Performance traces +- `all`, `everything`, `*` - All event types + +**Examples:** + +```bash +# Stream all events +spotlight tail + +# Stream only errors +spotlight tail errors + +# Stream errors and logs +spotlight tail errors logs + +# Stream with JSON format +spotlight tail -f json + +# Stream traces with logfmt format +spotlight tail traces -f logfmt + +# Stream on custom port +spotlight tail -p 3000 +``` + +**Behavior:** +- Connects to existing sidecar or starts new one +- Streams filtered events to stdout +- Formats output based on `-f` option + +[Learn more about tail →](/docs/cli/tail/) + +--- + +### `mcp` - Start MCP Server + +Starts Spotlight in MCP (Model Context Protocol) stdio server mode for integration with AI coding assistants. + +```bash +spotlight mcp [options] +``` + +**Examples:** + +```bash +# Start MCP server on default port +spotlight mcp + +# Start on custom port +spotlight mcp -p 3000 + +# Start with debug logging +spotlight mcp -d +``` + +**Behavior:** +- Starts Spotlight sidecar server +- Enables MCP protocol over stdio +- Provides tools for AI assistants to query errors, logs, and traces + +**Available MCP Tools:** +- `spotlight.errors.search` - Search for errors +- `spotlight.logs.search` - Search for logs +- `spotlight.traces.search` - List traces +- `spotlight.traces.get` - Get trace details + +[Learn more about MCP →](/docs/mcp/) + +--- + +### `server` - Start Standalone Server + +Starts the Spotlight sidecar server without any additional modes. + +```bash +spotlight server [options] +spotlight [options] # server is the default command +``` + +**Examples:** + +```bash +# Start on default port (8969) +spotlight server + +# Start on custom port +spotlight server -p 3000 + +# Start with debug logging +spotlight server -d + +# Shorthand (server is default) +spotlight +spotlight -p 3000 +``` + +**Behavior:** +- Starts the sidecar HTTP server +- Listens for events from Sentry SDKs +- Serves the Spotlight UI at `http://localhost:PORT` +- Streams events via Server-Sent Events (SSE) + +--- + +### `help` - Show Help + +Displays help information. + +```bash +spotlight help +spotlight --help +spotlight -h +``` + +## Global Options + +These options work with all commands: + +### `-p, --port ` + +Specify the port for the sidecar server. + +- **Type:** Number (1-65535 or 0) +- **Default:** `8969` (for most commands), `0` (for `run` command) +- **Special:** `0` = auto-assign random available port + +**Examples:** + +```bash +spotlight -p 3000 +spotlight --port 9000 tail errors +spotlight run -p 0 npm start # Random port +``` + +### `-d, --debug` + +Enable debug logging for troubleshooting. + +- **Type:** Boolean +- **Default:** `false` + +**Examples:** + +```bash +spotlight -d +spotlight --debug tail logs +spotlight run -d node server.js +``` + +**Output includes:** +- Detailed server startup information +- Connection status +- Event processing details +- SDK communication logs + +### `-h, --help` + +Show help message and exit. + +**Examples:** + +```bash +spotlight -h +spotlight --help +``` + +#### `-f, --format ` + +Specify output format for events. + +- **Type:** String +- **Options:** `human`, `logfmt`, `json`, `md` +- **Default:** `human` + +**Examples:** + +```bash +spotlight tail -f json +spotlight tail --format logfmt errors +spotlight tail errors logs -f md +``` + +**Formats:** +- `human` - Colored, human-readable (default). Based on the [hl](https://github.com/pamburus/hl) library. +- `logfmt` - Machine-readable key-value pairs following the [logfmt](https://brandur.org/logfmt) format. +- `json` - Structured JSON (one per line) +- `md` - Markdown format + +## Environment Variables + +### `SPOTLIGHT_DEBUG` + +Enable debug logging (alternative to `-d` flag). + +```bash +export SPOTLIGHT_DEBUG=1 +spotlight tail +``` + +### `SENTRY_SPOTLIGHT` + +Set by `run` command to tell SDKs where to send events. + +```bash +# Automatically set by spotlight run +SENTRY_SPOTLIGHT=http://localhost:8969/stream +``` + +### `SENTRY_TRACES_SAMPLE_RATE` + +Set by `run` command to enable 100% trace sampling. + +```bash +# Automatically set by spotlight run +SENTRY_TRACES_SAMPLE_RATE=1 +``` + +## Exit Codes + +- `0` - Success +- `1` - General error (invalid arguments, connection failed, etc.) +- `130` - Interrupted by user (SIGINT/Ctrl+C) + +## Configuration Files + +Spotlight CLI does not use configuration files. All configuration is done via command-line arguments and environment variables. + +## Common Patterns + +### Development Workflow + +```bash +# Terminal 1: Run your app with Spotlight +spotlight run + +# Terminal 2: Monitor specific events +spotlight tail errors logs + +# Browser: View in UI +open http://localhost:8969 +``` + +### CI/CD Integration + +```bash +# Capture events during tests as newline-delimited JSON (NDJSON) +spotlight tail -f json > events.ndjson & +SPOTLIGHT_PID=$! + +# Run tests +spotlight run npm test + +# Cleanup +kill $SPOTLIGHT_PID +``` + +### Multi-Service Setup + +```bash +# Service 1 (backend) +spotlight run -p 8969 npm run dev:backend + +# Service 2 (frontend - connects to same sidecar) +spotlight run -p 8969 npm run dev:frontend +``` + +### Log Aggregation + +```bash +# Stream to file with logfmt +spotlight tail -f logfmt >> spotlight.log + +# Stream to file with JSON +spotlight tail -f json | jq . >> spotlight.json +``` + +## Version + +To check the installed version: + +```bash +spotlight --version +# or check package version +npm list -g @spotlightjs/spotlight +``` + +## Package Information + +- **Package:** `@spotlightjs/sidecar` +- **Binary:** `spotlight` +- **Minimum Node Version:** 20.0.0 + +## Related Documentation + +- [Run Command Guide](/docs/cli/run/) - Detailed guide for running applications +- [Tail Command Guide](/docs/cli/tail/) - Detailed guide for streaming events +- [MCP Integration](/docs/mcp/) - Using Spotlight with AI coding assistants +- [Sidecar Documentation](/docs/sidecar/) - Understanding the sidecar server + diff --git a/packages/website/src/content/docs/docs/cli/run.mdx b/packages/website/src/content/docs/docs/cli/run.mdx new file mode 100644 index 000000000..4e7ddf644 --- /dev/null +++ b/packages/website/src/content/docs/docs/cli/run.mdx @@ -0,0 +1,277 @@ +--- +title: Spotlight Run +description: Run your applications with automatic Spotlight instrumentation +sidebar: + order: 1 +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +The `run` command wraps your application with Spotlight, automatically setting up the necessary environment variables and capturing telemetry data. + +## Basic Usage + +```bash +spotlight run [options] [command] +``` + +**Key points:** +- If you don't provide a command, Spotlight automatically detects and runs your development script from `package.json` +- Works with any language or framework +- Automatically configures environment variables for Spotlight integration + +## Auto-Detection from package.json + +When you run `spotlight run` without a command, it looks for these scripts in your `package.json` (in order): + +1. `dev` +2. `develop` +3. `serve` +4. `start` + +```bash +# In a directory with package.json +spotlight run +# ✓ Automatically runs: npm run dev (or first available script) +``` + +This makes it incredibly easy to get started - just add Spotlight to your existing workflow: + +```json +{ + "scripts": { + "dev": "node server.js", + "dev:spotlight": "spotlight run" + } +} +``` + +## Running Specific Commands + +You can run any command with Spotlight: + +```bash +spotlight run [your-command] +``` + +**Examples:** + +```bash +# Node.js +spotlight run node server.js + +# Python +spotlight run python manage.py runserver + +# Go +spotlight run go run main.go + +# Any other command +spotlight run npm start +spotlight run flask run +spotlight run rails server +``` + +## What Happens Under the Hood + +When you run `spotlight run`, it: + +1. **Starts the Spotlight Sidecar** on the specified port (default: dynamically assigned) +2. **Sets Environment Variables**: + - `SENTRY_SPOTLIGHT=http://localhost:/stream` + - `SENTRY_TRACES_SAMPLE_RATE=1` (enables 100% trace sampling) +3. **Runs Your Command** with these environment variables +4. **Captures stdout/stderr** as log events automatically +5. **Streams Everything** to Spotlight in real-time + +### Automatic Log Capture + +Your application's console output is automatically captured and sent to Spotlight as log events: + +- **stdout** → Info-level logs +- **stderr** → Error-level logs + +This means you don't need to add any special logging configuration - your existing `console.log()`, `print()`, or standard output statements will appear in Spotlight! + +:::note[Smart Detection] +Spotlight automatically detects if your app is already using Sentry's logging and disables automatic stdout/stderr capture to avoid duplicates. +::: + +## Options + +### Port Configuration + +**Default port:** `0` - automatically assigns a random available port. +```bash +# Use default port (0) +spotlight run node server.js + +# Use custom port +spotlight run -p 3000 node server.js + +# Use random available port +spotlight run -p 0 node server.js +``` + +### Debug Mode + +Enable debug logging to see what Spotlight is doing: + +```bash +spotlight run -d node server.js +# or +spotlight run --debug python app.py +``` + +## Complete Examples + +### Full Development Workflow + +```bash +# Terminal 1: Run your app with Spotlight +spotlight run npm run dev + +# Terminal 2: Open the Spotlight UI +open http://localhost:8969 + +# Now interact with your app and see errors, traces, and logs in real-time! +``` + +### With Custom Port + +```bash +# If port 8969 is already in use +spotlight run -p 9000 node server.js + +# Update your Sentry SDK configuration if needed: +# spotlight: "http://localhost:9000/stream" +``` + +### CI/CD Integration + +```bash +# Run tests with Spotlight for debugging failures +spotlight run npm test + +# Capture traces during integration tests +spotlight run -p 0 pytest tests/ +``` + +## SDK Configuration + +For the `run` command to work, your application needs: + +- Sentry SDK installed and initialized +- SDK configured to respect the `SENTRY_SPOTLIGHT` environment variable (most modern SDKs do this automatically) + +### Automatic Configuration (Recommended) + +Most modern Sentry SDKs automatically detect the `SENTRY_SPOTLIGHT` environment variable: + + + + ```javascript + // Sentry will automatically use the SENTRY_SPOTLIGHT env var + Sentry.init({ + dsn: "your-dsn", // Optional - can be omitted for local dev + // spotlight: true, // Not needed - handled by env var + }); + ``` + + + ```python + import sentry_sdk + + # Sentry will automatically use the SENTRY_SPOTLIGHT env var + sentry_sdk.init( + dsn="your-dsn", # Optional - can be omitted for local dev + # spotlight="...", # Not needed - handled by env var + ) + ``` + + + ```go + // Sentry will automatically use the SENTRY_SPOTLIGHT env var + sentry.Init(sentry.ClientOptions{ + Dsn: "your-dsn", // Optional + }) + ``` + + + +### Manual Configuration + +If you prefer explicit configuration: + +```javascript +Sentry.init({ + dsn: "your-dsn", + spotlight: process.env.NODE_ENV === "development", + // or explicitly: + // spotlight: "http://localhost:8969/stream", +}); +``` + +### Unsupported SDKs (DSN Workaround) + +If your SDK doesn't support the `spotlight` option or the `SENTRY_SPOTLIGHT` environment variable, you can use the DSN workaround: + +```javascript +Sentry.init({ + dsn: "http://spotlight@localhost:8969/0", +}); +``` + +:::caution[Local Development Only] +This DSN is only for local development with Spotlight. Make sure to use your real Sentry DSN in production: + +```javascript +Sentry.init({ + dsn: process.env.NODE_ENV === "production" + ? "your-real-sentry-dsn" + : "http://spotlight@localhost:8969/0", +}); +``` +::: + +## Troubleshooting + +### Command Not Found + +If `spotlight` is not found, make sure you've installed it: + +```bash +npm install -g @spotlightjs/sidecar +# or use npx +npx @spotlightjs/sidecar run node server.js +``` + +### No Events Showing Up + +1. **Check SDK Configuration**: Ensure your Sentry SDK is properly initialized +2. **Verify Environment Variable**: The SDK should respect `SENTRY_SPOTLIGHT` +3. **Check Port**: Make sure the port isn't already in use +4. **Enable Debug Mode**: Run with `-d` flag to see what's happening + +```bash +spotlight run -d node server.js +``` + +### Port Already in Use + +If port 8969 is already taken: + +```bash +# Use a different port +spotlight run -p 9000 node server.js + +# Or let the OS choose an available port +spotlight run -p 0 node server.js +``` + +## Next Steps + +- [View events in your terminal with Tail mode](/docs/cli/tail/) +- [See all CLI options](/docs/cli/reference/) +- [Configure the Spotlight UI](/docs/reference/configuration/) + diff --git a/packages/website/src/content/docs/docs/cli/tail.mdx b/packages/website/src/content/docs/docs/cli/tail.mdx new file mode 100644 index 000000000..d7d89d945 --- /dev/null +++ b/packages/website/src/content/docs/docs/cli/tail.mdx @@ -0,0 +1,404 @@ +--- +title: Spotlight Tail +description: Stream and filter Spotlight events in real-time from your terminal +sidebar: + order: 2 +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +The `tail` command streams events from Spotlight to your terminal in real-time. You can filter by event type and choose different output formats. + +## Basic Usage + +```bash +spotlight tail [event-types...] [options] +``` + +**Key features:** +- Filter events by type (errors, logs, traces, attachments) +- Choose output format (human, logfmt, json, markdown) +- Connect to existing sidecar or start a new one automatically + +## Event Types + +You can filter which events to display: + +### Available Event Types + +- `errors` - Runtime errors and exceptions with stack traces +- `logs` - Application logs (info, warn, debug messages) +- `traces` - Performance traces and spans + +### Show Everything + +Use magic words to show all event types: + +```bash +spotlight tail +# or explicitly: +spotlight tail all +spotlight tail everything +spotlight tail '*' +``` + +### Filter Specific Types + +```bash +# Only errors +spotlight tail errors + +# Only logs +spotlight tail logs + +# Errors and logs +spotlight tail errors logs + +# Errors, logs, and traces +spotlight tail errors logs traces +``` + +## Output Formats + +Control how events are displayed with the `-f` or `--format` option. + +### Human-Readable Format (Default) + +Nicely formatted, colored output optimized for reading: + +```bash +spotlight tail --format human +# or just: +spotlight tail +``` + +**Example output:** +``` +🔴 ERROR | 2025-10-31 14:23:45 +TypeError: Cannot read property 'id' of undefined + at getUserData (api/users.js:42) + at processRequest (api/middleware.js:18) + +📝 LOG | 2025-10-31 14:23:46 +[INFO] Request processed successfully + user_id: 12345 + duration: 234ms +``` + +### Logfmt Format + +Machine-readable key-value format: + +```bash +spotlight tail --format logfmt +``` + +**Example output:** +``` +level=error time=2025-10-31T14:23:45Z message="TypeError: Cannot read property" file=api/users.js line=42 +level=info time=2025-10-31T14:23:46Z message="Request processed" user_id=12345 duration=234ms +``` + +**Perfect for:** +- Log aggregation tools +- Piping to other CLI tools +- Parsing with standard tools like `grep`, `awk` + +### JSON Format + +Structured JSON output for programmatic processing: + +```bash +spotlight tail --format json +``` + +**Example output:** +```json +{"level":"error","timestamp":"2025-10-31T14:23:45Z","message":"TypeError: Cannot read property 'id' of undefined","stack":[...]} +{"level":"info","timestamp":"2025-10-31T14:23:46Z","message":"Request processed","user_id":12345,"duration":"234ms"} +``` + +**Perfect for:** +- CI/CD pipelines +- Automated testing +- Integration with other tools via `jq` + +### Markdown Format + +Formatted for documentation or reports: + +```bash +spotlight tail --format md +``` + +**Example output:** +```markdown +## Error - TypeError +**Time:** 2025-10-31 14:23:45 +**File:** api/users.js:42 + +Cannot read property 'id' of undefined + +### Stack Trace +- at getUserData (api/users.js:42) +- at processRequest (api/middleware.js:18) +``` + +**Perfect for:** +- Creating incident reports +- Sharing errors in documentation +- GitHub issues or PRs + +## Connection Modes + +### Connect to Existing Sidecar + +If a Spotlight sidecar is already running, `tail` will connect to it: + +```bash +# Terminal 1: Your app is running with Spotlight +npm run dev + +# Terminal 2: Tail events +spotlight tail errors logs +``` + +### Start New Sidecar + +If no sidecar is running, `tail` will start one automatically: + +```bash +spotlight tail +# ✓ Started new sidecar on port 8969 +``` + +## Options + +### Port Configuration + +```bash +# Connect to sidecar on default port (8969) +spotlight tail + +# Connect to custom port +spotlight tail -p 3000 + +# Start sidecar on random available port +spotlight tail -p 0 +``` + +### Format Selection + +```bash +# Human-readable (default) +spotlight tail -f human + +# Logfmt for parsing +spotlight tail -f logfmt + +# JSON for automation +spotlight tail -f json + +# Markdown for documentation +spotlight tail -f md +``` + +### Debug Mode + +Enable verbose logging to troubleshoot issues: + +```bash +spotlight tail -d +# or +spotlight tail --debug +``` + +## Common Use Cases + +### Development Monitoring + +Monitor errors and logs while developing: + +```bash +# Terminal 1: Run your app +npm run dev + +# Terminal 2: Watch for errors and logs +spotlight tail errors logs --format human +``` + +### CI/CD Integration + +Capture events during automated tests: + +```bash +# Start sidecar and run tests, output as JSON +spotlight tail -f json > spotlight-events.json & +SIDECAR_PID=$! + +# Run your tests +npm test + +# Cleanup +kill $SIDECAR_PID +``` + +### Error Monitoring + +Focus only on errors with clean output: + +```bash +spotlight tail errors --format logfmt | grep "level=error" +``` + +### Performance Analysis + +Stream trace data for performance investigation: + +```bash +spotlight tail traces --format json | jq '.duration' +``` + +### Log Aggregation + +Send formatted logs to a file: + +```bash +spotlight tail logs --format logfmt >> app-logs.txt +``` + +## Advanced Examples + +### Filter and Process with jq + +```bash +# Get all error messages from the last run +spotlight tail errors -f json | jq -r '.message' + +# Find slow traces (duration > 1000ms) +spotlight tail traces -f json | jq 'select(.duration > 1000)' +``` + +### Combine with grep + +```bash +# Only show errors from specific file +spotlight tail errors -f logfmt | grep "file=api/users.js" + +# Watch for specific error messages +spotlight tail errors | grep "database connection" +``` + +### Multiple Filters + +```bash +# Stream errors and logs, format as logfmt, filter by level +spotlight tail errors logs -f logfmt | grep "level=error" +``` + +### Background Monitoring + +```bash +# Start tailing in the background +spotlight tail -f logfmt > spotlight.log 2>&1 & +echo $! > spotlight.pid + +# Stop it later +kill $(cat spotlight.pid) +``` + +## Output Examples + +### Error Output (Human Format) + +``` +🔴 ERROR | 2025-10-31 14:23:45.123 +TypeError: Cannot read property 'id' of undefined + +Location: api/users.js:42:10 + +Stack Trace: + at getUserData (api/users.js:42:10) + at processRequest (api/middleware.js:18:5) + at Layer.handle (express/lib/router/layer.js:95:5) + +Context: + request_id: req_abc123 + user_id: 12345 + method: GET + path: /api/users/12345 +``` + +### Log Output (Logfmt Format) + +``` +time=2025-10-31T14:23:45Z level=info message="User login successful" user_id=12345 ip=192.168.1.1 +time=2025-10-31T14:23:46Z level=warn message="Rate limit approaching" user_id=12345 requests=95 limit=100 +time=2025-10-31T14:23:47Z level=info message="Database query" query="SELECT * FROM users" duration=15ms +``` + +### Trace Output (JSON Format) + +```json +{ + "trace_id": "71a8c5e41ae1044dee67f50a07538fe7", + "span_id": "b1234567890abcde", + "transaction": "GET /api/users/:id", + "duration": 245.5, + "status": "ok", + "spans": [ + { + "description": "database query", + "duration": 45.2 + }, + { + "description": "http request", + "duration": 120.3 + } + ] +} +``` + +## Troubleshooting + +### No Events Appearing + +1. **Check SDK Configuration**: Ensure your app is sending events to Spotlight +2. **Verify Connection**: Make sure the sidecar is running on the correct port +3. **Check Event Types**: You might be filtering out the events you want to see + +```bash +# Show all events to see what's coming through +spotlight tail everything +``` + +### Connection Refused + +If you see a connection error: + +```bash +# Check if sidecar is running on the expected port +spotlight tail -p 8969 + +# Or try starting a new sidecar +spotlight tail -p 0 # Use random port +``` + +### Events Too Verbose + +Filter to only what you need: + +```bash +# Only critical errors +spotlight tail errors -f logfmt | grep "level=error" + +# Specific file or component +spotlight tail -f logfmt | grep "file=api/critical.js" +``` + +## Next Steps + +- [Run your app with Spotlight](/docs/cli/run/) +- [See complete CLI reference](/docs/cli/reference/) +- [Learn about MCP integration](/docs/mcp/) + diff --git a/packages/website/src/content/docs/docs/desktop-app/index.mdx b/packages/website/src/content/docs/docs/desktop-app/index.mdx new file mode 100644 index 000000000..1fc30c137 --- /dev/null +++ b/packages/website/src/content/docs/docs/desktop-app/index.mdx @@ -0,0 +1,336 @@ +--- +title: Desktop App +description: Standalone Spotlight application with built-in UI for local debugging +sidebar: + order: 0 +--- + +import DownloadButton from '../../../../components/DownloadButton.astro'; +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +The Spotlight Desktop App is a standalone application that combines the sidecar server and debugging UI in a single package. Perfect for when you want a dedicated debugging environment. + +## Why Use the Desktop App? + +The desktop app offers several advantages: + +- **All-in-one solution**: Sidecar server and UI bundled together +- **No browser required**: Dedicated window for debugging +- **Persistent workspace**: Stays open across browser refreshes +- **Auto-updates**: Always get the latest features +- **Clean separation**: Keep debugging separate from your development browser +- **Built-in HTTP MCP server:** Model Context Protocol (MCP) Server directly from the desktop app. +**Perfect for:** +- Headless or mobile development +- When you want debugging in a separate window +- Team members who prefer desktop apps +- Quick setup without browser configuration + +## Download and Installation + +Get started by downloading the latest version for your platform: + +Download for Mac + +:::note[Other Platforms] +Currently, the desktop app is available for macOS. Windows and Linux support is coming soon. + +In the meantime, you can use the [CLI](/docs/cli/) or [browser-based UI](/docs/sidecar/npx/). +::: + +### Installation Steps + +1. **Download** the app using the button above +2. **Open** the downloaded `.dmg` file +3. **Drag** Spotlight to your Applications folder +4. **Launch** Spotlight from Applications + +## What's Included + +The desktop app provides everything you need for local debugging: + +### Built-in Sidecar Server + +The app automatically starts a Spotlight sidecar server: + +- Default port: 8969 (configurable in settings) +- No need to run separate commands +- Just launch the app and you're ready + +### Debugging UI + +Access all Spotlight features through the dedicated interface: + +- **Errors Tab**: View runtime errors with full stack traces +- **Traces Tab**: Inspect performance traces and spans +- **Logs Tab**: Browse application logs with filtering +- **Profiles Tab**: Analyze performance profiles +- **Settings**: Configure sidecar and UI preferences + +### Auto-Updates + +The app keeps itself up to date: + +- Automatically checks for updates +- Downloads and installs in the background +- Ensures you always have the latest features and bug fixes + +## Setup Your Application + +Once the desktop app is running, configure your application to send telemetry to Spotlight: + +### Backend Applications (Node.js, Python, etc.) + +Set the `SENTRY_SPOTLIGHT` environment variable: + + + + ```javascript + // Sentry will automatically use SENTRY_SPOTLIGHT env var + import * as Sentry from '@sentry/node'; + + Sentry.init({ + dsn: 'your-dsn', // Optional for local dev + // No spotlight config needed - handled by env var + }); + ``` + + Run your app: + ```bash + SENTRY_SPOTLIGHT=1 node server.js + # or + export SENTRY_SPOTLIGHT=1 + npm run dev + ``` + + + ```python + # Sentry will automatically use SENTRY_SPOTLIGHT env var + import sentry_sdk + + sentry_sdk.init( + dsn="your-dsn", # Optional for local dev + # No spotlight config needed - handled by env var + ) + ``` + + Run your app: + ```bash + SENTRY_SPOTLIGHT=1 python app.py + # or + export SENTRY_SPOTLIGHT=1 + flask run + ``` + + + Most Sentry SDKs support the `SENTRY_SPOTLIGHT` environment variable: + + ```bash + SENTRY_SPOTLIGHT=1 ./your-app + # or + export SENTRY_SPOTLIGHT=1 + ./your-app + ``` + + Check your SDK's documentation for Spotlight support. + + + +### Frontend Applications + +For browser-based applications, add the Spotlight browser integration: + +```javascript +import * as Sentry from '@sentry/browser'; + +Sentry.init({ + dsn: 'your-dsn', // Optional for local dev + integrations: [ + Sentry.spotlightBrowserIntegration() + ], + // Only enable in development + enabled: process.env.NODE_ENV === 'development' +}); +``` + +## Using the Desktop App + +### Starting the App + +1. Launch Spotlight from your Applications folder +2. The sidecar server starts automatically on port 8969 +3. The debugging UI opens in the app window + +### Viewing Events + +As your application sends telemetry to Spotlight: + +1. **Errors appear in real-time** in the Errors tab +2. **Traces are displayed** with timing information +3. **Logs stream** to the Logs tab +4. **Profiles** show up when captured + +### Filtering and Searching + +Use the built-in filters to find what you need: + +- **Search by text**: Find errors or logs containing specific text +- **Filter by type**: Show only errors, traces, or logs +- **Time range**: Focus on specific time periods +- **Source filter**: Show events from specific files or components + +### Inspecting Details + +Click any event to see full details: + +- **Errors**: Complete stack traces, context, and breadcrumbs +- **Traces**: Full span tree with timing breakdown +- **Logs**: Structured log data with attributes +- **Profiles**: Flamegraphs and performance metrics + +### Clearing Events + +Use the clear button in the toolbar to remove all events and start fresh. + +## Configuration + +### Changing the Port + +If port 8969 is already in use: + +1. Open Spotlight **Settings** (via menu or gear icon) +2. Change the **Sidecar Port** setting +3. Restart the app +4. Update your app's SDK configuration to match + +### UI Preferences + +Customize the interface: + +- **Theme**: Choose light or dark mode +- **Font size**: Adjust for readability +- **Panel layout**: Configure which panels are visible + +## When to Use Desktop App vs CLI vs Browser + +Choose the right tool for your workflow: + +### Use Desktop App When: +- ✅ You want a dedicated debugging window +- ✅ You prefer desktop applications +- ✅ You're developing headless or mobile apps +- ✅ You want automatic updates + +### Use CLI When: +- ✅ You prefer terminal-based workflows +- ✅ You need to stream events to files +- ✅ You're automating with scripts +- ✅ You want machine-readable output + +### Use Browser UI When: +- ✅ You want overlay on your application +- ✅ You're debugging frontend web apps +- ✅ You want integrated developer experience + +[Learn more about CLI →](/docs/cli/) + +## Use Cases + +### Mobile Development + +When developing mobile apps, the desktop app provides a great debugging companion: + +1. Run the desktop app on your machine +2. Configure your mobile app's SDK to point to your machine's IP: + ``` + spotlight: "http://192.168.1.100:8969/stream" + ``` +3. Run your mobile app on device/simulator +4. View events in the desktop app + +### Backend Development + +For backend services without a browser: + +1. Start the desktop app +2. Run your backend with `SENTRY_SPOTLIGHT=1` +3. Make API requests to your service +4. See traces and errors in the desktop app + +### Microservices + +Debug multiple services simultaneously: + +1. Start the desktop app (single sidecar on port 8969) +2. Point all services to the same sidecar +3. See events from all services in one place +4. Filter by service or component + +## Troubleshooting + +### App Won't Start + +**macOS Security Warning:** + +If you see "Spotlight can't be opened because it is from an unidentified developer": + +1. Right-click the app and select "Open" +2. Click "Open" in the security dialog +3. macOS will remember this choice + +**Port Already in Use:** + +If you see a port conflict: +1. Change the port in Settings +2. Or close other applications using port 8969 + +### No Events Showing + +**Check SDK Configuration:** +1. Verify Sentry SDK is initialized in your app +2. Ensure `spotlight` integration is enabled +3. Check environment variable is set: `SENTRY_SPOTLIGHT=1` + +**Check Network:** +1. Verify your app can reach `localhost:8969` +2. Check firewall settings if needed + +**Enable Debug:** +1. In your app, enable Sentry debug mode +2. Check console for Spotlight connection messages + +### Events Not Updating + +**Refresh the View:** +- Click the refresh button or use Cmd+R + +**Clear and Restart:** +1. Clear events +2. Restart your application +3. Trigger new events + +## Privacy and Security + +### Local-Only + +The desktop app and sidecar run entirely on your local machine: + +- **No data sent to external servers** - Everything stays local +- **No telemetry collected** - The app doesn't track your usage +- **Memory-only storage** - Events are cleared when the app closes + +### Development Only + +Spotlight is designed exclusively for development: + +- **Never enable in production** - Use environment checks to restrict to development only +- **Guard sensitive data** - Keep production secrets out of test scenarios +- **Review before sharing** - Be mindful when sharing screenshots or logs + +## Next Steps + +- [Configure your SDK](/docs/setup/) - Setup guide for different frameworks +- [Use the CLI](/docs/cli/) - Terminal-based workflows +- [MCP Integration](/docs/mcp/) - Connect to AI assistants +- [Explore integrations](/docs/reference/integration/) - Custom integrations + diff --git a/packages/website/src/content/docs/docs/mcp/index.mdx b/packages/website/src/content/docs/docs/mcp/index.mdx new file mode 100644 index 000000000..206b38972 --- /dev/null +++ b/packages/website/src/content/docs/docs/mcp/index.mdx @@ -0,0 +1,365 @@ +--- +title: MCP Server +description: Connect Spotlight to AI coding assistants via Model Context Protocol +sidebar: + order: 0 +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +The Spotlight MCP (Model Context Protocol) server enables AI coding assistants like Cursor, Claude, and others to access your application's runtime data for debugging and development assistance. + +## What is MCP? + +[Model Context Protocol](https://modelcontextprotocol.io) is an open standard that allows AI assistants to securely access external data sources and tools. Spotlight's MCP server provides tools that let your AI assistant: + +- Search through application errors with full stack traces +- Query logs to understand application behavior +- Inspect performance traces and identify bottlenecks +- Get detailed timing information for distributed traces + +## Why Use Spotlight with MCP? + +When debugging with an AI coding assistant, it can now access actual runtime data from your application instead of just analyzing static code. This means: + +- **Context-aware debugging**: Your AI assistant sees the actual errors, not just the code +- **Real-time insights**: Access to live traces and logs during development +- **Faster issue resolution**: AI can analyze stack traces and suggest fixes based on real data +- **Better performance analysis**: AI can identify slow operations from trace data + +## Quick Start + +### 1. Install Spotlight MCP Server + +We recommend using `npx` to always get the latest version: + +**For Claude Desktop:** + +```bash +claude mcp add sentry-spotlight -- npx -y --prefer-online @spotlightjs/spotlight@latest mcp +``` + +**For Cursor:** + +Click the button below or add manually: + + + Add spotlight MCP server to Cursor + + +### 2. Manual Configuration (Alternative) + +If you prefer to configure manually, add Spotlight to your MCP client configuration: + + + + Add to your Cursor MCP settings (`.cursor/mcp.json` or Cursor settings UI): + + ```json + { + "mcpServers": { + "spotlight": { + "command": "npx", + "args": ["-y", "--prefer-online", "@spotlightjs/spotlight@latest", "mcp"] + } + } + } + ``` + + + Add to Claude Desktop's configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): + + ```json + { + "mcpServers": { + "spotlight": { + "command": "npx", + "args": ["-y", "--prefer-online", "@spotlightjs/spotlight@latest", "mcp"] + } + } + } + ``` + + + Add to Cline's MCP settings: + + ```json + { + "mcpServers": { + "spotlight": { + "command": "npx", + "args": ["-y", "--prefer-online", "@spotlightjs/spotlight@latest", "mcp"] + } + } + } + ``` + + + For other MCP-compatible clients, use this configuration: + + - **Command:** `npx` + - **Args:** `["-y", "--prefer-online", "@spotlightjs/spotlight@latest", "mcp"]` + - **Protocol:** stdio + + Refer to your MCP client's documentation for exact configuration format. + + + +### 3. Run Your Application + +Make sure your application is running and sending telemetry to Spotlight. + +**Option 1 - Use Spotlight CLI:** +```bash +spotlight run npm run dev +``` + +**Option 2 - Set environment variable:** +```bash +export SENTRY_SPOTLIGHT=1 +npm run dev +``` + +### 4. Use in Your AI Assistant + +Now your AI assistant has access to Spotlight tools! Try asking: + +- "Are there any errors in my application?" +- "Show me recent errors in the auth.js file" +- "What traces do we have from the last 5 minutes?" +- "Analyze the performance of trace ID abc123" +- "Show me logs related to database operations" + +## Available Tools + +The MCP server provides four powerful tools: + +### `spotlight.errors.search` + +Search for application errors with stack traces and context. + +**Perfect for:** +- Finding runtime errors and exceptions +- Investigating crashes and failures +- Analyzing error patterns + +[See detailed documentation →](/docs/mcp/tools/#spotlight-errors-search) + +### `spotlight.logs.search` + +Query application logs to understand behavior and flow. + +**Perfect for:** +- Understanding application execution flow +- Finding debug information +- Analyzing timing and performance from logs + +[See detailed documentation →](/docs/mcp/tools/#spotlight-logs-search) + +### `spotlight.traces.search` + +List recent performance traces with summary information. + +**Perfect for:** +- Getting an overview of recent requests +- Identifying slow operations +- Finding traces with errors + +[See detailed documentation →](/docs/mcp/tools/#spotlight-traces-search) + +### `spotlight.traces.get` + +Get detailed span tree and timing for a specific trace. + +**Perfect for:** +- Deep-diving into performance issues +- Analyzing distributed traces +- Understanding request flow and timing + +[See detailed documentation →](/docs/mcp/tools/#spotlight-traces-get) + +[View complete tools reference →](/docs/mcp/tools/) + +## Configuration + +### Custom Port + +If you need to run Spotlight on a different port: + +```bash +spotlight-sidecar mcp -p 3000 +``` + +Update your MCP client configuration to match: + +```json +{ + "mcpServers": { + "spotlight": { + "command": "spotlight", + "args": ["mcp", "-p", "3000"] + } + } +} +``` + +### Debug Mode + +Enable debug logging to troubleshoot MCP connection issues: + +```bash +spotlight-sidecar mcp -d +``` + +## How It Works + +The MCP integration connects your AI assistant to live application data: + +1. **Your Application** sends telemetry (errors, logs, traces) to the Spotlight sidecar via Sentry SDK +2. **Spotlight Sidecar** stores events in memory and provides them via MCP tools +3. **MCP Client** (Cursor, Claude, etc.) connects to Spotlight via stdio +4. **AI Assistant** uses MCP tools to query events and help with debugging + +``` +Your App → Sentry SDK → Spotlight Sidecar ← MCP Client ← AI Assistant + ↓ + [Errors, Logs, Traces] +``` + +## Requirements + +### Sentry SDK + +Your application must have a Sentry SDK configured to send events to Spotlight: + + + + ```javascript + import * as Sentry from '@sentry/node'; + + Sentry.init({ + dsn: 'your-dsn', // Optional for local dev + // Spotlight is auto-enabled if SENTRY_SPOTLIGHT env var is set + }); + ``` + + + ```python + import sentry_sdk + + sentry_sdk.init( + dsn="your-dsn", # Optional for local dev + # Spotlight is auto-enabled if SENTRY_SPOTLIGHT env var is set + ) + ``` + + + ```javascript + import * as Sentry from '@sentry/browser'; + + Sentry.init({ + dsn: 'your-dsn', + integrations: [Sentry.spotlightBrowserIntegration()], + }); + ``` + + + +### MCP Client + +You need an MCP-compatible client such as: +- [Cursor](https://cursor.sh) +- [Claude Desktop](https://claude.ai/download) +- [Cline](https://github.com/cline/cline) +- Any other MCP-compatible tool + +## Example Workflow + +Here's a typical debugging session with Spotlight MCP: + +1. **Start Spotlight MCP Server** + ```bash + spotlight-sidecar mcp + ``` + +2. **Run Your Application** + ```bash + spotlight-sidecar run npm run dev + ``` + +3. **Trigger an Error** in your application (e.g., click a button, make a request) + +4. **Ask Your AI Assistant** + ``` + You: "Are there any errors in my app?" + + AI: I'll check Spotlight for errors... + [Calls spotlight.errors.search] + + AI: "Yes, there's a TypeError in auth.js at line 42: + Cannot read property 'id' of undefined + + The error occurs in the getUserData function. + Would you like me to analyze the code?" + ``` + +5. **Deep Dive with Follow-ups** + ``` + You: "Show me the full trace for this request" + + AI: [Calls spotlight.traces.search and spotlight.traces.get] + + AI: "Here's the trace: + - Total duration: 245ms + - Database query: 45ms + - External API call: 180ms (this is slow!) + - Error occurred during user data processing + + The external API call is taking most of the time. + The error happens because the API returned null." + ``` + +## Troubleshooting + +### MCP Server Not Starting + +Check that the port isn't already in use: + +```bash +# Use a different port +spotlight-sidecar mcp -p 3000 + +# Enable debug logging +spotlight-sidecar mcp -d +``` + +### AI Assistant Not Seeing Tools + +1. Verify MCP server is running +2. Check your MCP client configuration is correct +3. Restart your MCP client after configuration changes +4. Check client logs for connection errors + +### No Events Available + +1. Ensure your application is running +2. Verify Sentry SDK is configured +3. Trigger some activity (errors, requests) in your app +4. Check that `SENTRY_SPOTLIGHT` environment variable is set or SDK has spotlight enabled + +### Connection Issues + +Enable debug mode to see detailed logs: + +```bash +spotlight-sidecar mcp -d +``` + +Check that your MCP client is using the correct command and arguments. + +## Next Steps + +- [Learn about available MCP tools](/docs/mcp/tools/) +- [See common debugging workflows](/docs/mcp/workflows/) +- [Explore CLI commands](/docs/cli/) + diff --git a/packages/website/src/content/docs/docs/mcp/tools.mdx b/packages/website/src/content/docs/docs/mcp/tools.mdx new file mode 100644 index 000000000..369641c8b --- /dev/null +++ b/packages/website/src/content/docs/docs/mcp/tools.mdx @@ -0,0 +1,519 @@ +--- +title: MCP Tools Reference +description: Complete reference for Spotlight MCP tools available to AI assistants +sidebar: + order: 1 +--- + +Spotlight provides four MCP tools that allow AI coding assistants to query your application's runtime data. + +## Tool Overview + +| Tool | Purpose | Returns | +|------|---------|---------| +| `spotlight.errors.search` | Find runtime errors | Errors with stack traces | +| `spotlight.logs.search` | Query application logs | Log entries with context | +| `spotlight.traces.search` | List performance traces | Trace summaries | +| `spotlight.traces.get` | Get trace details | Full span tree and timing | + +## Common Filter Parameters + +All search tools support these filter options: + +### `timeWindow` + +Look back a specified number of seconds from now. + +- **Type:** Number (seconds) +- **Examples:** + - `60` - Last minute + - `300` - Last 5 minutes + - `3600` - Last hour + +**Example:** +```json +{ + "filters": { + "timeWindow": 300 + } +} +``` + +### `filename` + +Search for events related to a specific file (exact match, case-sensitive). + +- **Type:** String +- **Examples:** + - `"auth.js"` + - `"Button.tsx"` + - `"api/users.ts"` + +**Example:** +```json +{ + "filters": { + "filename": "auth.js" + } +} +``` + +### `limit` and `offset` + +Paginate through results. + +- **Type:** Number +- **Examples:** + - `limit: 10` - Return first 10 results + - `limit: 20, offset: 10` - Skip first 10, return next 20 + +**Example:** +```json +{ + "filters": { + "limit": 10, + "offset": 0 + } +} +``` + +--- + +## spotlight.errors.search + +Search for runtime errors, exceptions, and crashes captured by Spotlight. + +### Purpose + +Find and analyze application errors with full context: + +- **Complete stack traces** with file and line numbers +- **Error messages and types** (TypeError, ReferenceError, etc.) +- **Request/response context** for API failures +- **Browser/device information** when available + +### When to Use + +Use this tool when: + +- User reports "error", "broken", "not working", "crash", or "bug" +- Investigating unexpected application behavior +- Verifying no regressions after code changes +- Debugging errors in specific files + +### Parameters + +```typescript +{ + filters: { + timeWindow?: number, // Seconds to look back + filename?: string, // Exact filename in stack trace + limit?: number, // Max results + offset?: number // Skip first N results + } +} +``` + +### Usage Examples + +#### Get Recent Errors + +```json +{ + "filters": { + "timeWindow": 60 + } +} +``` + +Returns errors from the last minute. + +#### Find Errors in Specific File + +```json +{ + "filters": { + "filename": "auth.tsx" + } +} +``` + +Returns all errors with `auth.tsx` in the stack trace. + +#### Paginated Error Search + +```json +{ + "filters": { + "limit": 10, + "offset": 0 + } +} +``` + +Returns first 10 errors. + +### Response Format + +Each error includes: + +- **Error Message**: The exception message +- **Error Type**: Exception class (e.g., TypeError, ReferenceError) +- **Stack Trace**: Full stack with file:line:column +- **Timestamp**: When the error occurred +- **Context**: Additional information (request data, user info, etc.) + +### Example AI Prompts + +- "Are there any errors in my app?" +- "Show me errors from the last 5 minutes" +- "Find errors in the authentication module" +- "What's causing the TypeError in user.js?" + +--- + +## spotlight.logs.search + +Search application logs to understand behavior, debug issues, and trace execution flow. + +### Purpose + +Query logs to see: + +- **Application execution flow** and behavior +- **Debug messages** and timing information +- **API request/response logs** with context +- **Database query logs** with performance metrics + +### When to Use + +Best for: + +- Understanding how the application works +- User mentions "logs", "debugging", or "trace" +- Investigating what the app is doing internally +- Performance investigation and timing analysis + +:::note +For error diagnostics with stack traces, use `spotlight.errors.search` instead. +::: + +### Parameters + +```typescript +{ + filters: { + timeWindow?: number, // Seconds to look back + filename?: string, // Exact filename generating logs + limit?: number, // Max results + offset?: number // Skip first N results + } +} +``` + +### Log Levels + +- **INFO**: General application flow and significant events +- **WARN**: Potential issues that don't break functionality +- **DEBUG**: Detailed execution information for troubleshooting + +:::note +ERROR level logs are available, but `spotlight.errors.search` provides more detailed error context including stack traces. +::: + +### Usage Examples + +#### Check Recent Activity + +```json +{ + "filters": { + "timeWindow": 300 + } +} +``` + +Returns logs from the last 5 minutes. + +#### Find Logs from Specific File + +```json +{ + "filters": { + "filename": "database.ts" + } +} +``` + +Returns logs generated by `database.ts`. + +#### Get Latest Log Entries + +```json +{ + "filters": { + "limit": 20, + "offset": 0 + } +} +``` + +Returns 20 most recent log entries. + +### Response Format + +Each log entry includes: + +- **Level**: Log severity (info, warn, debug) +- **Message**: The log message +- **Timestamp**: When it was logged +- **Attributes**: Custom structured data (user_id, request_id, duration, etc.) +- **Source**: File and line number (when available) + +### Example AI Prompts + +- "Show me recent logs" +- "What's happening in the authentication flow?" +- "Show me database query logs" +- "How long are API requests taking?" + +--- + +## spotlight.traces.search + +List recent performance traces with summary information. + +### Purpose + +Get an overview of recent application activity: + +- **Trace IDs** and root transaction names +- **Total duration** and span counts +- **Error counts** per trace +- **Timestamps** for timeline analysis + +### When to Use + +Perfect for: + +- Investigating performance issues or slow requests +- User mentions "traces", "performance", or "slow" +- Finding specific transactions or requests +- Getting an overview of recent activity + +### Parameters + +```typescript +{ + filters: { + timeWindow?: number, // Seconds to look back + filename?: string, // Exact filename in trace spans + limit?: number, // Max results + offset?: number // Skip first N results + } +} +``` + +### Usage Examples + +#### Get Recent Traces + +```json +{ + "filters": { + "timeWindow": 300 + } +} +``` + +Returns traces from the last 5 minutes. + +#### Find Most Recent Traces + +```json +{ + "filters": { + "limit": 10, + "offset": 0 + } +} +``` + +Returns 10 most recent traces. + +#### Find Traces Involving Specific File + +```json +{ + "filters": { + "filename": "api.ts" + } +} +``` + +Returns traces with spans from `api.ts`. + +### Response Format + +Each trace summary includes: + +- **Trace ID**: Unique identifier (first 8 chars shown) +- **Transaction Name**: Root operation (e.g., "GET /api/users/:id") +- **Duration**: Total time in milliseconds +- **Span Count**: Number of operations in the trace +- **Error Count**: Number of errors in this trace +- **Timestamp**: When the trace started + +### Next Step + +After finding a trace of interest, use `spotlight.traces.get` with the trace ID to see detailed timing breakdown. + +### Example AI Prompts + +- "Show me recent traces" +- "What requests happened in the last minute?" +- "Find slow transactions" +- "Show me traces with errors" + +--- + +## spotlight.traces.get + +Get complete span tree and timing breakdown for a specific trace. + +### Purpose + +Deep-dive into a specific trace to see: + +- **Hierarchical span tree** with parent-child relationships +- **Individual operation durations** for each span +- **Database queries, API calls**, and render timings +- **Error details** within the trace timeline + +### When to Use + +Use this after: + +- Finding a trace ID from `spotlight.traces.search` +- Investigating a specific slow request or transaction +- Understanding detailed execution flow +- Finding performance bottlenecks in a trace + +### Parameters + +```typescript +{ + traceId: string // Full 32-char hex or first 8 chars +} +``` + +The trace ID can be: +- First 8 characters: `"71a8c5e4"` +- Full 32 characters: `"71a8c5e41ae1044dee67f50a07538fe7"` + +### Usage Examples + +#### Using Short Trace ID + +```json +{ + "traceId": "71a8c5e4" +} +``` + +#### Using Full Trace ID + +```json +{ + "traceId": "71a8c5e41ae1044dee67f50a07538fe7" +} +``` + +### Response Format + +Returns a hierarchical span tree showing: + +- **Span ID**: Unique identifier for each operation +- **Operation**: Description of what the span does +- **Duration**: Time in milliseconds +- **Start Time**: When the operation started (relative to trace start) +- **Parent/Child Relationships**: How operations nest +- **Status**: ok, error, etc. +- **Tags/Data**: Additional context (SQL queries, HTTP methods, etc.) + +Example structure: +``` +Transaction: GET /api/users/123 (245ms) +├─ Database Query: SELECT * FROM users (45ms) +├─ HTTP Request: GET external-api.com (180ms) +│ └─ DNS Lookup (5ms) +└─ Process Response (20ms) + └─ Error: Cannot read property 'id' +``` + +### Example AI Prompts + +- "Show me details for trace 71a8c5e4" +- "Analyze trace abc12345 for performance issues" +- "Why is trace xyz taking so long?" +- "Show me the span tree for this slow request" + +--- + +## Workflow Patterns + +### Error Investigation + +1. **Search for errors**: `spotlight.errors.search` +2. **If error mentions a trace**: Get trace details with `spotlight.traces.get` +3. **Check related logs**: `spotlight.logs.search` with filename from error + +### Performance Analysis + +1. **List recent traces**: `spotlight.traces.search` +2. **Identify slow traces**: Look at duration in summary +3. **Deep dive**: `spotlight.traces.get` with trace ID +4. **Check logs**: `spotlight.logs.search` for timing details + +### Understanding Application Behavior + +1. **Check logs**: `spotlight.logs.search` for recent activity +2. **Look for errors**: `spotlight.errors.search` for issues +3. **Examine traces**: `spotlight.traces.search` for request flow + +## Best Practices + +### Time Windows + +- Use **60s** (1 minute) for recent activity +- Use **300s** (5 minutes) for broader investigation +- Use **3600s** (1 hour) for historical analysis + +### Pagination + +- Start with `limit: 10` to avoid overwhelming output +- Use `offset` to load more if needed +- For specific issues, filter by `filename` instead of paginating + +### Combining Filters + +You can only use one filter type at a time: +- Either `timeWindow` +- Or `filename` +- Or `limit`/`offset` + +Choose the most specific filter for your use case. + +### Following Trace IDs + +Traces often reference related data: +1. Errors include trace IDs → use `spotlight.traces.get` +2. Logs include trace IDs → use `spotlight.traces.get` +3. Trace spans reference files → use `spotlight.logs.search` or `spotlight.errors.search` with filename + +## Next Steps + +- [See MCP workflows](/docs/mcp/workflows/) - Common debugging patterns +- [MCP server setup](/docs/mcp/) - Getting started guide +- [CLI reference](/docs/cli/reference/) - Command-line tools + diff --git a/packages/website/src/content/docs/docs/mcp/workflows.mdx b/packages/website/src/content/docs/docs/mcp/workflows.mdx new file mode 100644 index 000000000..f50a9f69b --- /dev/null +++ b/packages/website/src/content/docs/docs/mcp/workflows.mdx @@ -0,0 +1,524 @@ +--- +title: MCP Workflows +description: Common debugging workflows using Spotlight MCP tools with AI assistants +sidebar: + order: 2 +--- + +Learn how to effectively use Spotlight MCP tools with your AI coding assistant for common debugging scenarios. + +## Quick Start Workflow + +The simplest way to start debugging with Spotlight MCP: + +**Your prompt:** +``` +"Check if there are any errors in my application" +``` + +**What the AI does:** +1. Calls `spotlight.errors.search` with recent timeWindow +2. Analyzes any errors found +3. Suggests fixes or asks for more context + +This works because the AI assistant knows to check Spotlight first when you mention errors or issues. + +## Common Workflows + +### 1. Error Investigation + +**Scenario:** User reports an error or unexpected behavior. + +#### Step 1: Find the Error + +**Your prompt:** +``` +"My login page is broken. What's the error?" +``` + +**AI action:** +```json +spotlight.errors.search({ + filters: { timeWindow: 300 } +}) +``` + +#### Step 2: Analyze the Error + +The AI receives: +``` +TypeError: Cannot read property 'token' of null + at handleLogin (auth.js:42) + at onClick (LoginButton.tsx:18) +``` + +**AI response:** +``` +I found a TypeError in auth.js at line 42. The error indicates +that you're trying to access the 'token' property on a null object. +``` + +#### Step 3: Deep Dive with Code + +**Your follow-up:** +``` +"Show me the code around that error" +``` + +**AI action:** +- Reads `auth.js` lines 35-50 +- Analyzes the code context +- Suggests fix + +#### Step 4: Check Related Traces + +**Your follow-up:** +``` +"Is there a trace for this request?" +``` + +**AI action:** +```json +spotlight.traces.search({ + filters: { timeWindow: 60 } +}) +``` + +Then gets trace details with `spotlight.traces.get` if trace ID found. + +--- + +### 2. Performance Investigation + +**Scenario:** Application feels slow, need to identify bottlenecks. + +#### Step 1: List Recent Traces + +**Your prompt:** +``` +"Why is my API so slow?" +``` + +**AI action:** +```json +spotlight.traces.search({ + filters: { timeWindow: 300 } +}) +``` + +#### Step 2: Identify Slow Traces + +**AI response:** +``` +I found several traces. Here are the slowest: +- GET /api/users/profile: 2,450ms +- POST /api/data/upload: 1,820ms +- GET /api/products/search: 980ms + +The profile endpoint is notably slow. Let me analyze it. +``` + +#### Step 3: Analyze Slow Trace + +**AI action:** +```json +spotlight.traces.get({ + traceId: "abc12345" +}) +``` + +**AI response:** +``` +The slow profile request breaks down as: +- Database query: 2,100ms (bottleneck!) +- JSON processing: 200ms +- Response formatting: 150ms + +The database query is taking most of the time. +Would you like me to look at the query? +``` + +#### Step 4: Fix and Verify + +After making changes: + +**Your prompt:** +``` +"Check if the profile endpoint is faster now" +``` + +**AI checks recent traces again and compares durations** + +--- + +### 3. Understanding Application Behavior + +**Scenario:** Need to understand how a feature works. + +#### Step 1: Trigger the Feature + +1. Interact with your application +2. Trigger the feature you want to understand + +#### Step 2: Check Logs + +**Your prompt:** +``` +"What happened when I clicked the submit button?" +``` + +**AI action:** +```json +spotlight.logs.search({ + filters: { timeWindow: 60 } +}) +``` + +#### Step 3: Analyze Flow + +**AI response:** +``` +I can see the following flow: +1. Form validation started +2. API request to /api/submit +3. Database insert operation (25ms) +4. Email notification triggered +5. Success response returned + +Everything looks normal. The operation took 180ms total. +``` + +--- + +### 4. Debugging Specific Files + +**Scenario:** You made changes to a file and want to check for issues. + +#### Step 1: Check for Errors + +**Your prompt:** +``` +"Are there any errors in auth.tsx?" +``` + +**AI action:** +```json +spotlight.errors.search({ + filters: { filename: "auth.tsx" } +}) +``` + +#### Step 2: Check Logs + +**Your prompt:** +``` +"Show me logs from auth.tsx" +``` + +**AI action:** +```json +spotlight.logs.search({ + filters: { filename: "auth.tsx" } +}) +``` + +#### Step 3: Analyze Together + +The AI can now correlate errors and logs from the same file to give you a complete picture. + +--- + +### 5. Regression Testing + +**Scenario:** After deployment or changes, verify nothing broke. + +#### Step 1: Baseline Check + +**Your prompt:** +``` +"Check for any errors or issues after my deployment" +``` + +**AI action:** +```json +spotlight.errors.search({ + filters: { timeWindow: 300 } +}) +``` + +#### Step 2: Performance Comparison + +**Your prompt:** +``` +"Compare performance before and after" +``` + +**AI can:** +- Get recent traces +- Calculate average durations +- Identify regressions + +--- + +### 6. Distributed Tracing Analysis + +**Scenario:** Debugging a request that spans multiple services. + +#### Step 1: Find the Request Trace + +**Your prompt:** +``` +"I made a request to /api/orders/create. Show me the full trace." +``` + +**AI action:** +```json +spotlight.traces.search({ + filters: { timeWindow: 60 } +}) +``` + +Filters for transactions matching the path. + +#### Step 2: Analyze the Span Tree + +**AI action:** +```json +spotlight.traces.get({ + traceId: "found-trace-id" +}) +``` + +**AI response:** +``` +Transaction: POST /api/orders/create (450ms) +├─ Database: Check inventory (45ms) +├─ HTTP: Call payment service (280ms) +│ ├─ Payment validation (50ms) +│ └─ Charge card (220ms) +├─ Database: Create order (80ms) +└─ HTTP: Send notification (45ms) + +The payment service is the bottleneck at 280ms. +``` + +--- + +## Advanced Patterns + +### Correlating Errors with Traces + +When an error includes a trace ID: + +**Your prompt:** +``` +"This error mentions trace xyz123. What was happening?" +``` + +**AI action:** +1. Get trace details: `spotlight.traces.get({ traceId: "xyz123" })` +2. Analyze span tree +3. Identify where error occurred in the flow + +### Time-Based Analysis + +Investigate issues during a specific time: + +**Your prompt:** +``` +"What happened around 2:30 PM when the app crashed?" +``` + +**AI action:** +- Searches errors around that timeWindow +- Gets related traces +- Analyzes logs from that period +- Correlates all events to build timeline + +### Pattern Detection + +Find recurring issues: + +**Your prompt:** +``` +"Are there any recurring errors?" +``` + +**AI action:** +1. Gets all recent errors +2. Groups by error message/type +3. Identifies patterns +4. Reports frequency and commonalities + +--- + +## Effective Prompts + +### Good Prompts + +These prompts work well with Spotlight MCP: + +- ✅ "Are there any errors?" +- ✅ "Show me errors from auth.js" +- ✅ "Why is the API slow?" +- ✅ "What happened in the last 5 minutes?" +- ✅ "Analyze trace abc123" +- ✅ "Show me database query logs" + +### Prompts That Need Context + +These might need clarification: + +- ⚠️ "Fix the bug" → Be specific about what's broken +- ⚠️ "It's slow" → Specify what action or endpoint +- ⚠️ "Something's wrong" → Describe the symptom + +### Following Up + +Always effective: + +- "Show me the code" +- "What's causing this?" +- "How can I fix it?" +- "Are there related errors?" +- "Check the trace for this request" + +--- + +## Best Practices + +### 1. Start Broad, Then Narrow + +``` +You: "Are there any errors?" +AI: [Finds multiple errors] + +You: "Focus on errors in the auth module" +AI: [Filters to auth-related files] + +You: "Show me the code for that error" +AI: [Reads specific file and analyzes] +``` + +### 2. Use Timeframes Effectively + +- **Last 60s** - Immediate issues you just triggered +- **Last 5min** - Recent session activity +- **Last hour** - Broader investigation + +### 3. Combine Tools + +The AI can use multiple tools together: + +``` +You: "Debug the slow checkout process" + +AI workflow: +1. spotlight.traces.search → Find checkout traces +2. spotlight.traces.get → Analyze slow trace +3. spotlight.logs.search → Check related logs +4. spotlight.errors.search → Look for errors +``` + +### 4. Reproduce First + +For best results: + +1. Trigger the issue in your app +2. Then ask the AI to investigate +3. Fresh data gives better insights + +### 5. Iterate + +Don't expect one prompt to solve everything: + +``` +You: "Why did this fail?" +AI: [Finds error] + +You: "What was the request data?" +AI: [Shows context from error] + +You: "Is this validation working correctly?" +AI: [Reads validation code] + +You: "How should I fix it?" +AI: [Suggests solution] +``` + +--- + +## Troubleshooting Workflows + +### "No Errors Found" + +**What to do:** +1. Reproduce the issue in your app +2. Ask AI to check again immediately +3. Make sure your app is running with Spotlight enabled + +### "No Traces Available" + +**What to do:** +1. Verify Sentry SDK has tracing enabled +2. Trigger some requests in your app +3. Check SDK configuration with AI + +### "Can't Find Specific Event" + +**What to do:** +1. Widen the time window +2. Remove file filters +3. Ask AI to show everything + +--- + +## Example Debugging Session + +Here's a complete example: + +``` +You: "My app crashed when I clicked submit. What happened?" + +AI: Let me check for errors... +[Calls spotlight.errors.search] + +AI: I found a TypeError in forms/SubmitButton.tsx at line 34: + "Cannot read property 'validate' of undefined" + + Would you like me to analyze the code? + +You: "Yes, and show me what happened before the crash" + +AI: [Reads SubmitButton.tsx code] +[Calls spotlight.logs.search for recent activity] + +AI: Here's what I found: + + Code issue: Line 34 tries to call this.validator.validate(), + but this.validator is undefined. + + Logs show: + 1. Form render started + 2. Submit button clicked + 3. Crash occurred - no validator was initialized + + The validator is supposed to be set in the constructor, + but it looks like it's only set when props.validationSchema + exists. In your case, that prop might be missing. + + Would you like me to suggest a fix? + +You: "Yes please" + +AI: [Suggests adding null check or default validator] +``` + +--- + +## Next Steps + +- [Learn about MCP tools](/docs/mcp/tools/) - Detailed tool reference +- [MCP setup guide](/docs/mcp/) - Getting started +- [CLI workflows](/docs/cli/) - Using Spotlight from terminal + diff --git a/packages/website/src/content/docs/docs/sidecar/index.mdx b/packages/website/src/content/docs/docs/sidecar/index.mdx index da3f83408..625d71ed5 100644 --- a/packages/website/src/content/docs/docs/sidecar/index.mdx +++ b/packages/website/src/content/docs/docs/sidecar/index.mdx @@ -1,32 +1,271 @@ --- title: What is the Sidecar? -description: A server forwarding events to Spotlight UI. +description: The local proxy server that powers Spotlight's debugging capabilities sidebar: order: 0 --- -import { LinkCard } from '@astrojs/starlight/components'; +import { LinkCard, CardGrid } from '@astrojs/starlight/components'; -The Sidecar uses SSE (Server-Sent Events) to forward events to the Spotlight UI. It is a standalone server that can be deployed on the same machine as the Spotlight UI or on a different machine. +The Spotlight Sidecar is a lightweight local proxy server that sits between your application and the Spotlight UI. It's the backbone of Spotlight's real-time debugging capabilities. -It receives `POST` requests on `/stream` from the Sentry SDKs or any other source and forwards them to the Spotlight UI via SSE. +## How It Works -By default the Sidecar listens on port `8969` and the Spotlight UI connects to it on `http://localhost:8969/stream`. +``` +Your Application → Sentry SDK → Sidecar Server → Spotlight UI + ↓ + [Stores & Streams] + Errors, Traces, Logs +``` + +The sidecar: + +1. **Receives** telemetry data from your application via Sentry SDKs +2. **Stores** events in memory for quick access +3. **Streams** events to connected UIs via Server-Sent Events (SSE) +4. **Provides** APIs for querying historical data (used by MCP tools) + +## Key Features + +### Real-Time Event Streaming + +Uses Server-Sent Events (SSE) to push events to the UI as they happen. No polling, no delays - see errors and traces the moment they occur. + +### In-Memory Storage + +Events are buffered in memory, allowing you to: +- Browse historical events during your session +- Query past errors and traces +- Analyze patterns over time + +### Multiple Connection Modes -The url can be configured via the `sidecar` config variable in the Spotlight UI see [Configuration](/docs/reference/configuration/#sidecar). +The sidecar supports different ways to run: +- **Standalone**: Run independently and connect any UI +- **Embedded**: Automatically started by framework integrations +- **CLI-wrapped**: Started by `spotlight` commands +- **Desktop app**: Bundled with the Spotlight desktop application -Also in the Sentry SDKs the URL can be configured via the `spotlight` option, for example in the Python SDK: +### Built-in UI + +The sidecar includes a web-based UI accessible at `http://localhost:8969` (default port): + +- No additional setup required +- View events directly in your browser +- Works alongside desktop app and MCP clients + +## Configuration + +### Default Settings + +The sidecar comes pre-configured with sensible defaults: + +- **Port**: 8969 +- **Event endpoint**: `http://localhost:8969/stream` +- **UI endpoint**: `http://localhost:8969` + +### Custom Port + +You can configure the port in several ways: + +**Via CLI:** +```bash +spotlight -p 3000 +``` -```python {4} +**Via SDK:** +```python import sentry_sdk sentry_sdk.init( - spotlight="http://localhost:8969/stream", + spotlight="http://localhost:3000/stream", ) ``` -Spotlight provides a number of convenience utilities to run the Sidecar, and in some cases it will run automatically with an integration (suchy as in Astro). +**Via UI Config:** +See [Configuration reference](/docs/reference/configuration/#sidecar) for UI-side configuration. + +## Running the Sidecar + +Choose the method that fits your workflow: + + + + + + + + + +### Quick Start Options + +**Standalone Server:** +```bash +# Using CLI +spotlight-sidecar server + +# Using npx +npx @spotlightjs/sidecar +``` + +**With Your Application:** +```bash +# Run your app with Spotlight +spotlight-sidecar run npm run dev +``` + +**For MCP Integration:** +```bash +# Start with MCP support +spotlight-sidecar mcp +``` + +## Architecture + +### Communication Flow + +1. **Your Application** sends telemetry to the sidecar via HTTP POST +2. **Sidecar** validates, stores, and broadcasts events +3. **UI Clients** receive events via SSE connections +4. **MCP Clients** query events via stdio protocol + +### Multiple Clients + +A single sidecar instance can serve multiple clients simultaneously: + +- **Browser-based UI** - View in any web browser +- **Desktop app** - Dedicated application window +- **MCP clients** - AI assistants (Cursor, Claude, etc.) +- **Multiple apps** - Different services sending to the same sidecar + +All clients receive the same events in real-time. + +### Data Persistence + +Events are stored **in memory only** by design: + +**Benefits:** +- ✅ Fast access and streaming +- ✅ No disk I/O overhead +- ✅ Automatic cleanup on restart + +**Trade-off:** +- ⚠️ Events are lost when sidecar stops + +This is intentional - Spotlight is for **active development**, not long-term storage. + +## SDK Integration + +Your application sends events to the sidecar via Sentry SDKs. + +### Quick Setup + +Most SDKs support automatic detection via environment variable: + +```bash +export SENTRY_SPOTLIGHT=1 +# or specify custom URL +export SENTRY_SPOTLIGHT=http://localhost:8969/stream +``` + +**Or configure explicitly:** + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + + + + ```javascript + import * as Sentry from '@sentry/node'; + + Sentry.init({ + spotlight: process.env.NODE_ENV === 'development', + // or explicitly: + // spotlight: "http://localhost:8969/stream" + }); + ``` + + + ```python + import sentry_sdk + + sentry_sdk.init( + spotlight=True, # Uses SENTRY_SPOTLIGHT env var + # or explicitly: + # spotlight="http://localhost:8969/stream" + ) + ``` + + + ```javascript + import * as Sentry from '@sentry/browser'; + + Sentry.init({ + integrations: [Sentry.spotlightBrowserIntegration()], + }); + ``` + + + +## Use Cases + +### Local Development + +Run the sidecar alongside your development server to see errors and traces as you code. + +### Integration Testing + +Start the sidecar during tests to capture and analyze test failures with full context. + +### Mobile Development + +Point your mobile app to your machine's sidecar to debug on real devices: +``` +spotlight: "http://192.168.1.100:8969/stream" +``` + +### Microservices + +Run one sidecar and point all your services to it for unified debugging across your stack. + +## When to Use Each Method + +### Use CLI When: +- You want simple command-line control +- You need to wrap your application +- You want to stream events to terminal + +[Learn more about CLI →](/docs/cli/) + +### Use NPX When: +- You want the quickest setup +- You don't need the CLI features +- You just want the sidecar running + +[Learn more about NPX →](/docs/sidecar/npx/) + +### Use Webpack Plugin When: +- You're using webpack +- You want automatic sidecar lifecycle management +- You want sidecar to start/stop with your build + +[Learn more about Webpack →](/docs/sidecar/webpack/) + +### Use Docker When: +- You're containerizing your dev environment +- You need isolation from your host system +- You're deploying to a remote dev server + +[Learn more about Docker →](/docs/sidecar/docker/) + +### Use Desktop App When: +- You want a GUI experience +- You prefer desktop applications +- You're developing mobile or headless apps + +[Learn more about Desktop App →](/docs/desktop-app/) + +## Next Steps - - - +- [Learn about CLI commands](/docs/cli/) - Control sidecar via terminal +- [MCP Integration](/docs/mcp/) - Connect to AI assistants +- [Configuration reference](/docs/reference/configuration/) - Advanced settings