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',
  service: 'my-app',
  environment: 'production',
  release: '1.0.0',
});

Config Options

Option	Type	Default	Description
`dsn`	`string`	Required	Overseer endpoint URL
`service`	`string`	Required	Service/app name
`environment`	`string`	Required	Environment (production, staging, development)
`release`	`string`	-	App version for release tracking
`enabled`	`boolean`	`true`	Enable/disable the SDK
`debug`	`boolean`	`false`	Enable debug logging
`errorSampleRate`	`number`	`1`	Error sampling rate (0-1)
`enableReplay`	`boolean`	`true`	Enable session replay
`replaySampleRate`	`number`	`0.1`	Session replay sampling rate (0-1)
`replayOnErrorSampleRate`	`number`	`1.0`	Replay rate for error sessions (0-1)
`enablePerformance`	`boolean`	`true`	Enable performance tracking
`maskAllInputs`	`boolean`	`false`	Mask all form inputs in replay
`maskSelectors`	`string[]`	`[]`	CSS selectors to mask in replay
`beforeSend`	`function`	-	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

Parameter	Type	Description
`error`	`Error \| string`	The error to capture
`context.level`	`'fatal' \| 'error' \| 'warning' \| 'info' \| 'debug'`	Severity level
`context.tags`	`Record<string, string>`	Indexed tags for filtering
`context.extra`	`Record<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

Parameter	Type	Default	Description
`message`	`string`	Required	Message 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

Property	Type	Description
`id`	`string`	Unique user identifier
`email`	`string`	User email (optional)
`username`	`string`	Username (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,
});

Breadcrumbs

`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' },
});

Property	Type	Description
`type`	`'navigation' \| 'http' \| 'ui' \| 'console' \| 'user' \| 'custom'`	Breadcrumb type
`category`	`string`	Category for grouping
`message`	`string`	Human-readable message
`level`	`'debug' \| 'info' \| 'warning' \| 'error' \| 'fatal'`	Severity
`data`	`Record<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);
};

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',
  service: 'my-app',
  environment: 'production',
  release: '1.0.0',
});

Config Options

Option	Type	Default	Description
`dsn`	`string`	Required	Overseer endpoint URL
`service`	`string`	Required	Service/app name
`environment`	`string`	Required	Environment (production, staging, development)
`release`	`string`	-	App version for release tracking
`enabled`	`boolean`	`true`	Enable/disable the SDK
`debug`	`boolean`	`false`	Enable debug logging
`errorSampleRate`	`number`	`1`	Error sampling rate (0-1)
`enableReplay`	`boolean`	`true`	Enable session replay
`replaySampleRate`	`number`	`0.1`	Session replay sampling rate (0-1)
`replayOnErrorSampleRate`	`number`	`1.0`	Replay rate for error sessions (0-1)
`enablePerformance`	`boolean`	`true`	Enable performance tracking
`maskAllInputs`	`boolean`	`false`	Mask all form inputs in replay
`maskSelectors`	`string[]`	`[]`	CSS selectors to mask in replay
`beforeSend`	`function`	-	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

Parameter	Type	Description
`error`	`Error \| string`	The error to capture
`context.level`	`'fatal' \| 'error' \| 'warning' \| 'info' \| 'debug'`	Severity level
`context.tags`	`Record<string, string>`	Indexed tags for filtering
`context.extra`	`Record<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

Parameter	Type	Default	Description
`message`	`string`	Required	Message 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

Property	Type	Description
`id`	`string`	Unique user identifier
`email`	`string`	User email (optional)
`username`	`string`	Username (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,
});

Breadcrumbs

`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' },
});

Property	Type	Description
`type`	`'navigation' \| 'http' \| 'ui' \| 'console' \| 'user' \| 'custom'`	Breadcrumb type
`category`	`string`	Category for grouping
`message`	`string`	Human-readable message
`level`	`'debug' \| 'info' \| 'warning' \| 'error' \| 'fatal'`	Severity
`data`	`Record<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);
};