Full Configuration — Collect Everything

This document is the single reference for enabling every telemetry signal Sentrinel can collect. It covers the backend plugin (Elysia, Express, Next.js, Bun) and the Flutter SDK side by side, with every option explained and every data type mapped to the dashboard page that displays it.

If you want "just works, show me everything" — copy the first config block for each side and you are done. The rest of the document explains what each option does and why it exists.

Table of contents

1. Backend config: Elysia
2. Backend config: Express
3. Backend config: Next.js
4. Backend config: Bun native
5. Flutter config
6. Browser config
7. OpenTelemetry without a plugin
8. Backend environment variables
9. What each signal captures
10. Data masking
11. Sampling safety
12. Distributed tracing
13. Structured logging deep dive
14. What you see in the dashboard
15. Troubleshooting

Backend config: Elysia

This enables every signal the backend plugin supports: request metrics, request logs with payloads, console log capture, structured logging, error tracking, distributed tracing, resource monitoring, consumer tracking, and deploy markers.

import { Elysia } from "elysia";
import { sentrinelPlugin } from "@sentrinel/plugin";

const app = new Elysia()
  .use(sentrinelPlugin({
    // ── Core ──────────────────────────────────────────────────
    serverUrl: "http://localhost:3001",            // your Sentrinel API URL
    appName: "my-api",                             // shown in dashboard
    env: "prod",                                   // "dev" | "staging" | "prod"
    apiKey: process.env.SENTRINEL_API_KEY,         // per-app ingest key
    version: process.env.GIT_SHA,                  // deploy markers on charts
    debug: false,                                  // verbose plugin logging

    // ── Flush control ─────────────────────────────────────────
    flushInterval: 30000,                          // ms between batch sends

    // ── Consumer tracking ─────────────────────────────────────
    consumerIdentifier: (ctx) =>
      ctx.request.headers.get("x-consumer-id") ?? "unknown",

    // ── Path exclusion ────────────────────────────────────────
    excludePaths: ["/health", "/metrics", /^\/internal\//],

    // ── Request logging (raw request/response rows) ───────────
    requestLogging: {
      enabled: true,                               // turn on request log rows
      sampleRate: 1.0,                             // 100% of fast successes
      slowRequestThresholdMs: 500,                 // always capture slow ones
      logRequestHeaders: true,                     // include request headers
      logRequestBody: true,                        // include request body
      logResponseBody: true,                       // include response body
      maxBodySize: 65536,                          // 64KB max body capture
      maskHeaders: [/^authorization$/i, /^cookie$/i, /^x-api-key$/i],
      maskQueryParams: ["token", "secret", "key"],
      maskBodyFields: [/^password$/i, /^token$/i, /^credit_card$/i, /^cvv$/i],
    },

    // ── Console log capture ───────────────────────────────────
    logCapture: {
      enabled: true,                               // capture console.* output
      minLevel: "debug",                           // "debug" = capture everything
      maxPerRequest: 100,                          // cap per request
      maxMessageLength: 2000,                      // truncate long messages
    },

    // ── Structured logging ────────────────────────────────────
    logging: {
      minLevel: "debug",                           // drop nothing before buffering
      echo: true,                                  // mirror to stdout in dev
    },
  }))
  .get("/", () => "hello")
  .listen(3000);

What each option does

When a request shows no payload

An empty Payloads tab on a write request is usually correct. Two cases produce one, and they are worth telling apart before assuming capture is broken:

• The request carried no body. DELETE /customers/:id and action routes like POST /workorders/:id/start put everything in the URL. Check requestSize on the row — 0 means there was nothing to record.
• The body was exactly {}. An empty object is dropped as noise. Clients that send JSON.stringify(body ?? {}) therefore look identical to clients that send nothing at all.

Anything else with a non-zero requestSize and no recorded body is a bug worth reporting.

Backend config: Express

import express from "express";
import { sentrinelExpressMiddleware } from "@sentrinel/plugin/express";

const app = express();

app.use(sentrinelExpressMiddleware({
  serverUrl: "http://localhost:3001",
  appName: "my-express-api",
  env: "prod",
  apiKey: process.env.SENTRINEL_API_KEY,
  version: process.env.GIT_SHA,

  consumerIdentifier: "x-consumer-id",           // header name (string)

  excludePaths: ["/health", "/metrics"],

  requestLogging: {
    enabled: true,
    sampleRate: 1.0,
    slowRequestThresholdMs: 500,
    logRequestHeaders: true,
    logRequestBody: true,
    logResponseBody: true,
    maxBodySize: 65536,
    maskHeaders: [/^authorization$/i, /^cookie$/i],
    maskBodyFields: [/^password$/i, /^token$/i],
  },

  logCapture: {
    enabled: true,
    minLevel: "debug",
    maxPerRequest: 100,
  },

  logging: {
    minLevel: "debug",
    echo: false,
  },
}));

app.get("/users", (req, res) => {
  res.json(getUsers());
});

app.listen(3000);

Important: Mount the middleware before your routes so it sees every request.

Backend config: Next.js

// middleware.ts (App Router)
import { sentrinelNextMiddleware } from "@sentrinel/plugin/next";

const sentrinel = sentrinelNextMiddleware({
  serverUrl: process.env.SENTRINEL_URL!,
  appName: "my-next-app",
  env: process.env.VERCEL_ENV ?? "prod",
  apiKey: process.env.SENTRINEL_API_KEY,
  version: process.env.VERCEL_GIT_COMMIT_SHA,

  requestLogging: {
    enabled: true,
    sampleRate: 1.0,
    slowRequestThresholdMs: 500,
    logRequestHeaders: true,
    logRequestBody: true,
    logResponseBody: true,
    maxBodySize: 65536,
    maskHeaders: [/^authorization$/i, /^cookie$/i],
    maskBodyFields: [/^password$/i, /^token$/i],
  },

  logCapture: {
    enabled: true,
    minLevel: "info",
    maxPerRequest: 50,
  },

  logging: {
    minLevel: "debug",
    echo: false,
  },
});

export function middleware(request: Request) {
  return sentrinel.middleware(request);
}

export const config = {
  matcher: "/api/:path*",
};

For Pages Router API routes, wrap each handler:

import { withSentrinel } from "@sentrinel/plugin/next";

export default withSentrinel({
  serverUrl: process.env.SENTRINEL_URL!,
  appName: "my-next-app",
  env: process.env.VERCEL_ENV ?? "prod",
}, async function handler(req, res) {
  res.json({ data: "hello" });
});

Backend config: Bun native

For raw Bun.serve without Elysia:

import { sentrinelBunMiddleware } from "@sentrinel/plugin/bun";

Bun.serve({
  port: 3000,
  fetch: sentrinelBunMiddleware({
    serverUrl: "http://localhost:3001",
    appName: "my-bun-app",
    env: "prod",
    apiKey: process.env.SENTRINEL_API_KEY,
    version: process.env.GIT_SHA,

    consumerIdentifier: "x-consumer-id",

    requestLogging: {
      enabled: true,
      sampleRate: 1.0,
      slowRequestThresholdMs: 500,
      logRequestHeaders: true,
      logRequestBody: true,
      logResponseBody: true,
    },

    logCapture: {
      enabled: true,
      minLevel: "debug",
    },

    logging: {
      minLevel: "debug",
      echo: false,
    },
  }, async (req) => {
    return new Response("Hello");
  }),
});

Flutter config

The Flutter SDK captures HTTP requests, errors, crashes, release health sessions, performance frames, and structured logs. It sends traceparent headers so backend traces connect automatically.

Using SentrinelFlutter (recommended)

import 'package:flutter/material.dart';
import 'package:sentrinel_flutter/sentrinel_flutter.dart';

void main() => SentrinelFlutter.run(
  options: SentrinelOptions(
    serverUrl: 'https://api.sentrinel.dev',
    appName: 'mobile-app',
    env: 'prod',
    apiKey: const String.fromEnvironment('SENTRINEL_API_KEY'),
    release: '1.4.2',           // critical for release health
    flushInterval: Duration(seconds: 30),
  ),
  app: () => runApp(const MyApp()),
);

// In your root widget:
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // Navigation tracking + breadcrumbs
      navigatorObservers: [SentrinelNavigatorObserver()],
      home: HomeScreen(),
    );
  }
}

