@usesentinel/sentinel

Manual event tracking SDK for Sentinel - Track events programmatically in your application.

Installation

npm install @usesentinel/sentinel
# or
yarn add @usesentinel/sentinel
# or
pnpm add @usesentinel/sentinel
# or
bun add @usesentinel/sentinel

Usage

Basic Setup

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

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

Send a Single Event

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

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);

Start and Complete Events

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

import { createClient, createRequestId, getCurrentTimestamp } 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);

Tracking Steps

You can track sub-operations within a request:

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);

Configuration

The SDK reads from environment variables:

• SENTINEL_API_KEY (required) - Your Sentinel API key

You can also pass the API key directly to createClient().

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.

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

Sends a batch of events.

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

• createRequestId() - Generates a unique request ID
• getCurrentTimestamp() - Gets current timestamp in ISO format
• getBodySize(body: string | undefined) - Calculates body size 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.)
}