JavaScript SDK

Installation

npm install @usesentinel/sentinel

yarn add @usesentinel/sentinel

pnpm add @usesentinel/sentinel

bun add @usesentinel/sentinel

Basic usage

Basic setup

Create a client instance to start tracking events:

client.ts

import { createClient } from "@usesentinel/sentinel";

const client = createClient({
  apiKey: process.env.SENTINEL_API_KEY!,
});

The client provides methods to send events individually or in batches, with automatic retries and error handling built-in.

Sending events

Send a single event

Send a complete event in one call:

import {
  createClient,
  createRequestId,
  getCurrentTimestamp,
  getBodySize,
} from "@usesentinel/sentinel";
import type { Event } from "@usesentinel/sentinel";

const client = createClient({ apiKey: "sk_..." });

const event: Event = {
  method: "GET",
  path: "/api/users",
  bodySize: 0,
  statusCode: 200,
  responseBodySize: 0,
  startedOn: getCurrentTimestamp(),
  finishedOn: getCurrentTimestamp(),
  duration: 150,
  requestId: createRequestId(),
};

await client.sendEvent(event);

Send a batch of events

Send multiple events at once for better performance:

const events: Event[] = [
  {
    method: "GET",
    path: "/api/users",
    bodySize: 0,
    statusCode: 200,
    responseBodySize: 0,
    startedOn: getCurrentTimestamp(),
    finishedOn: getCurrentTimestamp(),
    duration: 150,
    requestId: createRequestId(),
  },
  {
    method: "POST",
    path: "/api/users",
    body: JSON.stringify({ name: "John" }),
    bodySize: getBodySize(JSON.stringify({ name: "John" })),
    statusCode: 201,
    responseBody: JSON.stringify({ id: "123" }),
    responseBodySize: getBodySize(JSON.stringify({ id: "123" })),
    startedOn: getCurrentTimestamp(),
    finishedOn: getCurrentTimestamp(),
    duration: 200,
    requestId: createRequestId(),
  },
];

await client.sendBatch(events);

Batching events reduces the number of API calls and improves performance, especially for high-volume applications.

Start and complete events

For long-running requests or when you want to track the start and completion separately:

import {
  createClient,
  createRequestId,
  getCurrentTimestamp,
  getBodySize,
} from "@usesentinel/sentinel";
import type { EventStart, EventComplete } from "@usesentinel/sentinel";

const client = createClient({ apiKey: "sk_..." });
const requestId = createRequestId();

// Start tracking
const eventStart: EventStart = {
  requestId,
  method: "POST",
  path: "/api/users",
  body: JSON.stringify({ name: "John" }),
  bodySize: getBodySize(JSON.stringify({ name: "John" })),
  startedOn: getCurrentTimestamp(),
  userId: "user-123",
};

await client.startEvent(eventStart);

// ... do your work ...

// Complete tracking
const eventComplete: EventComplete = {
  requestId,
  statusCode: 201,
  responseBody: JSON.stringify({ id: "123" }),
  responseBodySize: getBodySize(JSON.stringify({ id: "123" })),
  finishedOn: getCurrentTimestamp(),
};

await client.completeEvent(eventComplete);

Start/complete tracking is useful for asynchronous operations or when you need to track events that span multiple function calls or processes.

Tracking steps

Track sub-operations within a request to monitor database queries, external API calls, and other operations:

const eventComplete: EventComplete = {
  requestId,
  statusCode: 200,
  finishedOn: getCurrentTimestamp(),
  steps: [
    {
      name: "db_query",
      startedOn: getCurrentTimestamp(),
      finishedOn: getCurrentTimestamp(),
      duration: 50,
      metadata: { table: "users", operation: "SELECT" },
    },
    {
      name: "external_api_call",
      startedOn: getCurrentTimestamp(),
      finishedOn: getCurrentTimestamp(),
      duration: 100,
      metadata: { service: "payment_gateway" },
    },
  ],
};

await client.completeEvent(eventComplete);

Steps are automatically included in the event sent to Sentinel, allowing you to see which parts of your request took the longest. This helps identify performance bottlenecks.

Configuration

The SDK automatically reads configuration from environment variables. You can also pass options directly when creating the client.

string

required

Your Sentinel API key. Can be provided via SENTINEL_API_KEY environment variable or passed directly to createClient().

Ensure your SENTINEL_API_KEY environment variable is set in production. Without it, events will not be sent to Sentinel.

API reference

`createClient(config: SentinelConfig): SentinelClient`

Creates a new Sentinel client instance.

`client.sendEvent(event: Event): Promise<{ success: boolean; queued: number; projectId: string }>`

Sends a single event to Sentinel.

`client.sendBatch(events: Event[]): Promise<{ success: boolean; queued: number; projectId: string }>`

Sends a batch of events to Sentinel in a single API call.

`client.startEvent(eventStart: EventStart): Promise<{ success: boolean; requestId: string; projectId: string }>`

Starts tracking an event. The event will be stored partially until completed.

`client.completeEvent(eventComplete: EventComplete): Promise<{ success: boolean; requestId: string; projectId: string }>`

Completes an event that was previously started. The start and complete data will be merged and sent.

Helper functions

string

Generates a unique request ID for tracking events.

string

Gets the current timestamp in ISO 8601 format.

number

Calculates the size of a request or response body in bytes.

Error handling

All methods throw errors if the request fails. Make sure to handle errors appropriately:

try {
  await client.sendEvent(event);
} catch (error) {
  console.error("Failed to send event:", error);
  // Handle error (retry, log, etc.)
}

Always wrap SDK calls in try-catch blocks to prevent unhandled promise rejections that could crash your application.

Get Started

SDKs

Installation

Basic usage

Basic setup

Sending events

Send a single event

Send a batch of events

Start and complete events

Tracking steps

Configuration

API reference

`createClient(config: SentinelConfig): SentinelClient`

`client.sendEvent(event: Event): Promise<{ success: boolean; queued: number; projectId: string }>`

`client.sendBatch(events: Event[]): Promise<{ success: boolean; queued: number; projectId: string }>`

`client.startEvent(eventStart: EventStart): Promise<{ success: boolean; requestId: string; projectId: string }>`

`client.completeEvent(eventComplete: EventComplete): Promise<{ success: boolean; requestId: string; projectId: string }>`

Helper functions

Error handling

​Installation

​Basic usage

​Basic setup

​Sending events

​Send a single event

​Send a batch of events

​Start and complete events

​Tracking steps

​Configuration

​API reference

​createClient(config: SentinelConfig): SentinelClient

​client.sendEvent(event: Event): Promise<{ success: boolean; queued: number; projectId: string }>

​client.sendBatch(events: Event[]): Promise<{ success: boolean; queued: number; projectId: string }>

​client.startEvent(eventStart: EventStart): Promise<{ success: boolean; requestId: string; projectId: string }>

​client.completeEvent(eventComplete: EventComplete): Promise<{ success: boolean; requestId: string; projectId: string }>

​Helper functions

​Error handling

Installation

Basic usage

Basic setup

Sending events

Send a single event

Send a batch of events

Start and complete events

Tracking steps

Configuration

API reference

`createClient(config: SentinelConfig): SentinelClient`

`client.sendEvent(event: Event): Promise<{ success: boolean; queued: number; projectId: string }>`

`client.sendBatch(events: Event[]): Promise<{ success: boolean; queued: number; projectId: string }>`

`client.startEvent(eventStart: EventStart): Promise<{ success: boolean; requestId: string; projectId: string }>`

`client.completeEvent(eventComplete: EventComplete): Promise<{ success: boolean; requestId: string; projectId: string }>`

Helper functions

Error handling