@usesentinel/express

Sentinel middleware for Express - Track your API requests automatically.

Installation

npm install @usesentinel/express
# or
yarn add @usesentinel/express
# or
pnpm add @usesentinel/express

Usage

Simply add the middleware to your Express app:

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

const app = express();

// Add body parser middleware before sentinel
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Add Sentinel middleware
app.use(sentinel()); // That's it!

app.get("/", (req, res) => {
  res.json({ message: "Hello World" });
});

app.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 } from "@usesentinel/express";

app.get("/users", async (req, res) => {
  if (!req.sentinel) {
    return res.status(500).json({ error: "Sentinel not initialized" });
  }

  // Track a database query
  const endDbStep = registerStep(req.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
  const endApiStep = registerStep(req.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?.();

  res.json(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 } from "@usesentinel/express";

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

  // Identify the user making the request
  if (req.sentinel) {
    setUserId(req.sentinel.requestId, user.id);
  }

  res.json(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).

Important Notes

• Make sure to add body parser middleware (like express.json() or express.urlencoded()) before the Sentinel middleware so that request bodies can be captured.
• The middleware attaches a sentinel property to the Express Request object, which contains the request context including requestId.