Instrumentation & executions

Installation already instruments modules and scopes HTTP. Use this page for other entrypoints and recorder tuning.

Enable automatic instrumentation

The Vite plugin instruments your app. If you need to confirm or adjust that setup, use the prompt below.

Executions

An execution groups instrumented calls for one request or task. Recorder state is attached when that work fails.

HTTP requests

rasputinServerHooks scopes each HTTP request. Do not wrap handle, load, actions, or +server.ts again.

Background jobs

For cron, queues, and other non-HTTP entrypoints, call createRequestScope on the ServerRuntime from node() with a clear route label:

import type { ServerRuntime } from '@rasputin-ai/sveltekit';

export async function runSyncInvoices(server: ServerRuntime) {
  const scope = server.createRequestScope({
    method: 'JOB',
    route: 'sync-invoices',
  });

  try {
    await scope.run(async () => {
      await syncInvoices();
    });
  } catch (error) {
    const observation = scope.observeError(error);
    server.captureException(error, { observation });
  } finally {
    scope.finish();
  }
}

Errors, finish, and flush

scope.run() does not await for you. To attach recorder evidence from a scope you opened, pass observation from scope.observeError(error) to captureException.

try {
  await chargeCustomer();
} catch (error) {
  const observation = scope.observeError(error);
  server.captureException(error, { observation });
}

Adaptive mode

Full recording copies and bounds every argument and return on every call. That adds CPU and memory work on busy servers. Adaptive mode skips value capture on the happy path and still records call history and timings, so you keep useful failures with less overhead.

When it is enabled:

Each execution still records which functions ran, how they nest, and how long they took.
Arguments and returns wait until a qualifying error (a failure Rasputin reports). HTTP 4xx responses do not turn on full capture.
That error turns on full capture for the same execution type (same job name, route, and so on) for fullCaptureDurationMs, default 24 hours. See Configuration for the window and optional duration sampling.
Matching runs that start during the window include argument and return values. The run that failed does not.

Need values on the first failure? Leave adaptive mode off.

const server = node({
  // ...required options
  executionRecorder: {
    adaptive: { enabled: true },
  },
});

Configuration

On by default after install. Tune limits, exclusions, and redaction via node(). Each snapshot is capped at 256 KiB.

Field	Default	What it does
`enabled`	`true`	Turns runtime-state capture on or off.
`maxEventsPerExecution`	`1500`	Maximum events kept for one execution.
`maxCapturedCallsPerFunction`	`1`	Detailed successful calls kept before similar calls are summarized.
`maxActiveMemoryBytes`	`64 MiB`	Maximum recorder memory shared across active executions.
`maxDepth`	`3`	Maximum captured value depth.
`maxObjectKeys`	`30`	Maximum properties kept from one object.
`maxArrayElements`	`20`	Maximum items kept from one array, map, or set.
`maxStringLength`	`500`	Maximum characters kept from one string.
`maxSerializedValueBytes`	`16 KiB`	Maximum retained size of one captured value.
`redactKeys`	`[]`	Extra property names copied at init and applied at ingest with the default sensitive names.
`excludeSources`	`[]`	Source globs or function-name patterns to exclude.
`adaptive.enabled`	`false`	Record calls and timings without values until a qualifying error, then capture values for matching executions for a fixed window. Default captures arguments and returns from the start.
`adaptive.fullCaptureDurationMs`	`86400000`	How long matching executions keep capturing values after the first qualifying error. Default 24 hours. Clamped to 1 second–7 days. Ignored unless adaptive recording is enabled.
`adaptive.dynamicDurationSampling`	`false`	Inactive adaptive only. Default false: enabling adaptive still times every eligible invocation. True reduces duration measurements progressively for each function, its direct caller, and execution type, then resets those counters every hour. Invalid values are treated as false. Counts and call history stay retained. Selected sessions and activations always have full timing coverage.

const server = node({
  // ...required options
  executionRecorder: {
    adaptive: { enabled: true, dynamicDurationSampling: false, fullCaptureDurationMs: 86_400_000 },
    excludeSources: ['src/lib/logger/**'],
    redactKeys: ['customerEmail'],
    maxEventsPerExecution: 200,
  },
});

Sensitive data: recordings can include arguments and returns. Rasputin redacts default secret names and redactKeys at ingest. Set scrubPII: true on the client when you need personal-data redaction (default false). See Redaction for ignore comments and what we hide automatically.