@drilonhametaj/observer-node

Node SDK for the Observer SDK. Provides middleware (Next.js / Express), AsyncLocalStorage trace context, TypeORM logger integration, and automatic in-process transport detection.

Status: alpha. Only safe to use in dev environments.

Install

pnpm add @drilonhametaj/observer-node

Quickstart (Next.js App Router)

// app/api/cantieri/save/route.ts
import { withObserver } from '@drilonhametaj/observer-node'

export const POST = withObserver(async (req) => {
  const body = await req.json()
  const cantiere = await saveCantiere(body)
  return Response.json(cantiere)
})

withObserver:

1. Reads traceparent from the incoming request (or generates one) and opens an AsyncLocalStorage scope.
2. Captures the request as an HttpEvent on response.
3. Captures any thrown exception as BackendExceptionEvent and re-throws.
4. All correlated db_query / console events emitted within the handler share the same traceId.

TypeORM integration

import { observerTypeOrmLogger } from '@drilonhametaj/observer-node'

export const dataSource = new DataSource({
  type: 'postgres',
  url: process.env.DATABASE_URL,
  logger: observerTypeOrmLogger(),
  // ...
})

Every query emits a db_query event with timing. Slow queries (>200ms by default) and N+1 patterns (>10 same-signature queries in one trace) are flagged by the server's classifier.

Express

import { expressMiddleware } from '@drilonhametaj/observer-node'

app.use(expressMiddleware())

Manual capture

import { Observer } from '@drilonhametaj/observer-node'

Observer.captureException(err, { handler: 'POST /api/x' })

In-process transport

When @drilonhametaj/observer-nextjs is initialized in the same process (via configureObserver()), this SDK enqueues events directly into BullMQ — no HTTP self-call. Detection is via a shared globalThis symbol, no hard import dependency. If you run the SDK in a sidecar process, it falls back to HTTP-posting to the same /api/observer/ingest endpoint as the browser SDK.

License

MIT © Drilon Hametaj