@interfere/elysia

Elysia plugin for Interfere. Creates a span for every request and reports server-fault errors (5xx and uncaught throws) with request context.

Install

bun add @interfere/elysia
# or
npm install @interfere/elysia
# or
pnpm add @interfere/elysia

elysia and @elysia/opentelemetry are peer dependencies:

bun add elysia @elysia/opentelemetry

Setup

Register the plugin once at the root of your app:

import { Elysia } from "elysia";
import { interfere } from "@interfere/elysia";

new Elysia()
  .use(interfere({ serviceName: "checkout-api" }))
  .get("/", () => "ok")
  .listen(3000);

That's it. The plugin exports per-request spans to Interfere, reports 5xx and uncaught errors with request context, and installs process-level handlers for uncaught exceptions and unhandled rejections. Client faults (validation, not-found) still produce spans but are not reported as errors.

When INTERFERE_PUBLIC_KEY is unset the plugin is inert, so local runs without the SDK configured don't crash.

Manual instrumentation

import { record, captureError, withSpan } from "@interfere/elysia";

app.get("/users", () =>
  record("db.query", () => db.query("SELECT * FROM users"))
);

• record(name, fn) — wrap work in a child span that auto-closes and captures exceptions.
• withSpan(name, fn) — same, framework-agnostic.
• captureError(error, request?) / captureMessage(message, request?) — report an error from anywhere.
• getCurrentSpan() / setAttributes(attrs) — annotate the active span.

Build & Deploy

Install @interfere/cli as a dev dependency and add a postbuild script so source maps are uploaded and the release is registered. Without this step, the collector rejects spans from production deployments.

{
  "scripts": {
    "build": "tsc",
    "postbuild": "interfere sourcemaps upload ./dist"
  }
}

The CLI derives the release slug from the same commit SHA the SDK uses at runtime (INTERFERE_SOURCE_ID, GITHUB_SHA, VERCEL_GIT_COMMIT_SHA, or git rev-parse HEAD). Both must see the same SHA for the slugs to match.

Environment Variables

| Variable | Where | Purpose | |---|---|---| | INTERFERE_PUBLIC_KEY | Runtime | Routes spans to your surface (interfere_pub_us_* or interfere_pub_eu_*) | | INTERFERE_API_KEY | CI / Build | Authenticates source map uploads and release registration (interfere_secret_us_* or interfere_secret_eu_*) | | INTERFERE_SOURCE_ID | Both | Override the commit SHA used to derive the release slug. | | INTERFERE_DEBUG | Runtime | Set to 1 to log lifecycle events and exporter results. Equivalent to debug: true. |

Options

| Option | Default | Purpose | |---|---|---| | serviceName | OTEL_SERVICE_NAME ?? "elysia-app" | The identity spans are grouped by. | | serviceNamespace | — | Groups several services under one product surface. | | environment | INTERFERE_ENVIRONMENT ?? VERCEL_ENV ?? NODE_ENV ?? development | Deployment environment label. | | captureUncaughtException | true | Report and exit on uncaughtException. | | captureUnhandledRejection | true | Report on unhandledRejection. | | debug | false | Log lifecycle and exporter results to stdout. |

Compatibility

• Elysia 1.4+
• Bun and Node.js