Key rule: runApp goes inside the app callback. Async errors are only caught within the zone — calling runApp outside it silently misses most of them.

Using the core Dart package (non-Flutter)

import 'package:sentrinel/sentrinel.dart';

void main() {
  Sentrinel.init(
    serverUrl: 'https://api.sentrinel.dev',
    appName: 'my-dart-app',
    env: 'prod',
    apiKey: const String.fromEnvironment('SENTRINEL_API_KEY'),
    release: '1.4.2',
    consumerIdentifier: 'ios_app',  // or 'android_app', user id, etc.
  );
  runApp(const MyApp());
}

// HTTP client — every request is recorded + traceparent is sent
final client = Sentrinel.httpClient();

// Dio adapter
final dio = Dio();
dio.httpClientAdapter = SentrinelHttpClientAdapter();

What gets captured automatically

Capturing errors manually

// Uncaught errors (in your zone handler)
runZonedGuarded(() {
  // ...
}, (error, stack) {
  Sentrinel.captureError(error, stack, path: 'main');
});

// Caught errors
try {
  await api.submitPost(post);
} catch (e, stack) {
  Sentrinel.captureError(e, stack, path: 'submit_post');
  rethrow;
}

Adding context

// After login — attaches to every later record
Sentrinel.setContext({
  'userId': user.id,
  'tier': user.subscriptionTier,
  'locale': Localizations.localeOf(context).languageCode,
});

