@detiq/stacklens

Lightweight Node.js SDK for sending backend telemetry and audit logs to StackLens.

import { StackLens } from "@detiq/stacklens";

const telemetry = new StackLens({
  apiKey: process.env.STACKLENS_AGENT_KEY,
  apiUrl: process.env.STACKLENS_API_URL || "https://stacklens.detiq.in",
  defaultService: "zeta-ai",
});

telemetry.info("Action performed", { tenantId: "123", actorId: "456" });
telemetry.warn("Rate limit approaching", { ip: "1.2.3.4" });
telemetry.error("Unhandled exception", { err: "Database timeout" });

Fastify

Register the SDK integration once at your authenticated Fastify boundary:

import { setupFastifyTelemetry } from "@detiq/stacklens";

setupFastifyTelemetry(app, {
  apiKey: process.env.STACKLENS_AGENT_KEY,
  apiUrl: process.env.STACKLENS_API_URL,
  defaultService: "zeta-ai",
  source: "zeta-api-mutation",
});

The Fastify integration records completed mutation requests by default (POST, PUT, PATCH, DELETE) and redacts request bodies.

Express

Register the SDK integration once before your authenticated routes:

import { setupExpressTelemetry } from "@detiq/stacklens";

setupExpressTelemetry(app, {
  apiKey: process.env.STACKLENS_AGENT_KEY,
  apiUrl: process.env.STACKLENS_API_URL,
  defaultService: "zeta-ai",
  source: "zeta-api-mutation",
});

The Express integration records the final route, status, duration, request id, actor context, route params, and redacted body after the response finishes.

Fetch Route Handlers

Use withStackLensFetchHandler for Fetch-compatible server handlers such as Next.js App Router routes:

import { withStackLensFetchHandler } from "@detiq/stacklens";

export const POST = withStackLensFetchHandler(async (request) => {
  return Response.json({ ok: true });
}, {
  apiKey: process.env.STACKLENS_AGENT_KEY,
  apiUrl: process.env.STACKLENS_API_URL,
  defaultService: "zeta-ai",
  route: "/api/route",
  source: "nextjs-route",
});

The SDK is failsafe by design: logging methods do not throw, network calls use timeouts, and telemetry delivery failures never break the host application.

Configuration

| Option | Default | Description | | --- | --- | --- | | apiKey | none | StackLens source agent key. Missing keys disable sending. | | apiUrl | https://stacklens.detiq.in | StackLens API or web proxy base URL. | | defaultService | node-app | Service name applied when a log does not specify one. | | timeoutMs | 3000 | Abort timeout for each ingest request. | | flushIntervalMs | 1000 | Background batching interval. | | maxBatchSize | 50 | Flush immediately when this many logs are queued. | | maxQueueSize | 1000 | Oldest logs are dropped beyond this queue size. | | debug | false | Emits SDK warnings to the configured logger. |

Framework Options

setupFastifyTelemetry and setupExpressTelemetry both accept:

| Option | Default | Description | | --- | --- | --- | | mutationOnly | true | Captures only POST, PUT, PATCH, and DELETE. | | redactBody | true | Replaces request bodies with REDACTED. | | source | framework name | Adds a stable source tag in metadata. | | shouldCapture | capture mutations | Custom predicate for including or excluding requests. | | getService | defaultService | Selects service dynamically per request. | | getMetadata | none | Adds request-specific metadata without changing app domain code. |

Shutdown

Call close() during graceful shutdown if you want to drain the queue:

await telemetry.close();

apiKey, apiUrl, and defaultService automatically fall back to STACKLENS_AGENT_KEY, STACKLENS_API_URL, and STACKLENS_SERVICE.