Spotlight Run

The run command wraps your application with Spotlight, automatically setting up the necessary environment variables and capturing telemetry data.

Basic Usage

spotlight run [options] [command]

Key points:

• If you don’t provide a command, Spotlight automatically detects Docker Compose projects or runs your development script from package.json (prompts you to choose if both are found)
• 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

# 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:

{
  "scripts": {
    "dev": "node server.js",
    "dev:spotlight": "spotlight run"
  }
}

Auto-Detection with Docker Compose

Spotlight also automatically detects Docker Compose projects. When you run spotlight run without a command, it checks:

1. COMPOSE_FILE environment variable - If set, Spotlight uses the compose file(s) specified there
2. Compose files in the current directory - Otherwise, it looks for:
   • docker-compose.yml
   • docker-compose.yaml
   • compose.yml
   • compose.yaml

It also automatically includes override files (e.g., docker-compose.override.yml) when detecting files in the current directory.

# In a directory with docker-compose.yml
spotlight run
# ✓ Automatically runs: docker compose up (with Spotlight injection)

What Spotlight Does for Docker Compose

When a Docker Compose project is detected, Spotlight:

1. Uses host.docker.internal instead of localhost so containers can reach Spotlight running on your host machine
2. Injects environment variables into all services:
   • SENTRY_SPOTLIGHT
   • NEXT_PUBLIC_SENTRY_SPOTLIGHT
   • SENTRY_TRACES_SAMPLE_RATE
3. Adds extra_hosts mapping for Linux compatibility (host.docker.internal:host-gateway)

Requirements

Docker Compose auto-detection requires Docker version 20.10.0 or higher for host.docker.internal support on Linux.

When Both Are Detected

If Spotlight finds both a Docker Compose file and a package.json with runnable scripts, it will prompt you to choose which one to use:

spotlight run
# ⚠️  Both Docker Compose and package.json detected!
#
# Which would you like to use?
#   1) docker compose
#   2) package.json
# Enter your choice (1 or 2):

Non-Interactive Mode

In non-interactive environments (like CI/CD pipelines), Spotlight will exit with an error if both are detected. Specify a command explicitly to avoid this:

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

Running Specific Commands

You can run any command with Spotlight:

spotlight run [your-command]

Examples:

# 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:<port>/stream (or http://host.docker.internal:<port>/stream for Docker Compose)
   • 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!

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.

# 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:

spotlight run -d node server.js
# or
spotlight run --debug python app.py

Complete Examples

Full Development Workflow

# 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

# 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

# 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:

Node.js

// 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:

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:

Sentry.init({
  dsn: "http://spotlight@localhost:8969/0",
});

Local Development Only

This DSN is only for local development with Spotlight. Make sure to use your real Sentry DSN in production:

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:

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

spotlight run -d node server.js

Port Already in Use

If port 8969 is already taken:

# 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
• See all CLI options