// On logout
Sentrinel.clearContext();

Adding breadcrumbs

Sentrinel.addBreadcrumb('tapped pay', category: 'ui', data: {'amount': 42});

Structured logs

Sentrinel.info('User signed in', category: 'auth', attributes: {
  'method': 'google',
});

Sentrinel.warn('Cache miss', category: 'cache', attributes: {
  'key': 'feed_v2',
});

Sentrinel.error('Payment failed', category: 'billing', attributes: {
  'orderId': order.id,
  'reason': 'insufficient_funds',
});

Flush on background

When the app goes to the background, flush buffered telemetry so nothing is lost (especially crash reports):

class _MyAppState extends State<MyApp> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.paused ||
        state == AppLifecycleState.detached) {
      Sentrinel.flush();
    }
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }
}

Full Flutter example

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:sentrinel_flutter/sentrinel_flutter.dart';

void main() => SentrinelFlutter.run(
  options: SentrinelOptions(
    serverUrl: 'https://api.sentrinel.dev',
    appName: 'my-app',
    env: 'prod',
    apiKey: const String.fromEnvironment('SENTRINEL_API_KEY'),
    release: '1.4.2',
  ),
  app: () => runApp(const MyApp()),
);

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.paused ||
        state == AppLifecycleState.detached) {
      Sentrinel.flush();
    }
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorObservers: [SentrinelNavigatorObserver()],
      home: Scaffold(
        body: Center(
          child: ElevatedButton(
            onPressed: () async {
              final client = Sentrinel.httpClient();
              final res = await client.get(
                Uri.parse('https://api.example.com/posts'),
              );
              // Process response...
            },
            child: const Text('Load Posts'),
          ),
        ),
      ),
    );
  }
}

Browser config

A web app is the third surface, and the only one where the API key cannot go in the config. Everything in a JavaScript bundle is served to every visitor, and an ingest key cannot be scoped down after the fact. So the setup is two halves: the page holds no secret and posts to your own origin, and a server route forwards with the key.

Client — everything on

import { initSentrinelBrowser } from '@sentrinel/plugin/browser';

