@usesentinel/hono

Sentinel middleware for Hono - Track your API requests automatically.

Installation

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

Usage

Simply add the middleware to your Hono app:

import { Hono } from "hono";
import { sentinel } from "@usesentinel/hono";

const app = new Hono();

app.use("*", sentinel()); // That's it!

app.get("/", (c) => {
  return c.text("Hello World");
});

export default app;

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/hono";

app.get("/users", async (c) => {
  const sentinel = c.get("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 c.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/hono";

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

  // Identify the user making the request
  const sentinel = c.get("sentinel");
  if (sentinel) {
    setUserId(sentinel.requestId, user.id);
  }

  return c.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).

Accessing Sentinel Context

The middleware attaches a sentinel context to the Hono context, which you can access using c.get("sentinel"):

app.get("/example", (c) => {
  const sentinel = c.get("sentinel");
  // sentinel.requestId, sentinel.path, etc.
  return c.json({ requestId: sentinel?.requestId });
});