diff --git a/apps/cli-docs/src/fragments/commands/local.md b/apps/cli-docs/src/fragments/commands/local.md index 9db9ec7ab..44fde7191 100644 --- a/apps/cli-docs/src/fragments/commands/local.md +++ b/apps/cli-docs/src/fragments/commands/local.md @@ -12,7 +12,7 @@ Runs a command with `SENTRY_SPOTLIGHT` set to the local server's URL. Node.js an If nothing is listening on the port, a server is started in the background and shut down when your command exits. If something already is — the Spotlight desktop app's own sidecar, or a `sentry local serve` in another terminal — the command attaches to it as an SSE consumer, so events still tail to your terminal either way. -The Local daemon behind `--session` is the exception: it only takes session traffic. When it holds port 8969, a plain `local run` captures on a free port and says so. Add `--session ` to capture into the daemon instead. With an explicit `--port` that the daemon holds, the command stops with an error. +The Local daemon behind `--session` is the exception: it only takes session traffic. When it holds port 8969, a plain `local run` captures on a free port and says so. An SDK that hard-codes 8969 won't reach that port, so make sure it reads `SENTRY_SPOTLIGHT`. Add `--session ` to capture into the daemon instead. With an explicit `--port` that the daemon holds, the command stops with an error. With no command, `local run` picks one from the project, in this order: diff --git a/packages/cli/src/commands/local/run.ts b/packages/cli/src/commands/local/run.ts index ba7bc1554..1c17f80e3 100644 --- a/packages/cli/src/commands/local/run.ts +++ b/packages/cli/src/commands/local/run.ts @@ -284,6 +284,22 @@ async function startBackgroundServer({ }; } +/** + * Say that this run listens on `boundPort` because `defaultPort` is taken. + * An SDK that hard-codes the default port sends there instead, and the + * daemon drops traffic that isn't for a session without a word, so the + * notice says to use SENTRY_SPOTLIGHT. + * + * @param reason - Why the default port is taken, e.g. "is in use" + */ +function freePortNotice( + defaultPort: number, + boundPort: number, + reason: string, +): string { + return `Port ${defaultPort} ${reason}, so this run listens on port ${boundPort} instead. SDKs that hard-code ${defaultPort} won't reach it; make sure they read SENTRY_SPOTLIGHT.`; +} + /** * Get a live event tail on `host:port`, whichever way is available. * @@ -303,7 +319,7 @@ async function openEventTail({ const url = formatLocalServerUrl(host, port); let running = false; - let listenPort = port; + let heldByDaemon = false; try { running = await isServerRunning(url); } catch (err) { @@ -318,10 +334,7 @@ async function openEventTail({ } // The daemon's receiver only takes session traffic, and it stays up while // it retains sessions, so a plain run gets its own receiver instead. - logger.info( - `The Local daemon is using port ${port}, so this run captures on a free port. Add --session to capture into the daemon instead.`, - ); - listenPort = 0; + heldByDaemon = true; } if (running) { @@ -335,18 +348,23 @@ async function openEventTail({ }); } - if (listenPort === port) { + if (!heldByDaemon) { logger.info("No server detected, starting one in the background..."); } try { const bg = await startBackgroundServer({ maxEnvelopes, - port: listenPort, + port: heldByDaemon ? 0 : port, host, activeFilters, useJson, showAttributes, }); + if (heldByDaemon) { + logger.info( + `${freePortNotice(port, Number(new URL(bg.url).port), "is held by the Local daemon")} Add --session to capture into the daemon instead.`, + ); + } logger.info(`Background server listening on ${bold(bg.url)}`); return bg; } catch (err) { @@ -902,8 +920,8 @@ async function listenForVerify( PORT_IN_USE_FIELD, ); } - logger.info(`Port ${DEFAULT_PORT} is in use; verifying on a free port`); const bound = await tryListen(app, 0, host, { retries: 0 }); + logger.info(freePortNotice(DEFAULT_PORT, bound.port, "is in use")); return { ...bound, fellBack: true }; } } @@ -1069,9 +1087,7 @@ async function* runWithVerify( if (fellBack) { // An SDK that ignores SENTRY_SPOTLIGHT still sends to the busy default // port, so it reaches whatever holds that port instead of this receiver. - logger.warn( - `Verify used port ${boundPort} because ${DEFAULT_PORT} was busy. Make sure your SDK reads SENTRY_SPOTLIGHT instead of a hard-coded port.`, - ); + logger.warn(freePortNotice(DEFAULT_PORT, boundPort, "is in use")); } throw new VerifyFailedError( `Verification timed out after ${verifyTimeout}s — no events received from the SDK`, diff --git a/packages/cli/test/commands/local/run.test.ts b/packages/cli/test/commands/local/run.test.ts index db27f0d34..3fa8c01e3 100644 --- a/packages/cli/test/commands/local/run.test.ts +++ b/packages/cli/test/commands/local/run.test.ts @@ -1115,6 +1115,7 @@ describe("sentry local run --verify receiver", () => { test("says which port it used when verify on a fallback port times out", async () => { const busy = makeDefaultPortBusy(); + const info = vi.spyOn(logger, "info").mockImplementation(() => {}); const warn = vi.spyOn(logger, "warn").mockImplementation(() => {}); const context = makeParsedRunContext(); try { @@ -1137,10 +1138,12 @@ describe("sentry local run --verify receiver", () => { ); expect(context.process.exitCode).toBe(EXIT.VERIFY_FAILED); const port = new URL(spawnCapture.env?.["SENTRY_SPOTLIGHT"] ?? "").port; - expect(warn).toHaveBeenCalledWith( - `Verify used port ${port} because ${DEFAULT_PORT} was busy. Make sure your SDK reads SENTRY_SPOTLIGHT instead of a hard-coded port.`, - ); + const notice = `Port ${DEFAULT_PORT} is in use, so this run listens on port ${port} instead. SDKs that hard-code ${DEFAULT_PORT} won't reach it; make sure they read SENTRY_SPOTLIGHT.`; + // Once when it binds, and again when nothing arrived. + expect(info).toHaveBeenCalledWith(notice); + expect(warn).toHaveBeenCalledWith(notice); } finally { + info.mockRestore(); warn.mockRestore(); busy.mockRestore(); } @@ -1223,7 +1226,7 @@ describe("sentry local run messages", () => { expect(Number(receiver.port)).not.toBe(DEFAULT_PORT); expect(Number(receiver.port)).toBeGreaterThan(0); expect(info).toHaveBeenCalledWith( - `The Local daemon is using port ${DEFAULT_PORT}, so this run captures on a free port. Add --session to capture into the daemon instead.`, + `Port ${DEFAULT_PORT} is held by the Local daemon, so this run listens on port ${receiver.port} instead. SDKs that hard-code ${DEFAULT_PORT} won't reach it; make sure they read SENTRY_SPOTLIGHT. Add --session to capture into the daemon instead.`, ); } finally { info.mockRestore();