Skip to content
Merged
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/content/docs/exit-codes.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ react to failure categories without parsing stderr.
| 50 | Upgrade Error | CLI upgrade operation failed |
| 51 | Device Flow Error | OAuth device authorization flow failed |
| 60 | Output Error | Command produced output but the operation failed |
| 64 | Verify Failed | `sentry local run --verify` received no events from the SDK |
| 64 | Verify Failed | `sentry local run --verify` received no matching events from the SDK |
| 124 | Run Timeout | `sentry local run --timeout` stopped the app (the GNU `timeout` convention) |
| 252 | Invalid Argument | An argument could not be parsed — see [Argument errors](#argument-errors) |

Expand Down
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 @@ -52,7 +52,7 @@ When `local run` sees `wrangler dev` and a `wrangler.json`, `wrangler.jsonc`, or

### Check your setup with `--verify`

`sentry local run --verify -- <command>` starts your app, waits for its first event, then stops it. It exits 0 once an event arrives. It fails if the app exits, crashes, or sends nothing within the timeout (30 seconds, or `--timeout <seconds>`). When port 8969 is busy, it verifies on a free port.
`sentry local run --verify -- <command>` starts your app, waits for its first event, then stops it. It exits 0 once the SDK sends telemetry: any item other than a session or client report or, with `--filter`, an item that `--filter` would show in the tail. It fails if the app exits, crashes, or sends nothing within the timeout (30 seconds, or `--timeout <seconds>`). When port 8969 is busy, it verifies on a free port.

A Cloudflare Worker sends nothing until it handles a request, so send one to it while `--verify` waits.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,7 @@ Run a command with the local dev server enabled
- `-p, --port <value> - Port for the local server (default: 8969)`
- `--host <value> - Hostname for the local server - (default: "localhost")`
- `-f, --filter <value>... - Only show items of this type (repeatable: error, transaction, log, ai)`
- `-V, --verify - Verify SDK sends events, then exit`
- `-V, --verify - Wait for the app's first event (of the --filter types, if set), then exit`
- `-t, --timeout <value> - Stop the child after N seconds and exit 124 (0 = no timeout; defaults to 30 s in --verify mode, which exits 64) - (default: "0")`
- `-F, --format <value> - Output format: human (default) or json (NDJSON on stdout) - (default: "human")`
- `-a, --attributes - Also show SDK attributes, under each transaction, span and log or in JSON`
Expand Down
46 changes: 42 additions & 4 deletions packages/cli/src/commands/local/run.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,10 +52,12 @@ import {
type FilterValue,
FORMAT_VALUES,
createReplayTracker,
envelopeHasTelemetry,
formatEnvelopeLines,
formatEnvelopeLinesJson,
type FormatValue,
printLocalViewerHint,
sanitize,
} from "../../lib/formatters/local.js";
import { logger, printJsonLine, printLine } from "../../lib/logger.js";
import { spawnFailureError } from "../../lib/spawn-failure.js";
Expand Down Expand Up @@ -587,7 +589,8 @@ export const runCommand = buildCommand({
},
verify: {
kind: "boolean",
brief: "Verify SDK sends events, then exit",
brief:
"Wait for the app's first event (of the --filter types, if set), then exit",
default: false,
},
timeout: {
Expand Down Expand Up @@ -1054,12 +1057,35 @@ async function* runWithVerify(

const spotlightUrl = `${url}/stream`;

// Only telemetry the active filters show counts: an SDK sends sessions and
// client reports even when nothing else reaches Sentry Local. Remember what
// did arrive, so a timeout can say the SDK connected.
const activeFilters = new Set(flags.filter);
const uncountedTypes = new Set<string>();
let subscriptionId: string | undefined;
const envelopeReceived = new Promise<void>((resolveEnvelope) => {
subscriptionId = buffer.subscribe(() => {
resolveEnvelope();
subscriptionId = buffer.subscribe((container) => {
if (envelopeHasTelemetry(container, activeFilters)) {
resolveEnvelope();
return;
}
for (const [{ type }] of container.getParsedEnvelope()?.envelope[1] ??
[]) {
// Item types are untrusted input that ends up in the terminal.
const safeType = type ? sanitize(type).trim() : "";
if (safeType) {
uncountedTypes.add(safeType);
}
}
});
});
const connectedNote = (): string | undefined => {
if (uncountedTypes.size === 0) {
return;
}
const filters = [...activeFilters].map((f) => `-f ${f}`).join(" ");
return `the SDK connected but sent only ${[...uncountedTypes].join(", ")}${filters ? ` (nothing matching ${filters})` : ""}`;
Comment thread
sentry-junior[bot] marked this conversation as resolved.
Resolved
};

const childEnv = buildChildEnv(spotlightUrl, commandSource, cwd);
const wrangler = await injectWranglerSpotlightBinding(
Expand Down Expand Up @@ -1190,6 +1216,13 @@ async function* runWithVerify(
return;
}
case "timeout": {
const connected = connectedNote();
if (connected) {
// The SDK reached this receiver, so the DSN and port hints don't apply.
throw new VerifyFailedError(
`Verification timed out after ${verifyTimeout}s: ${connected}`,
);
}
if (wrangler.injected) {
logger.warn(
`A Worker sends nothing until it handles a request, so send one to it while --verify waits. ${wranglerSetupHint()}`,
Expand All @@ -1216,7 +1249,12 @@ async function* runWithVerify(
throw spawnFailureError(wrangler.args[0] ?? "", spawnError, cwd);
}
if (outcome.code === 0) {
throw new VerifyFailedError("Process exited before sending any events");
const connected = connectedNote();
throw new VerifyFailedError(
connected
? `Process exited before verifying: ${connected}`
: "Process exited before sending any events",
);
}
throw new VerifyFailedError(
`Process crashed with code ${outcome.code}`,
Expand Down
32 changes: 32 additions & 0 deletions packages/cli/src/lib/formatters/local.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1525,6 +1525,38 @@ function transactionHasAiActivity(payload: Record<string, unknown>): boolean {
return false;
}

/**
* Housekeeping item types an SDK sends on its own, even when nothing else
* reaches Sentry Local. Every other type counts as telemetry, so item types
* that SDKs add later count without a change here.
*/
const NOT_TELEMETRY_ITEM_TYPES = new Set([
"session",
"sessions",
"client_report",
]);

/**
* Whether an envelope shows the app is set up: it holds an item the active
* filters let through, or, with no filters, any item that is not
* housekeeping.
*/
export function envelopeHasTelemetry(
container: {
getParsedEnvelope: () => {
envelope: [Record<string, unknown>, [{ type?: string }, unknown][]];
} | null;
},
activeFilters: ReadonlySet<FilterValue>,
): boolean {
const items = container.getParsedEnvelope()?.envelope[1] ?? [];
return items.some(([{ type }, payload]) =>
activeFilters.size > 0
? isItemIncluded(type, activeFilters, payload as Record<string, unknown>)
: type !== undefined && !NOT_TELEMETRY_ITEM_TYPES.has(type),
);
}

/**
* Format a freshly received envelope as NDJSON lines.
*
Expand Down
117 changes: 117 additions & 0 deletions packages/cli/test/commands/local/run.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1310,6 +1310,19 @@ const SEND_ONE_EVENT = [
].join(" "),
];

/**
* Node `-e` args for an app that posts one envelope per item type, in order,
* then stays up (or exits 0 with `thenExit`).
*/
function sendItems(types: string[], thenExit = false): string[] {
return [
"-e",
`const id = "b".repeat(32);
const send = (type) => fetch(process.env.SENTRY_SPOTLIGHT, { method: "POST", headers: { "content-type": "application/x-sentry-envelope" }, body: [JSON.stringify({ event_id: id }), JSON.stringify({ type }), JSON.stringify({ event_id: id, type, message: "verify me" })].join(String.fromCharCode(10)) });
(async () => { for (const type of ${JSON.stringify(types)}) await send(type); ${thenExit ? "process.exit(0);" : "setTimeout(() => {}, 30000);"} })();`,
];
}

/** Hold `port` on `host`; resolves undefined when something already holds it. */
async function holdPort(
port: number,
Expand Down Expand Up @@ -1384,6 +1397,110 @@ describe("sentry local run --verify receiver", () => {
}
});

test.each([
{
sent: ["session", "client_report"],
filter: [],
message:
"Verification timed out after 2s: the SDK connected but sent only session, client_report",
},
{
sent: ["transaction", "log"],
filter: ["error" as const],
message:
"Verification timed out after 2s: the SDK connected but sent only transaction, log (nothing matching -f error)",
},
])(
"times out when only $sent arrive (filter: $filter)",
async ({ sent, filter, message }) => {
const warn = vi.spyOn(logger, "warn").mockImplementation(() => {});
try {
const func = (await runCommand.loader()) as unknown as RunFunc;
const error = await func
.call(
makeContext(),
{ port: 0, host: "127.0.0.1", verify: true, timeout: 2, filter },
process.execPath,
...sendItems(sent),
)
.catch((err: unknown) => err);
expect(error).toBeInstanceOf(VerifyFailedError);
expect((error as CliError).message).toBe(message);
expect((error as CliError).exitCode).toBe(64);
// The SDK reached the receiver, so the DSN hint would mislead.
expect(
warn.mock.calls.map((c) => String(c[0])).join("\n"),
).not.toContain("SENTRY_DSN");
} finally {
warn.mockRestore();
}
},
);

test("strips terminal escapes and line breaks from item types in the error", async () => {
const func = (await runCommand.loader()) as unknown as RunFunc;
const error = await func
.call(
makeContext(),
{
port: 0,
host: "127.0.0.1",
verify: true,
timeout: 2,
filter: ["error" as const],
},
process.execPath,
...sendItems(["\u001b[31mevil\u001b[0m\nError: forged \u202eline"]),
)
.catch((err: unknown) => err);
expect(error).toBeInstanceOf(VerifyFailedError);
expect((error as CliError).message).toBe(
"Verification timed out after 2s: the SDK connected but sent only evil Error: forged line (nothing matching -f error)",
);
});

test("says the SDK connected when the app exits after only a session", async () => {
const func = (await runCommand.loader()) as unknown as RunFunc;
const error = await func
.call(
makeContext(),
{ port: 0, host: "127.0.0.1", verify: true, timeout: 20, filter: [] },
process.execPath,
...sendItems(["session"], true),
)
.catch((err: unknown) => err);
expect(error).toBeInstanceOf(VerifyFailedError);
expect((error as CliError).message).toBe(
"Process exited before verifying: the SDK connected but sent only session",
);
expect((error as CliError).exitCode).toBe(64);
});

test.each([
{ sent: ["session", "log"], filter: [] },
{ sent: ["session", "check_in"], filter: [] },
{ sent: ["transaction", "event"], filter: ["error" as const] },
])(
"verifies once $sent arrive (filter: $filter)",
async ({ sent, filter }) => {
const info = vi.spyOn(logger, "info").mockImplementation(() => {});
try {
const func = (await runCommand.loader()) as unknown as RunFunc;
await func.call(
makeContext(),
{ port: 0, host: "127.0.0.1", verify: true, timeout: 20, filter },
process.execPath,
...sendItems(sent),
);
expect(info.mock.calls.map((c) => String(c[0]))).toContain(
"Setup verified — your app is sending events to Sentry Local",
);
} finally {
info.mockRestore();
}
},
);

test("verifies on a free port when the default port is busy", async () => {
const busy = makeDefaultPortBusy();
const warn = vi.spyOn(logger, "warn").mockImplementation(() => {});
Expand Down
66 changes: 66 additions & 0 deletions packages/cli/test/lib/formatters/local.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
import { describe, expect, test } from "vitest";
import type { FilterValue } from "../../../src/lib/formatters/local.js";
import {
envelopeHasTelemetry,
extractTraceId,
formatAttributeTable,
formatErrorItem,
Expand Down Expand Up @@ -1497,3 +1498,68 @@ describe("sentry-python ISO 8601 timestamps", () => {
);
});
});

describe("envelopeHasTelemetry", () => {
const envelope = (...items: [string, unknown][]) => ({
getParsedEnvelope: () => ({
envelope: [{}, items.map(([type, payload]) => [{ type }, payload])] as [
Record<string, unknown>,
[{ type?: string }, unknown][],
],
}),
});
const emptyLogBatch: [string, unknown] = ["log", { items: [] }];

test.each<{
items: [string, unknown][];
filters: FilterValue[];
counts: boolean;
}>([
{ items: [["session", {}]], filters: [], counts: false },
{ items: [["sessions", {}]], filters: [], counts: false },
{ items: [["client_report", {}]], filters: [], counts: false },
{
items: [
["session", {}],
["client_report", {}],
],
filters: [],
counts: false,
},
{ items: [["event", {}]], filters: [], counts: true },
{ items: [["check_in", {}]], filters: [], counts: true },
{ items: [["feedback", {}]], filters: [], counts: true },
{ items: [["trace_metric", {}]], filters: [], counts: true },
{ items: [["profile_chunk", {}]], filters: [], counts: true },
{
items: [
["session", {}],
["transaction", {}],
],
filters: [],
counts: true,
},
{ items: [emptyLogBatch], filters: [], counts: true },
{ items: [emptyLogBatch], filters: ["log"], counts: true },
{ items: [emptyLogBatch], filters: ["error"], counts: false },
{ items: [["transaction", {}]], filters: ["error"], counts: false },
{ items: [["session", {}]], filters: ["error"], counts: false },
{ items: [["event", {}]], filters: ["error"], counts: true },
{ items: [["check_in", {}]], filters: ["transaction"], counts: false },
{ items: [["span", {}]], filters: ["transaction"], counts: true },
{ items: [["transaction", {}]], filters: ["ai"], counts: false },
])(
"$items with filters $filters counts: $counts",
({ items, filters, counts }) => {
expect(envelopeHasTelemetry(envelope(...items), new Set(filters))).toBe(
counts,
);
},
);

test("an unparseable envelope does not count", () => {
expect(
envelopeHasTelemetry({ getParsedEnvelope: () => null }, new Set()),
).toBe(false);
});
});
Loading