@nais/apm API reference ¶

@nais/apm wraps @grafana/faro-web-sdk with an ergonomic, capture-oriented API. For installation, see Track frontend errors with @nais/apm.

Latest published release: 0.4.0 — pin this exact version when you install (pre-1.0, see the note below).

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 to pass, though namespace is effectively required (see its row below). app, namespace, 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',
  namespace: 'my-team', // the nais team that owns this app — effectively required
  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, namespace, 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? }. Pass an opaque, non-identifying id only — see setUser and user identity.

setUser({ id: hashedSubject }); // opaque id only — email/username/idents are dropped
// 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.

setUser and user identity ¶

Telemetry lands in a shared Loki instance that every team can read, so a user's identity must never reach it. setUser enforces this in code — it is not a convention you can opt out of:

Pass an opaque, non-identifying id — a salted hash, never a raw ident:

setUser({ id: hash(fnr) }); // an ident/email/fnr passed here is silently dropped

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.

Limitations & differences from Sentry ¶

@nais/apm gives you Sentry-shaped ergonomics but is deliberately not a drop-in for the whole Sentry API. This is the canonical list of what differs and what has no equivalent — migrating off Sentry? Read it before you delete @sentry/*.

Behaves differently ¶

Deliberately unsupported Sentry APIs ¶

These have no @nais/apm equivalent:

If you depend on one of these, log it before you delete Sentry and track it against the @nais/apm CHANGELOG.