@pydantic/logfire-session-replay 0.4.0 → 0.6.0

package/README.md

@@ -158,6 +158,14 @@ configured cadence. After five minutes without activity, background events use
 the greater of `flushIntervalMs` and five minutes. After the replay reaches its
 minimum duration, reaching `maxBufferBytes` still flushes immediately.
 
+Normal recording takes a full-DOM checkpoint on the first recorded incremental
+event after five minutes since the previous full snapshot. Each checkpoint
+starts a new upload chunk with its `Meta` and `FullSnapshot` pair. This does not
+change the upload cadence. Error-buffered recording retains its two-minute
+checkpoint interval. If `minSessionDurationMs` exceeds five minutes, normal
+recording uses that longer checkpoint interval so replacement snapshots cannot
+restart the minimum-duration gate before it completes.
+
 Replays must contain at least `minSessionDurationMs` of recorded events (10
 seconds by default) before they are uploaded. While waiting, events stay
 buffered. The initial `Meta` and `FullSnapshot` anchor is retained even when it
@@ -197,6 +205,46 @@ Security Policy blocks fflate's worker compressor, replay retries the same batch
 with synchronous gzip and remembers the fallback for that replay controller.
 This preserves the batch, but compression may briefly use the main thread.
 
+## Upload Failures
+
+Ordinary uploads wait in an in-memory queue and are sent in sequence order.
+Network errors, timeouts, `408`, `425`, `429`, and `5xx` responses are retried
+with the same sequence number and the same compressed bytes. The backoff starts
+at 500 ms, doubles up to 8 s, and uses jitter. Each chunk has a 30-second retry
+budget that includes the time of its requests. `Retry-After` on `429` and `503`
+can lengthen a wait, never shorten it, and is honored while it fits that budget.
+Other `4xx` responses are not retried. The receiver must accept a repeated
+`(sessionId, seq)` as the same chunk, because a retry can follow a request that
+the server stored but whose response was lost.
+
+The queue holds at most 2,000,000 bytes, or twice `maxBufferBytes` when that is
+larger. It counts uncompressed events until they are compressed, and compressed
+bodies afterwards. An empty queue always admits the next batch, even when that
+batch is larger than the limit, because an initial full snapshot can exceed it
+and must not be lost. Otherwise, a batch that does not fit is discarded without
+a sequence number, and the chunks already queued are still delivered.
+
+A lost chunk is reported to `onError` as a `ReplayUploadError`:
+
+- `reason`: `'unconfirmed'` when retries ran out after a request reached the
+  network (the server may still hold the chunk), `'rejected'` for a terminal
+  HTTP status, or `'not-sent'` when no request left the browser (full queue,
+  compression failure, or a failing `headers` or `token` callback).
+- `seq`: the lost chunk, or `undefined` for a batch the full queue rejected.
+- `droppedSeqs`: later chunks that were discarded without upload because they
+  depended on the lost one.
+- `status`, `sessionId`, and `cause`.
+
+After a loss, replay discards the events that depend on the missing DOM state
+and takes a fresh full snapshot, so playback resumes correctly after the gap.
+Chunks that already start from a later full snapshot are kept. Replay takes at
+most one of these recovery snapshots per minute.
+
+`stop()` gives each unsent chunk one last attempt and resolves within about 10
+seconds, even when uploads hang. The queue lives in memory only: chunks that are
+still queued when the page closes or reloads are lost, and a reloaded page does
+not retry them.
+
 ## Privacy
 
 The recorder masks all rendered text and input values by default
@@ -227,8 +275,8 @@ The recorder uses a Sentry-style two-rate model:
 
 - `sessionSampleRate`: records the current browser session continuously
 - `onErrorSampleRate`: for sessions not selected by `sessionSampleRate`, keeps
-  an in-memory replay buffer and promotes it only for an uncaught `window.error`
-  or `unhandledrejection`
+  an in-memory replay buffer and promotes it for an uncaught `window.error` or
+  `unhandledrejection`, or for an error passed to `captureError()`
 
 Buffer mode is bounded by `maxBufferBytes`, measured as the UTF-8 byte sum of
 event JSON before envelope metadata and compression. It keeps the latest full