// Before hydration or first render. An error thrown *during* hydration is one
// of the most common real failures, and a handler installed after misses it.
export const sentrinel = initSentrinelBrowser({
  // Same origin, so no key ships in the bundle.
  endpoint: '/api/sentrinel',

  // Crash-free rate is per release. Without this every build reads `unknown`.
  release: '2026.8.2',

  // ── What to collect ──────────────────────────────────────────────────
  captureErrors: true,       // window errors + unhandled rejections
  captureRequests: true,     // patch fetch: timing, status, trace propagation
  captureBreadcrumbs: true,  // clicks, SPA navigation, requests
  trackSessions: true,       // one per page load — release health's denominator

  // ── Volume ───────────────────────────────────────────────────────────
  sampleRate: 1,                 // successful requests kept
  slowRequestThresholdMs: 2_000, // above this, kept regardless of sampleRate
  flushInterval: 10_000,
  maxBatch: 100,                 // flush early once this many records queue

  // ── Tracing ──────────────────────────────────────────────────────────
  // Same-origin only by default: sending trace ids to a third party leaks them
  // and turns a simple request into one needing CORS preflight.
  tracePropagationTargets: [/^\//, 'https://api.myapp.com'],

  // ── Noise ────────────────────────────────────────────────────────────
  // On top of the built-in list (`Script error.`, ResizeObserver loops,
  // browser-extension frames).
  ignoreErrors: ['AbortError', 'The user aborted a request'],

  // ── Redaction ────────────────────────────────────────────────────────
  // Runs before the value is ever on the wire — the only place that helps for
  // data that should not leave the device at all. Return null to drop.
  beforeSend: (record) => {
    if (record.kind === 'request' && record.queryParams?.token) {
      record.queryParams.token = '[redacted]';
    }
    return record;
  },

  debug: import.meta.env.DEV,
});

Server — the tunnel

Any runtime that speaks Request/Response: Bun, Elysia, Hono, Next route handlers, TanStack Start, Remix, Deno, Workers.

import { createSentrinelTunnel } from '@sentrinel/plugin/tunnel';

export const POST = createSentrinelTunnel({
  serverUrl: 'https://api.sentrinel.dev',

  // Pinned here, never read from the batch. A browser-supplied app name is a
  // claim from an untrusted source — without pinning, anyone who found the
  // endpoint could write into a different app in your account.
  appName: 'admin',
  env: 'prod',

  apiKey: process.env.SENTRINEL_API_KEY!,   // never reaches the client
  release: process.env.GIT_SHA,

  // An open endpoint that will buffer anything is a memory-exhaustion target.
  maxBodyBytes: 256 * 1024,

  // Read server-side and overrides whatever the browser claimed. An identity a
  // page asserts about itself is a claim, not a fact.
  consumerIdentifier: (request) => userIdFromSession(request),

  beforeForward: (batch, request) => batch,  // null drops the batch

  debug: process.env.NODE_ENV !== 'production',
});

What gets captured automatically

Manual API

sentrinel.captureError(err, { orderId: 'o_1' });
sentrinel.addBreadcrumb('tapped pay', { category: 'ui', data: { amount: 42 } });
sentrinel.setUser('user_123');       // null on sign-out
sentrinel.setContext({ tier: 'pro' });
await sentrinel.flush();
await sentrinel.close();             // unpatch, end the session, send

Not covered

Source maps (a minified stack stays minified), web vitals, XMLHttpRequest (only fetch is patched), and session replay.

Full detail: BROWSER.md.

OpenTelemetry without a plugin

Any OpenTelemetry SDK or Collector can export straight to Sentrinel. This works for any language — Go, Rust, Java, Python, Ruby, .NET — not just JS/Dart.

OTEL_EXPORTER_OTLP_ENDPOINT=https://api.sentrinel.dev
OTEL_EXPORTER_OTLP_PROTOCOL=http/json
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=snt_live_your_key_here

GenAI spans (gen_ai.request.model + gen_ai.usage.*_tokens) are priced automatically and appear on the LLM cost dashboard page.

What gets collected

Backend environment variables

These control the Sentrinel API server itself. Set them in .env or your deployment platform (Dokploy, Docker, etc.).

# ── Storage ──────────────────────────────────────────────────
DATABASE_URL=postgresql://sentrinel:<password>@postgres:5432/sentrinel
TELEMETRY_STORE=clickhouse                # "postgres" or "clickhouse"
CLICKHOUSE_DB=sentrinel
CLICKHOUSE_USER=sentrinel
CLICKHOUSE_PASSWORD=<password>
CLICKHOUSE_URL=http://clickhouse:8123

# ── Network ──────────────────────────────────────────────────
SENTRINEL_API_PORT=3001
PUBLIC_API_URL=https://api.sentrinel.dev   # compiled into dashboard at build time
PUBLIC_DASHBOARD_URL=https://app.sentrinel.dev

# ── Auth & security ─────────────────────────────────────────
SENTRINEL_REQUIRE_AUTH=true               # enforce session auth on dashboard routes
SENTRINEL_REQUIRE_INGEST_KEY=true         # require API keys for ingestion
SENTRINEL_DISABLE_SIGNUP=false            # lock signup after first user
SENTRINEL_ALLOWED_ORIGINS=https://app.sentrinel.dev,http://localhost:3000
SENTRINEL_COOKIE_SAMESITE=lax
SENTRINEL_COOKIE_DOMAIN=

# ── Billing, trials & the operator console ──────────────────
SENTRINEL_ADMIN_EMAILS=                   # comma-separated; empty = nobody is an admin
SENTRINEL_TRIAL_DAYS=14                   # 0 disables trials (self-hosted wants this)
SENTRINEL_INGEST_GRACE_DAYS=7             # keep accepting telemetry this long after a block

# ── Retention ────────────────────────────────────────────────
RETENTION_LOGS_DAYS=30                    # raw request/app log retention
RETENTION_METRICS_DAYS=400                # aggregated metrics (~13 months)
RETENTION_REPLAY_DAYS=14                  # session replay recordings

# ── Connection pools ────────────────────────────────────────
DATABASE_POOL_SIZE=10
DATABASE_READ_POOL_SIZE=10
DATABASE_REPLICA_URL=                     # optional read replica

Key settings explained

What each signal captures

Request metrics (always collected)

In-memory aggregation, flushed every 30s. Exact regardless of sampling.

Dashboard pages: Traffic, Performance, Errors, Consumers

Request logs (when requestLogging.enabled: true)

Individual request/response records with full detail.

Dashboard pages: Request Logs, Traffic (endpoint detail), Performance (Apdex)

Application logs (when logging.enabled or logCapture.enabled)

Structured log records correlated to requests.

Dashboard pages: Logs, Request Logs (Logs tab)

Errors (auto-collected for status >= 400)

Fingerprinted and grouped into issues with occurrence counting.

Dashboard pages: Issues, Errors

Distributed traces (auto-collected for every request)

Dashboard pages: Traces (waterfall), Request Logs (Trace tab)

Resource metrics (auto-collected)

Dashboard pages: Resources

LLM cost (auto-detected from GenAI spans)

Dashboard pages: LLM cost

Release health (Flutter sessions)

Dashboard pages: Release Health

Data masking

Masking runs in your process, before anything leaves it. A masked field never reaches the network, let alone Sentrinel's disk.

Headers to mask

maskHeaders: [
  /^authorization$/i,    // auth tokens
  /^cookie$/i,           // session cookies
  /^x-api-key$/i,        // API keys
  /^x-auth-token$/i,     // custom auth
],

Query parameters to mask

maskQueryParams: [
  "token",               // exact match
  "secret",              // exact match
  /^key$/i,              // regex match
],

Body fields to mask

maskBodyFields: [
  /^password$/i,         // password fields
  /^token$/i,            // token fields
  /^credit_card$/i,      // payment fields
  /^cvv$/i,              // security codes
  /^ssn$/i,              // social security
  /^secret$/i,           // any secret
],

maskBodyFields descends into nested JSON objects. A field named password at any depth is masked.

Sampling safety

Three properties make sampling safe:

1. Errors and slow requests are never sampled out. sampleRate applies only to successful, fast requests — the ones you were never going to read.

2. Metrics stay exact. Counters are computed in-process before sampling, so a 1% sample rate still yields correct request counts and error rates. Only the individual log rows are thinned.

3. Every row records the rate it was captured at, so counts derived from raw logs can be extrapolated honestly rather than silently under-reporting.

Recommended sample rates

Distributed tracing

Traces connect the full request path: Flutter tap → API → database → external service. The root span is always the HTTP request. Child spans are created with traceSpan().

Manual spans

import { traceSpan, traced } from "@sentrinel/plugin";

// Wrap a block
const user = await traceSpan("db.findUser", async (span) => {
  span.setAttribute("db.system", "postgresql");
  span.setAttribute("db.operation", "SELECT");
  return db.users.findById(id);
});

// Wrap a function at definition
const getProducts = traced("db.getProducts", () => db.products.find());

Auto-trace an entire service

import { traceObject } from "@sentrinel/plugin";

const db = traceObject(new DatabaseClient(), "db");
// Every method on db is now auto-traced as "db.*"

Cross-service calls

import { sentrinelFetch } from "@sentrinel/plugin";

// Automatically propagates traceparent header
const res = await sentrinelFetch("https://payments.internal/v1/charges", {
  method: "POST",
  body: JSON.stringify({ amount }),
});

Flutter → backend correlation

The Flutter SDK automatically sends traceparent on every HTTP request. The backend plugin picks it up and continues the same trace. No extra configuration needed — just make sure both sides use the same Sentrinel API.

Span kinds

Use the right kind for accurate waterfall coloring:

Structured logging deep dive

Why structured logging

console.log(\user ${id} failed checkout`)` is easy to write and impossible to query. You cannot filter by user, group by failure reason, or tie it to the request that produced it.

Structured logging fixes this by separating the message (stable, groupable) from the attributes (filterable fields).

Context is inherited, not repeated

withContext({ userId: user.id, tenantId: org.id, tier: user.tier }, async () => {
  await processOrder();
  // every log inside carries those three fields
  // even three levels deep, in code that never heard of a user
});

Categories are hierarchical

const log = getLogger(["api", "checkout"]);
// logs under "api.checkout"

const sub = log.getChild("db");
// logs under "api.checkout.db"

// Filter by "api" to see everything in the API subsystem

Canonical wide events

Instead of scattered log lines, attach rich context to the request itself:

addRequestContext({
  tier: user.tier,
  cartTotal,
  experiment: "new-pricing",
  outcome: "success",
});

"Slow checkouts for enterprise customers in the new pricing experiment" becomes one query rather than a correlation exercise.

Everything is linked

• The request row carries the trace id and your addRequestContext() fields
• Every log record carries the request id, trace id and span id
• The trace carries the request id, so the waterfall links back
• An error occurrence carries both, linking to the exact request

What you see in the dashboard

Troubleshooting

Nothing shows up

1. Check API health: curl http://localhost:3001/health
2. Check serverUrl: Must point to the API, not the dashboard
3. Check API key: Must match appName + env
4. Check requestLogging.enabled: true: Metrics work without it, request logs don't
5. Check excludePaths: Your endpoint might be excluded

Logs not appearing

• logging.enabled is off by default. Add logging: { minLevel: "debug" }.
• logCapture.enabled is off by default. Add logCapture: { enabled: true, minLevel: "debug" }.

Traces missing

• No traceSpan() calls = only the root HTTP span appears. Wrap key operations.
• For Flutter: traceparent propagation is automatic. No config needed.

Flutter crashes not showing

• Make sure runApp is inside the app callback of SentrinelFlutter.run()
• Set release — without it, release health shows "unknown"
• Call Sentrinel.flush() in didChangeAppLifecycleState when paused

403 errors in logs

The API key doesn't match appName + env. Create a new key in the dashboard that matches both values.

Reference: all plugin options