diff --git a/packages/sidecar/src/cli/help.ts b/packages/sidecar/src/cli/help.ts index 271a9c197..371f30514 100644 --- a/packages/sidecar/src/cli/help.ts +++ b/packages/sidecar/src/cli/help.ts @@ -5,7 +5,7 @@ export default function showHelp() { console.log(` Spotlight Sidecar - Development proxy server for Spotlight -Usage: spotlight-sidecar [command] [options] +Usage: spotlight [command] [options] Commands: tail [types...] Tail Sentry events (default: everything) @@ -17,19 +17,19 @@ Commands: Options: -p, --port Port to listen on (default: 8969, or 0 for random) -d, --debug Enable debug logging - -f, --format Output format for tail command (default: logfmt) + -f, --format Output format for tail command (default: human) Available formats: ${[...AVAILABLE_FORMATTERS].join(", ")} -h, --help Show this help message Examples: - spotlight-sidecar # Start on default port 8969 - spotlight-sidecar tail # Tail all event types (logfmt format) - spotlight-sidecar tail errors # Tail only errors - spotlight-sidecar tail errors logs # Tail errors and logs - spotlight-sidecar tail --format logfmt # Explicitly use logfmt format - spotlight-sidecar mcp # Start in MCP mode - spotlight-sidecar --port 3000 # Start on port 3000 - spotlight-sidecar -p 3000 -d # Start on port 3000 with debug logging + spotlight # Start on default port 8969 + spotlight tail # Tail all event types (human format) + spotlight tail errors # Tail only errors + spotlight tail errors logs # Tail errors and logs + spotlight tail --format json # Explicitly use json format + spotlight mcp # Start in MCP mode + spotlight --port 3000 # Start on port 3000 + spotlight -p 3000 -d # Start on port 3000 with debug logging `); process.exit(0); } diff --git a/packages/website/src/content/docs/docs/architecture.mdx b/packages/website/src/content/docs/docs/architecture.mdx index 55249167e..8cfaa6492 100644 --- a/packages/website/src/content/docs/docs/architecture.mdx +++ b/packages/website/src/content/docs/docs/architecture.mdx @@ -11,31 +11,41 @@ import Architecture from "../../../../public/images/simple-event-flow.png"; At a high level, Spotlight consists of two components: -1. An overlay (`@spotlightjs/overlay`) that renders inside of your application. The overlay is a simple React application, and can - seamlessly run in any web application (or even independently!). +1. A standalone UI (`@spotlightjs/overlay`) that runs independently in your browser or as a desktop application. The UI is a React application that displays your application's telemetry data in real-time. -2. A proxy server (`@spotlightjs/sidecar`) which enables push-based communication to the overlay. This is achieved via a simple HTTP relay, - allowing SDKs to push events to it, and allowing the overlay to receive events using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events). +2. A proxy server (`@spotlightjs/sidecar`) which receives telemetry from your application and streams it to the UI. This is achieved via a simple HTTP relay, allowing SDKs to push events to it, and allowing the UI to receive events using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events). -For convenience, these packages are combined in a single package (`@spotlightjs/spotlight`), which is the recommended way to use Spotlight. -This means that adoption in most projects is as simple as adding a single dependency: +For convenience, these packages are combined in a single package (`@spotlightjs/spotlight`), which is the recommended way to run Spotlight. +This means that adoption in most projects is as simple as: ```shell -npm add @spotlightjs/spotlight +# Run the Spotlight sidecar with UI +npx @spotlightjs/spotlight + +# Or install globally +npm install -g @spotlightjs/spotlight +spotlight ``` -Registering Spotlight in your frontend application: +Enabling Spotlight in your application's SDK: ```typescript -import * as Spotlight from '@spotlightjs/spotlight'; +import * as Sentry from '@sentry/node'; + +// Enable Spotlight for development +Sentry.init({ + dsn: 'your-dsn', + spotlight: process.env.NODE_ENV === 'development', +}); +``` -// only load Spotlight in dev -if (process.env.NODE_ENV === "development") { - Spotlight.init(); -} +Or simply set the environment variable: + +```shell +export SENTRY_SPOTLIGHT=1 ``` -You can send any kind of events to the Sidecar, it forwards it to Spotlight and the integrations within Spotlight need to understand what to do with it. +You can send any kind of events to the Sidecar, it forwards them to the Spotlight UI where integrations process and display the data. diff --git a/packages/website/src/content/docs/docs/cli/run.mdx b/packages/website/src/content/docs/docs/cli/run.mdx index 4e7ddf644..ca451bd99 100644 --- a/packages/website/src/content/docs/docs/cli/run.mdx +++ b/packages/website/src/content/docs/docs/cli/run.mdx @@ -273,5 +273,4 @@ spotlight run -p 0 node server.js - [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/mcp/index.mdx b/packages/website/src/content/docs/docs/mcp/index.mdx index 206b38972..90e490e2d 100644 --- a/packages/website/src/content/docs/docs/mcp/index.mdx +++ b/packages/website/src/content/docs/docs/mcp/index.mdx @@ -187,7 +187,7 @@ Get detailed span tree and timing for a specific trace. If you need to run Spotlight on a different port: ```bash -spotlight-sidecar mcp -p 3000 +spotlight mcp -p 3000 ``` Update your MCP client configuration to match: @@ -208,7 +208,7 @@ Update your MCP client configuration to match: Enable debug logging to troubleshoot MCP connection issues: ```bash -spotlight-sidecar mcp -d +spotlight mcp -d ``` ## How It Works @@ -279,12 +279,12 @@ Here's a typical debugging session with Spotlight MCP: 1. **Start Spotlight MCP Server** ```bash - spotlight-sidecar mcp + spotlight mcp ``` 2. **Run Your Application** ```bash - spotlight-sidecar run npm run dev + spotlight run npm run dev ``` 3. **Trigger an Error** in your application (e.g., click a button, make a request) @@ -327,10 +327,10 @@ Check that the port isn't already in use: ```bash # Use a different port -spotlight-sidecar mcp -p 3000 +spotlight mcp -p 3000 # Enable debug logging -spotlight-sidecar mcp -d +spotlight mcp -d ``` ### AI Assistant Not Seeing Tools @@ -347,16 +347,6 @@ spotlight-sidecar mcp -d 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/) diff --git a/packages/website/src/content/docs/docs/reference/configuration.md b/packages/website/src/content/docs/docs/reference/configuration.md deleted file mode 100644 index f5e174551..000000000 --- a/packages/website/src/content/docs/docs/reference/configuration.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: Configuration -description: All the configuration options for setting up Spotlight ---- - -## `init` - -To initialize spotlight in your app using following configuration options: - -#### `integrations` - -**type:** [`SpotlightIntegration[]`](#spotlightintegration) - -Defines which integrations should be loaded for Spotlight. Defaults to `[sentry()]`. - -```js -import { init, sentry } as Spotlight from '@spotlightjs/spotlight'; - -init({ - integrations: [sentry()], -}); -``` - -#### `debug` - -**type:** `boolean` **default:** `false` - -Enables some debug output in console for debugging. - -```ts -init({ - debug: true, -}); -``` - -#### `sidecarUrl` - -**type:** `string` **default:** `"http://localhost:8969/stream"` - -The Sidecar event-source stream endpoint URL. - -Set this option if you have the sidecar running on another URL than the default one. - -```ts -init({ - sidecarUrl: 'http://localhost:8969/stream', -}); -``` - -#### `anchor` - -**type:** [`AnchorConfig`](#anchorconfig) - -The anchor position for the toolbar. - -```ts -init({ - anchor: 'centerRight', -}); -``` - -#### `experiments` - -**type:** [`ExperimentsConfig`](#experimentsconfig) - -Experimental configuration. - -```ts -init({ - experiments: { - 'sentry:focus-local-events': false, - }, -}); -``` - -#### `AnchorConfig` - -```ts -type AnchorConfig = 'bottomRight' | 'bottomLeft' | 'centerRight' | 'centerLeft' | 'topLeft' | 'topRight'; -``` - -#### `ExperimentsConfig` - -```ts -type ExperimentsConfig = Record; -``` - -Experiment names are: - -- `sentry:focus-local-events` - if set to true, errors and traces will hide events from other sessions when possible. - -#### `injectImmediately` - -**type:** `boolean` **default:** `false` - -By default, Spotlight waits until the host page is loaded before injecting the Spotlight Overlay. Depending on how and -when the `init` call is made, the `load` event might have already happened. - -By setting `injectImmediately` to `true`, the UI will be injected synchronously with the `init` call. - -Use this option, if you called `init()` but the Spotlight Overlay UI is not visible. - -```ts -init({ - injectImmediately: true, -}); -``` - -#### `openOnInit` - -**type:** `boolean` **default:** `false` - -If set to `true`, the Spotlight overlay Window will be opened immediately after calling the init function. By default, -only the button is visible. - -```ts -init({ - openOnInit: true, -}); -``` - -#### `fullPage` - -**type:** `boolean` **default:** `false` - -If set to `true`, the Spotlight overlay will be rendered directly in the HTML as a relative `
`. It's helpful and -goes well with `injectImmediately`. It's used for rendering a blocking page like an error page or dedicated HTML. Also -the ability for closing the overlay is disabled when this is avitce. - -```ts -init({ - fullPage: true, -}); -``` - -#### `showClearEventsButton` - -**type:** `boolean` **default:** `true` - -If set to `true`, the Spotlight overlay will have a clear events button on top. On clicking the button, all events -processed from sidecar will be removed. - -```ts -init({ - showClearEventsButton: true, -}); -``` - -## `trigger` - -Trigger an event within Spotlight. - -```js -import { trigger } from '@spotlightjs/spotlight'; - -trigger('sentry:showError', { - event: string, - eventId: string, -}); -``` - -```ts -type TriggerFunction = (eventName: string, eventPayload?: unknown) -``` - -## `SpotlightIntegration` - -```ts -// TODO -type SpotlightIntegration = {}; -``` diff --git a/packages/website/src/content/docs/docs/sidecar/index.mdx b/packages/website/src/content/docs/docs/sidecar/index.mdx index 625d71ed5..a93fc9c15 100644 --- a/packages/website/src/content/docs/docs/sidecar/index.mdx +++ b/packages/website/src/content/docs/docs/sidecar/index.mdx @@ -82,15 +82,12 @@ sentry_sdk.init( ) ``` -**Via UI Config:** -See [Configuration reference](/docs/reference/configuration/#sidecar) for UI-side configuration. - ## Running the Sidecar Choose the method that fits your workflow: - + @@ -102,22 +99,22 @@ Choose the method that fits your workflow: **Standalone Server:** ```bash # Using CLI -spotlight-sidecar server +spotlight server # Using npx -npx @spotlightjs/sidecar +npx @spotlightjs/spotlight ``` **With Your Application:** ```bash # Run your app with Spotlight -spotlight-sidecar run npm run dev +spotlight run npm run dev ``` **For MCP Integration:** ```bash # Start with MCP support -spotlight-sidecar mcp +spotlight mcp ``` ## Architecture @@ -268,4 +265,3 @@ Run one sidecar and point all your services to it for unified debugging across y - [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 diff --git a/packages/website/src/content/docs/docs/sidecar/webpack.mdx b/packages/website/src/content/docs/docs/sidecar/webpack.mdx index 9c0e2eacc..bce5107f2 100644 --- a/packages/website/src/content/docs/docs/sidecar/webpack.mdx +++ b/packages/website/src/content/docs/docs/sidecar/webpack.mdx @@ -30,9 +30,9 @@ module.exports = { plugins: [ new WebpackHookPlugin({ onBuildStart: ['npx @spotlightjs/spotlight'], - // Or you package manager of you choice e.g. yarn run spotlight-sidecar + // Or you package manager of your choice e.g. yarn run spotlight }), ], }; -``` \ No newline at end of file +```