@@ -244,8 +292,14 @@ properties. A sampled-off session keeps only a lightweight session-id monitor;
 it does not start rrweb or patch console, network, or navigation globals, and a
 later sampled session can begin recording without reloading the page.
 
-Caught exceptions, `console.error`, and errors reported through another API do
-not automatically promote the replay buffer.
+Pass a caught error to `replay.captureError(error)` to add it to the replay and
+promote the buffer, as an uncaught error does. For an error that occurred
+earlier, pass `{ timestamp }` in epoch milliseconds; the error event records it. An error object is added once,
+even when it is also uncaught later. `console.error` does not promote the buffer.
+
+Set `captureGlobalErrors: false` when another layer listens for uncaught errors
+and forwards them through `captureError()`. The replay then installs no `error`
+or `unhandledrejection` listeners.
 
 `stop()` is awaitable and flushes the final chunk before resolving.
 
@@ -277,7 +331,9 @@ logfire.configure({
 ```
 
 The browser package owns RUM session identity, span correlation attributes, and
-cleanup ordering. Call `startSessionReplay()` directly only for standalone or
+cleanup ordering. It also reports uncaught errors as spans and passes every
+`reportError()` call to `captureError()`, so a handled error that the
+application reports promotes an error-buffered replay. Call `startSessionReplay()` directly only for standalone or
 advanced integrations that do not use `@pydantic/logfire-browser`.
 
 ## Local Development Notes

package/dist/index-BxzwrVOz.d.cts

@@ -0,0 +1,220 @@
+//#region src/types.d.ts
+interface RrwebEvent {
+  type: number;
+  data: unknown;
+  timestamp: number;
+}
+declare const EventType: {
+  readonly DomContentLoaded: 0;
+  readonly Load: 1;
+  readonly FullSnapshot: 2;
+  readonly IncrementalSnapshot: 3;
+  readonly Meta: 4;
+  readonly Custom: 5;
+  readonly Plugin: 6;
+};
+declare const IncrementalSource: {
+  readonly Mutation: 0;
+  readonly MouseMove: 1;
+  readonly MouseInteraction: 2;
+  readonly Scroll: 3;
+  readonly ViewportResize: 4;
+  readonly Input: 5;
+  readonly TouchMove: 6;
+  readonly MediaInteraction: 7;
+  readonly Drag: 12;
+  readonly Selection: 14;
+};
+declare const MouseInteractions: {
+  readonly MouseUp: 0;
+  readonly MouseDown: 1;
+  readonly Click: 2;
+  readonly ContextMenu: 3;
+  readonly DblClick: 4;
+};
+declare const CustomTag: {
+  readonly Error: "logfire.error";
+  readonly Console: "logfire.console";
+  readonly Network: "logfire.network";
+  readonly Navigation: "logfire.navigation";
+};
+declare const CHUNK_ENVELOPE_VERSION: 1;
+type MaybePromise<T> = T | Promise<T>;
+type ConsoleLevel = "log" | "info" | "warn" | "error" | "debug";
+type SamplingMode = "full" | "buffer" | "off";
+type SessionAttributeValue = string | number | boolean;
+type SessionAttributesInput = Record<string, SessionAttributeValue | undefined>;
+type SessionAttributes = Record<string, SessionAttributeValue>;
+interface ConsolePayload {
+  level: ConsoleLevel;
+  args: string[];
+  source?: string;
+}
+interface NetworkPayload {
+  method: string;
+  url: string;
+  status: number;
+  durationMs: number;
+  failed?: boolean;
+  reqBytes?: number;
+  resBytes?: number;
+}
+interface NavigationPayload {
+  url: string;
+  kind: "push" | "replace" | "pop";
+}
+/** User identity reported by the application. Name and email are optional personal data. */
+interface ReplayUser {
+  id: string;
+  name?: string;
+  email?: string;
+}
+interface ChunkMeta {
+  seq: number;
+  firstTimestamp: number;
+  lastTimestamp: number;
+  eventCount: number;
+  clickCount: number;
+  keypressCount: number;
+  errorCount: number;
+  hasFullSnapshot: boolean;
+  urls: string[];
+  distinctId?: string;
+  user?: ReplayUser;
+  sessionAttributes?: SessionAttributes;
+}
+interface ChunkEnvelope {
+  version: typeof CHUNK_ENVELOPE_VERSION;
+  meta: ChunkMeta;
+  events: RrwebEvent[];
+}
+/**
+ * Early Access session replay recorder configuration. Keep browser replay
+ * rollout behind an application flag.
+ */
+interface SessionReplayConfig {
+  /**
+   * Browser-safe replay upload endpoint, either direct Logfire ingest with a
+   * restricted frontend application token or an application-owned proxy. The
+   * SDK posts to `${replayUrl}/${recordingId}?seq=${seq}`. A replay continues
+   * across same-tab reloads/navigations; a new tab gets a separate recording id.
+   */
+  replayUrl: string;
+  /**
+   * Headers added to each replay upload. Direct Logfire ingest uses the same
+   * restricted frontend application headers as traces and metrics.
+   */
+  headers?: () => MaybePromise<Record<string, string>>;
+  /**
+   * Convenience token source. A non-empty value removes any case-insensitive
+   * Authorization entry returned by `headers`, then sets
+   * `Authorization: Bearer ${token}`. Only restricted frontend application
+   * tokens are safe in browsers.
+   */
+  token?: string | (() => MaybePromise<string>);
+  /**
+   * Optional external session id source. The browser SDK integration should
+   * pass its RUM session id here. This controls sampling and session rotation;
+   * it is not used as the upload/playback id (see `getRecordingId()`).
+   */
+  getSessionId?: () => string | undefined;
+  /**
+   * Returns low-cardinality, non-PII dimensions to snapshot once per replay
+   * session. Invalid or oversized entries are omitted.
+   */
+  getSessionAttributes?: () => SessionAttributesInput;
+  /** Probability of recording each new browser session in full. */
+  sessionSampleRate?: number;
+  /** Probability of buffering each otherwise-unsampled session for uncaught error promotion. */
+  onErrorSampleRate?: number;
+  /** Mask all rendered DOM text. Defaults to true. */
+  maskAllText?: boolean;
+  maskAllInputs?: boolean;
+  maskTextSelector?: string;
+  blockSelector?: string;
+  /** Batching interval while the user is active. Defaults to 5 seconds. */
+  flushIntervalMs?: number;
+  maxBufferBytes?: number;
+  /** Minimum recording duration before a replay is uploaded. Defaults to 10 seconds. */
+  minSessionDurationMs?: number;
+  sessionIdleTimeoutMs?: number;
+  /** Maximum recording duration before the session ID rotates. Defaults to 2 hours. */
+  maxSessionDurationMs?: number;
+  distinctId?: string;
+  getDistinctId?: () => string | undefined;
+  /**
+   * Returns the current user, snapshotted for every chunk as `meta.user`. Only
+   * a non-empty `id`, `name` and `email` are kept; name and email are optional
+   * personal data. Without `getDistinctId`, the same snapshot's `id` becomes
+   * `meta.distinctId`.
+   */
+  getUser?: () => ReplayUser | undefined;
+  captureConsole?: boolean;
+  captureNetwork?: boolean;
+  captureNavigation?: boolean;
+  /**
+   * Listen for uncaught `error` and `unhandledrejection` events, add them to the replay, and
+   * promote an error-sampled buffer. Defaults to true. The browser SDK turns this off when it
+   * captures global errors itself and forwards them through `captureError()`.
+   */
+  captureGlobalErrors?: boolean;
+  ignoreUrlPatterns?: RegExp[];
+  redactUrlPatterns?: RegExp[];
+  onError?: (error: unknown) => void;
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+  random?: () => number;
+}
+//#endregion
+//#region src/uploadError.d.ts
+/**
+ * - `unconfirmed`: retries ended after a request reached the network; the server may hold the chunk.
+ * - `rejected`: the server answered with a terminal HTTP status.
+ * - `not-sent`: no request reached the network (queue full, compression, headers or token failed).
+ */
+type ReplayUploadFailureReason = "unconfirmed" | "rejected" | "not-sent";
+interface ReplayUploadErrorInit {
+  cause: unknown;
+  droppedSeqs?: readonly number[];
+  reason: ReplayUploadFailureReason;
+  seq: number | undefined;
+  sessionId: string;
+  status?: number | undefined;
+}
+/**
+ * Reported through `onError` when a replay chunk is not confirmed by the server.
+ * Recording continues from a fresh full snapshot, so `droppedSeqs` lists the
+ * later chunks that were discarded because they depended on the lost one.
+ */
+declare class ReplayUploadError extends Error {
+  readonly droppedSeqs: readonly number[];
+  readonly reason: ReplayUploadFailureReason;
+  readonly seq: number | undefined;
+  readonly sessionId: string;
+  readonly status: number | undefined;
+  constructor(init: ReplayUploadErrorInit);
+}
+//#endregion
+//#region src/index.d.ts
+interface SessionReplay {
+  readonly recording: boolean;
+  readonly mode: "full" | "buffer" | "off";
+  getSessionId(): string;
+  /**
+   * Add an error to the replay and promote an error-sampled buffer, as an uncaught error does.
+   * The same error object is added once, however many times it is captured. Pass the time the
+   * error occurred, in epoch milliseconds, when it is captured later; the error event records it
+   * as `timestamp`.
+   */
+  captureError(error: unknown, options?: CaptureErrorOptions): void;
+  /** The current DOM recording's upload/playback id; distinct from the RUM session id. */
+  getRecordingId(): string;
+  flush(): Promise<void>;
+  stop(): Promise<void>;
+}
+interface CaptureErrorOptions {
+  timestamp?: number;
+}
+declare function startSessionReplay(config: SessionReplayConfig): SessionReplay;
+//#endregion
+export { SessionReplayConfig as C, SessionAttributesInput as S, ReplayUser as _, ReplayUploadErrorInit as a, SessionAttributeValue as b, ChunkEnvelope as c, CustomTag as d, EventType as f, NetworkPayload as g, NavigationPayload as h, ReplayUploadError as i, ChunkMeta as l, MouseInteractions as m, SessionReplay as n, ReplayUploadFailureReason as o, IncrementalSource as p, startSessionReplay as r, CHUNK_ENVELOPE_VERSION as s, CaptureErrorOptions as t, ConsolePayload as u, RrwebEvent as v, SessionAttributes as x, SamplingMode as y };

package/dist/index-BxzwrVOz.d.ts

@@ -0,0 +1,220 @@
+//#region src/types.d.ts
+interface RrwebEvent {
+  type: number;
+  data: unknown;
+  timestamp: number;
+}
+declare const EventType: {
+  readonly DomContentLoaded: 0;
+  readonly Load: 1;
+  readonly FullSnapshot: 2;
+  readonly IncrementalSnapshot: 3;
+  readonly Meta: 4;
+  readonly Custom: 5;
+  readonly Plugin: 6;
+};
+declare const IncrementalSource: {
+  readonly Mutation: 0;
+  readonly MouseMove: 1;
+  readonly MouseInteraction: 2;
+  readonly Scroll: 3;
+  readonly ViewportResize: 4;
+  readonly Input: 5;
+  readonly TouchMove: 6;
+  readonly MediaInteraction: 7;
+  readonly Drag: 12;
+  readonly Selection: 14;
+};
+declare const MouseInteractions: {
+  readonly MouseUp: 0;
+  readonly MouseDown: 1;
+  readonly Click: 2;
+  readonly ContextMenu: 3;
+  readonly DblClick: 4;
+};
+declare const CustomTag: {
+  readonly Error: "logfire.error";
+  readonly Console: "logfire.console";
+  readonly Network: "logfire.network";
+  readonly Navigation: "logfire.navigation";
+};
+declare const CHUNK_ENVELOPE_VERSION: 1;
+type MaybePromise<T> = T | Promise<T>;
+type ConsoleLevel = "log" | "info" | "warn" | "error" | "debug";
+type SamplingMode = "full" | "buffer" | "off";
+type SessionAttributeValue = string | number | boolean;
+type SessionAttributesInput = Record<string, SessionAttributeValue | undefined>;
+type SessionAttributes = Record<string, SessionAttributeValue>;
+interface ConsolePayload {
+  level: ConsoleLevel;
+  args: string[];
+  source?: string;
+}
+interface NetworkPayload {
+  method: string;
+  url: string;
+  status: number;
+  durationMs: number;
+  failed?: boolean;
+  reqBytes?: number;
+  resBytes?: number;
+}
+interface NavigationPayload {
+  url: string;
+  kind: "push" | "replace" | "pop";
+}
+/** User identity reported by the application. Name and email are optional personal data. */
+interface ReplayUser {
+  id: string;
+  name?: string;
+  email?: string;
+}
+interface ChunkMeta {
+  seq: number;
+  firstTimestamp: number;
+  lastTimestamp: number;
+  eventCount: number;
+  clickCount: number;
+  keypressCount: number;
+  errorCount: number;
+  hasFullSnapshot: boolean;
+  urls: string[];
+  distinctId?: string;
+  user?: ReplayUser;
+  sessionAttributes?: SessionAttributes;
+}
+interface ChunkEnvelope {
+  version: typeof CHUNK_ENVELOPE_VERSION;
+  meta: ChunkMeta;
+  events: RrwebEvent[];
+}
+/**
+ * Early Access session replay recorder configuration. Keep browser replay
+ * rollout behind an application flag.
+ */
+interface SessionReplayConfig {
+  /**
+   * Browser-safe replay upload endpoint, either direct Logfire ingest with a
+   * restricted frontend application token or an application-owned proxy. The
+   * SDK posts to `${replayUrl}/${recordingId}?seq=${seq}`. A replay continues
+   * across same-tab reloads/navigations; a new tab gets a separate recording id.
+   */
+  replayUrl: string;
+  /**
+   * Headers added to each replay upload. Direct Logfire ingest uses the same
+   * restricted frontend application headers as traces and metrics.
+   */
+  headers?: () => MaybePromise<Record<string, string>>;
+  /**
+   * Convenience token source. A non-empty value removes any case-insensitive
+   * Authorization entry returned by `headers`, then sets
+   * `Authorization: Bearer ${token}`. Only restricted frontend application
+   * tokens are safe in browsers.
+   */
+  token?: string | (() => MaybePromise<string>);
+  /**
+   * Optional external session id source. The browser SDK integration should
+   * pass its RUM session id here. This controls sampling and session rotation;
+   * it is not used as the upload/playback id (see `getRecordingId()`).
+   */
+  getSessionId?: () => string | undefined;
+  /**
+   * Returns low-cardinality, non-PII dimensions to snapshot once per replay
+   * session. Invalid or oversized entries are omitted.
+   */
+  getSessionAttributes?: () => SessionAttributesInput;
+  /** Probability of recording each new browser session in full. */
+  sessionSampleRate?: number;
+  /** Probability of buffering each otherwise-unsampled session for uncaught error promotion. */
+  onErrorSampleRate?: number;
+  /** Mask all rendered DOM text. Defaults to true. */
+  maskAllText?: boolean;
+  maskAllInputs?: boolean;
+  maskTextSelector?: string;
+  blockSelector?: string;
+  /** Batching interval while the user is active. Defaults to 5 seconds. */
+  flushIntervalMs?: number;
+  maxBufferBytes?: number;
+  /** Minimum recording duration before a replay is uploaded. Defaults to 10 seconds. */
+  minSessionDurationMs?: number;
+  sessionIdleTimeoutMs?: number;
+  /** Maximum recording duration before the session ID rotates. Defaults to 2 hours. */
+  maxSessionDurationMs?: number;
+  distinctId?: string;
+  getDistinctId?: () => string | undefined;
+  /**
+   * Returns the current user, snapshotted for every chunk as `meta.user`. Only
+   * a non-empty `id`, `name` and `email` are kept; name and email are optional
+   * personal data. Without `getDistinctId`, the same snapshot's `id` becomes
+   * `meta.distinctId`.
+   */
+  getUser?: () => ReplayUser | undefined;
+  captureConsole?: boolean;
+  captureNetwork?: boolean;
+  captureNavigation?: boolean;
+  /**
+   * Listen for uncaught `error` and `unhandledrejection` events, add them to the replay, and
+   * promote an error-sampled buffer. Defaults to true. The browser SDK turns this off when it
+   * captures global errors itself and forwards them through `captureError()`.
+   */
+  captureGlobalErrors?: boolean;
+  ignoreUrlPatterns?: RegExp[];
+  redactUrlPatterns?: RegExp[];
+  onError?: (error: unknown) => void;
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+  random?: () => number;
+}
+//#endregion
+//#region src/uploadError.d.ts
+/**
+ * - `unconfirmed`: retries ended after a request reached the network; the server may hold the chunk.
+ * - `rejected`: the server answered with a terminal HTTP status.
+ * - `not-sent`: no request reached the network (queue full, compression, headers or token failed).
+ */
+type ReplayUploadFailureReason = "unconfirmed" | "rejected" | "not-sent";
+interface ReplayUploadErrorInit {
+  cause: unknown;
+  droppedSeqs?: readonly number[];
+  reason: ReplayUploadFailureReason;
+  seq: number | undefined;
+  sessionId: string;
+  status?: number | undefined;
+}
+/**
+ * Reported through `onError` when a replay chunk is not confirmed by the server.
+ * Recording continues from a fresh full snapshot, so `droppedSeqs` lists the
+ * later chunks that were discarded because they depended on the lost one.
+ */
+declare class ReplayUploadError extends Error {
+  readonly droppedSeqs: readonly number[];
+  readonly reason: ReplayUploadFailureReason;
+  readonly seq: number | undefined;
+  readonly sessionId: string;
+  readonly status: number | undefined;
+  constructor(init: ReplayUploadErrorInit);
+}
+//#endregion
+//#region src/index.d.ts
+interface SessionReplay {
+  readonly recording: boolean;
+  readonly mode: "full" | "buffer" | "off";
+  getSessionId(): string;
+  /**
+   * Add an error to the replay and promote an error-sampled buffer, as an uncaught error does.
+   * The same error object is added once, however many times it is captured. Pass the time the
+   * error occurred, in epoch milliseconds, when it is captured later; the error event records it
+   * as `timestamp`.
+   */
+  captureError(error: unknown, options?: CaptureErrorOptions): void;
+  /** The current DOM recording's upload/playback id; distinct from the RUM session id. */
+  getRecordingId(): string;
+  flush(): Promise<void>;
+  stop(): Promise<void>;
+}
+interface CaptureErrorOptions {
+  timestamp?: number;
+}
+declare function startSessionReplay(config: SessionReplayConfig): SessionReplay;
+//#endregion
+export { SessionReplayConfig as C, SessionAttributesInput as S, ReplayUser as _, ReplayUploadErrorInit as a, SessionAttributeValue as b, ChunkEnvelope as c, CustomTag as d, EventType as f, NetworkPayload as g, NavigationPayload as h, ReplayUploadError as i, ChunkMeta as l, MouseInteractions as m, SessionReplay as n, ReplayUploadFailureReason as o, IncrementalSource as p, startSessionReplay as r, CHUNK_ENVELOPE_VERSION as s, CaptureErrorOptions as t, ConsolePayload as u, RrwebEvent as v, SessionAttributes as x, SamplingMode as y };