@usesentinel/elysia

Sentinel middleware for Elysia - Track your API requests automatically.

Installation

bun add @usesentinel/elysia
# or
npm install @usesentinel/elysia

Usage

Simply add the middleware after CORS:

import { Elysia } from "elysia";
import { cors } from "@elysiajs/cors";
import { sentinel } from "@usesentinel/elysia";

const app = new Elysia()
  .use(cors())
  .use(sentinel()) // That's it!
  .get("/", () => "Hello World")
  .listen(3000);

Configuration

The SDK automatically reads from environment variables:

• SENTINEL_API_KEY (required) - Your Sentinel API key

You can also pass options directly:

app.use(
  sentinel({
    apiKey: "sk_...", // Optional if SENTINEL_API_KEY is set
    batchSize: 50, // Optional, default 50
    flushInterval: 5000, // Optional, default 5000ms
    excludePaths: ["/health", "/metrics"], // Optional
  })
);

Tracking Steps

You can track sub-operations within a request (like database queries, external API calls, etc.):

import { registerStep, type SentinelContext } from "@usesentinel/elysia";

app.get("/users", async ({ ...context }) => {
  const sentinel = (context as { sentinel?: SentinelContext }).sentinel;

  // Track a database query
  let endDbStep: (() => void) | undefined;
  if (sentinel) {
    endDbStep = registerStep(sentinel.requestId, "db_query", {
      table: "users",
      operation: "SELECT",
    });
  }
  const users = await db.query("SELECT * FROM users");
  endDbStep?.(); // Step completes here

  // Track an external API call
  let endApiStep: (() => void) | undefined;
  if (sentinel) {
    endApiStep = registerStep(sentinel.requestId, "external_api_call", {
      service: "payment_gateway",
    });
  }
  const payment = await fetch("https://api.payment.com/charge", {
    method: "POST",
    body: JSON.stringify({ amount: 100 }),
  });
  endApiStep?.();

  return users;
});

The steps will be automatically included in the event sent to Sentinel, allowing you to see which parts of your request took the longest.

Setting User Context

You can set userId for a request to track user behavior:

import { setUserId, type SentinelContext } from "@usesentinel/elysia";

app.get("/users", async ({ ...context }) => {
  // Get user from your auth system
  const user = await getCurrentUser();

  // Identify the user making the request
  const sentinel = (context as { sentinel?: SentinelContext }).sentinel;
  if (sentinel) {
    setUserId(sentinel.requestId, user.id);
  }

  return users;
});

The userId will be automatically included in the event sent to Sentinel.

How it works

The middleware automatically:

• Tracks all incoming requests
• Captures request/response metadata
• Batches events and sends them to Sentinel API
• Handles errors gracefully with automatic retries
• Supports exponential backoff for failed requests

Events are batched and sent automatically, so there's minimal performance impact. Failed requests are automatically retried with exponential backoff (up to 3 retries by default).