Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion apps/cli-docs/src/fragments/commands/local.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <name>` 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 <name>` 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:

Expand Down
38 changes: 27 additions & 11 deletions packages/cli/src/commands/local/run.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand All @@ -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) {
Expand All @@ -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 <name> to capture into the daemon instead.`,
);
listenPort = 0;
heldByDaemon = true;
}

if (running) {
Expand All @@ -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 <name> to capture into the daemon instead.`,
);
}
logger.info(`Background server listening on ${bold(bg.url)}`);
return bg;
} catch (err) {
Expand Down Expand Up @@ -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 };
}
}
Expand Down Expand Up @@ -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`,
Expand Down
11 changes: 7 additions & 4 deletions packages/cli/test/commands/local/run.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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();
}
Expand Down Expand Up @@ -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 <name> 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 <name> to capture into the daemon instead.`,
);
} finally {
info.mockRestore();
Expand Down
Loading