Complete API reference for the Overseer SDK

API Reference

Complete reference for all Overseer SDK methods.

Initialization

init(config)

Initialize the Overseer SDK. Call this once at app startup.

import { init } from '@codmir/overseer';

init({
  dsn: 'https://your-project.codmir.com/overseer',
  apiKey: 'osk_...',
  service: 'my-app',
  environment: 'production',
  release: '1.0.0',
});

Config Options

OptionTypeDefaultDescription
dsnstringRequiredOverseer endpoint URL
servicestringRequiredService/app name
environmentstringRequiredEnvironment (production, staging, development)
releasestring-App version for release tracking
enabledbooleantrueEnable/disable the SDK
debugbooleanfalseEnable debug logging
errorSampleRatenumber1Error sampling rate (0-1)
enableReplaybooleantrueEnable session replay
replaySampleRatenumber0.1Session replay sampling rate (0-1)
replayOnErrorSampleRatenumber1.0Replay rate for error sessions (0-1)
enablePerformancebooleantrueEnable performance tracking
maskAllInputsbooleanfalseMask all form inputs in replay
maskSelectorsstring[][]CSS selectors to mask in replay
beforeSendfunction-Filter/modify events before sending

Error Capture

captureException(error, context?)

Capture an exception with optional context.

import { captureException } from '@codmir/overseer';

try {
  await riskyOperation();
} catch (error) {
  captureException(error, {
    level: 'error',
    tags: { feature: 'checkout' },
    extra: { orderId: '12345' },
  });
}

Parameters

ParameterTypeDescription
errorError | stringThe error to capture
context.level'fatal' | 'error' | 'warning' | 'info' | 'debug'Severity level
context.tagsRecord<string, string>Indexed tags for filtering
context.extraRecord<string, unknown>Additional context data

Returns

string | null - Event ID or null if not sent


captureMessage(message, level?)

Capture a message event.

import { captureMessage } from '@codmir/overseer';

captureMessage('User completed checkout', 'info');
captureMessage('Payment failed', 'error');

Parameters

ParameterTypeDefaultDescription
messagestringRequiredMessage to capture
level'fatal' | 'error' | 'warning' | 'info' | 'debug''info'Severity level

Context

setUser(user)

Set user context for all subsequent events.

import { setUser } from '@codmir/overseer';

// Set user
setUser({
  id: 'user-123',
  email: 'user@example.com',
  username: 'johndoe',
});

// Clear user (on logout)
setUser(null);

User Object

PropertyTypeDescription
idstringUnique user identifier
emailstringUser email (optional)
usernamestringUsername (optional)

setTags(tags)

Set global tags for all events.

import { setTags } from '@codmir/overseer';

setTags({
  region: 'us-east-1',
  tenant: 'acme-corp',
});

setContext(name, context)

Set named context data.

import { setContext } from '@codmir/overseer';

setContext('order', {
  id: 'order-123',
  total: 99.99,
  items: 3,
});

addBreadcrumb(breadcrumb)

Add a breadcrumb for context on future errors.

import { addBreadcrumb } from '@codmir/overseer';

addBreadcrumb({
  type: 'navigation',
  category: 'router',
  message: 'Navigated to /checkout',
  level: 'info',
  data: { from: '/cart' },
});
PropertyTypeDescription
type'navigation' | 'http' | 'ui' | 'console' | 'user' | 'custom'Breadcrumb type
categorystringCategory for grouping
messagestringHuman-readable message
level'debug' | 'info' | 'warning' | 'error' | 'fatal'Severity
dataRecord<string, unknown>Additional data

Session Replay

startReplay()

Manually start session replay recording.

import { startReplay } from '@codmir/overseer';

const sessionId = startReplay();

stopReplay()

Stop session replay recording.

import { stopReplay } from '@codmir/overseer';

stopReplay();

Performance

trackMetric(name, value, unit?, tags?)

Track a custom performance metric.

import { trackMetric } from '@codmir/overseer';

trackMetric('api.latency', 150, 'ms', { endpoint: '/api/users' });

timeOperation(name, operation, tags?)

Time an async operation.

import { timeOperation } from '@codmir/overseer';

const result = await timeOperation(
  'database.query',
  async () => db.users.findMany(),
  { table: 'users' }
);

Lifecycle

flush(timeout?)

Flush pending events to the server.

import { flush } from '@codmir/overseer';

await flush(2000); // Wait up to 2 seconds

close(timeout?)

Close the client and flush pending events.

import { close } from '@codmir/overseer';

await close();

Next.js Specific

captureRouterTransitionStart()

Track Next.js router transitions (use with onRouterTransitionStart).

// instrumentation-client.ts
export const onRouterTransitionStart = Overseer.captureRouterTransitionStart;

captureRequestError(error, request, context)

Capture server-side request errors.

// instrumentation.ts
export const onRequestError = async (error, request, context) => {
  await Overseer.captureRequestError(error, request, context);
};