@nais/apm API reference ¶

@nais/apm wraps @grafana/faro-web-sdk with an ergonomic, capture-oriented API. This page documents the public API of version 0.1.0. For installation, see Track frontend errors with @nais/apm.

init(options?)

Initializes the SDK. Safe to call once — a second call warns and returns the existing instance. Returns the underlying Faro instance.

init(options?: InitOptions): Faro

InitOptions

All fields are optional. app, version, environment, and telemetryUrl each resolve independently (see Configuration resolution).

sessionReplay fields: enabled (boolean), mode ('on-error' default, or 'always'), sampleRate (0..1, default 1), block (string[], tighten-only). See Enable session replay.

init({
  app: 'my-app',
  version: '2026.07.04-abc1234',
  environment: 'prod-gcp',
  telemetryUrl: undefined, // usually omitted — resolved automatically on nais

  beforeSend: (item) => item,
  ignoreErrors: [/some noisy vendor error/],
  dangerouslyDisablePiiScrubbing: false,
  faro: {},

  sessionReplay: { enabled: false },
  screenshotOnError: false,
});

Configuration resolution ¶

Each of app, version, environment, and telemetryUrl resolves independently, highest priority first:

captureException(error, options?)

Captures an exception. No event ID is returned (a Faro limitation).

captureException(error: unknown, options?: CaptureExceptionOptions): void

CaptureExceptionOptions: context? (Record<string, unknown>) and fingerprint? (string, a custom grouping key).

captureException(e, {
  context: { orderId: '123' },
  fingerprint: 'checkout-timeout',
});

captureMessage(message, level?)

captureMessage(message: string, level?: SeverityLevel): void

SeverityLevel is 'fatal' | 'error' | 'warning' | 'log' | 'info' | 'debug'.

captureMessage('fallback flow used', 'warning');

setUser(user) / clearUser()

setUser(user: User): void
clearUser(): void

User: { id?, email?, username? }. Set a hashed subject as id where you can.

setUser({ id: hashedSubject, email: 'user@example.com', username: 'jdoe' });
// on logout:
clearUser();

setTag(key, value)

Attaches a single key/value tag. Faro has no first-class tag concept, so the value rides along as context on every subsequent capture rather than as an indexed label.

setTag('featureFlag.newCheckout', true);

setContext(name, context)

Attaches named context, flattened as name.key, to every subsequent capture. Pass null to remove a previously set context.

setContext('order', { id: '123', total: 499 });
setContext('order', null); // remove it

captureFeedback(message, options?)

Free-text user feedback capture.

captureFeedback(message: string, options?: CaptureFeedbackOptions): void

CaptureFeedbackOptions: category? ('bug' | 'idea' | 'other', default 'other'), email? (only sent when email-shaped), fingerprint? (joins to an issue), context? (Record<string, string>, scrubbed like the message). The message is scrubbed, trimmed, and capped at 4000 characters; empty messages are dropped.

isInitialized()

isInitialized(): boolean

if (!isInitialized()) init();

scrubString(value)

Exposes the PII scrubber directly, e.g. to sanitize a string before you log it yourself.

scrubString(value: string): string

console.log(scrubString('contact me at user@example.com'));
// -> "contact me at [email]"

Privacy: PII scrubbing ¶

Every outgoing signal — exception values, stack traces, log lines, context values, and the page URL — passes through a beforeSend scrubbing pipeline before it leaves the browser:

Your own init({ beforeSend }) runs first and may drop items by returning null; the scrubber always runs last, so it also sees anything your hook added. Opting out requires an explicit init({ dangerouslyDisablePiiScrubbing: true }) — and then your team owns the GDPR consequences of everything the app sends. Scrubbing is regex-based and best-effort — a safety net, not a GDPR guarantee. Don't put personal data in error messages in the first place.

Local development ¶

On localhost (or anywhere no collector URL resolves), init() warns once, sends nothing over the network, and echoes every signal to the console. Calling any capture function before init() is a safe no-op (with a single warning).

Supporting exports ¶

Beyond the primary API, @nais/apm also exports DEFAULT_IGNORE_ERRORS, NaisConsoleInstrumentation / CONSOLE_ERROR_PREFIX (the replacement console instrumentation that captures console.error('msg', err) with a real stack trace), resolveConfig / versionFromImage, FEEDBACK_EVENT_NAME, and VERSION. Most apps never need these directly.

Known limitations (0.1.0) ¶