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
10 changes: 8 additions & 2 deletions apps/cli-docs/src/fragments/commands/local.md
Original file line number Diff line number Diff line change
Expand Up @@ -281,8 +281,14 @@ same way without wrapping a command.

`sentry local session create <name> --json` returns separate SDK ingest and
viewer read capability URLs. Keep these URLs private. `--clientId <key>` makes
retried session creation idempotent. Use the session ID when multiple sessions
share a label.
retried session creation idempotent.

Each `local run --session` creates a new session, so names repeat. Commands
that read, such as `event list` and `session view`, use the name's newest open
session, or its newest session when none is open. When several open sessions
share the name, they use the newest and note the others on stderr. `session
close` and other commands that change a session refuse a name that several open
sessions share and list them, so pass the session ID instead.

How an SDK reaches a session depends on its Spotlight support:

Expand Down
4 changes: 4 additions & 0 deletions design/sentry-local.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,10 @@ account.
`sentry-local#stop-clears`).
- Each session or receiver keeps its most recent envelopes, 500 by default,
and a user can set the limit from 1 to 50,000.
- A session name reads from its newest open session, or its newest session
when none is open, because every `local run --session` creates a new one.
Close, reset, and retention changes refuse a name that several open sessions
share. A session ID always selects that session.
- A missing or evicted session, event, or envelope is a not-found error that
names what is missing and the list command to run
(`sentry-local#missing-session-exit`).
Expand Down
10 changes: 8 additions & 2 deletions docs/cli/local-control-plane.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,14 @@ Treat those URLs as credentials. Terminal output redacts them, including the
`Starting:` line of `local run --session`; the wrapped app still gets the real URL.
Use `--clientId <key>` to make session creation idempotent for retries. Once a
retained session expires, reusing its key creates a fresh session with new capabilities.
Names must be unique for name-based queries; ambiguous names return HTTP 409 with guidance
to use the session ID.
A session ID resolves to exactly that session. For reads, a name resolves to its newest
open session, or to its newest session when none is open. When several open sessions
share the name, read responses carry an `X-Sentry-Local-Session-Choice` header, JSON
with the chosen `id`, up to five `others` (each `id` and `createdAt`), and a `more`
count of the rest, and the CLI prints a one-line note to stderr. Close, reset, and
retention changes refuse such a name with HTTP 409 `ambiguous_session`. For control
clients it lists every match in `sessions` with its `id`, `state`, and `createdAt`;
capability-scoped requests get the code only. The CLI reports it as a user error. Daemons from older CLIs answered every shared-name lookup with that 409.
Session lookup commands accept names quoted or as separate words. For `event view` and
`envelope view`, the final argument is the telemetry ID; preceding arguments
form the session name. Event lookup uses the Sentry event ID from the envelope
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ List retained envelopes for a Local session

| Argument | Description |
|----------|-------------|
| `<session...>` | Session ID or unique name |
| `<session...>` | Session ID or name |

### `sentry local envelope view <session envelope...>`

Expand All @@ -60,7 +60,7 @@ List decoded events for a Local session

| Argument | Description |
|----------|-------------|
| `<session...>` | Session ID or unique name |
| `<session...>` | Session ID or name |

### `sentry local event view <session event...>`

Expand Down Expand Up @@ -139,7 +139,7 @@ View or change session envelope retention

| Argument | Description |
|----------|-------------|
| `<session...>` | Session ID or unique name |
| `<session...>` | Session ID or name |

**Flags:**
- `--max-envelopes <value> - Maximum envelopes retained by this receiver or session`
Expand All @@ -156,7 +156,7 @@ View a Local telemetry session

| Argument | Description |
|----------|-------------|
| `<session...>` | Session ID or unique name |
| `<session...>` | Session ID or name |

### `sentry local session close <session...>`

Expand All @@ -166,7 +166,7 @@ Close a Local telemetry session

| Argument | Description |
|----------|-------------|
| `<session...>` | Session ID or unique name |
| `<session...>` | Session ID or name |

### `sentry local session reset <session...>`

Expand All @@ -176,7 +176,7 @@ Clear a Local telemetry session

| Argument | Description |
|----------|-------------|
| `<session...>` | Session ID or unique name |
| `<session...>` | Session ID or name |

### `sentry local run <command...>`

Expand Down
Loading
Loading