Node.js SDK

The @owlmetry/node SDK instruments Node.js backend services -- Express, Fastify, raw HTTP servers, and serverless functions like AWS Lambda, Vercel Serverless Functions, and Firebase Cloud Functions. It has zero runtime dependencies and ships as both ESM and CommonJS.

Features

• Events -- log at four severity levels (info, debug, warn, error) with custom attributes and automatic source-module capture from the call stack
• File Attachments -- attach files from disk or in-memory buffers to any event via the attachments option on every log method
• Structured Metrics -- track operation lifecycles (start, complete, fail, cancel) and record single-shot measurements
• Funnels -- emit named step completions for backend conversion tracking
• Experiments -- assign A/B variants with persistent local storage and automatic event tagging
• User Scoping -- Owl.withUser(userId) returns a scoped instance that tags every event with a user ID
• Session Scoping -- Owl.withSession(sessionId) links backend events to a client's session for cross-SDK correlation
• User Properties -- attach custom metadata to users via Owl.setUserProperties()
• Serverless Support -- Owl.wrapHandler() guarantees event flush before your function returns
• Auto-flush -- events are buffered and sent in batches on a configurable interval, with automatic flush on process exit via the beforeExit handler
• Gzip compression -- payloads over 512 bytes are compressed automatically
• Retry with backoff -- failed ingestion requests retry up to 5 times with exponential backoff

Requirements

• Node.js 20 or later
• An Owlmetry backend app with a client API key (owl_client_...)

Quick Start

import { Owl } from "@owlmetry/node";

Owl.configure({
  endpoint: "https://ingest.owlmetry.com",
  apiKey: "owl_client_...",
  serviceName: "my-api",
});

Owl.info("Server started", { port: 4000 });

See the installation guide to get started.