Configuration

Call Owl.configure() once at application startup before logging any events.

Basic Configuration

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

Owl.configure({
  endpoint: "https://ingest.owlmetry.com",
  apiKey: "owl_client_...",
  serviceName: "payment-service",
  appVersion: "1.4.0",
});

Options

What Happens on Configure

When Owl.configure() is called:

1. Validates the endpoint URL and API key format
2. Generates a session ID -- a fresh UUID that groups all events until the next configure() call or shutdown(). This is the default session ID; for servers that handle many clients, per-request overrides are available via Owl.withSession() and the options.sessionId parameter on event methods
3. Starts the flush timer -- the buffer is flushed every flushIntervalMs milliseconds
4. Registers a beforeExit handler -- automatically flushes remaining events when the Node.js process exits gracefully
5. Loads experiment assignments from ~/.owlmetry/experiments.json (see Experiments)
6. Prepares the session bracket -- a sdk:session_started event is emitted lazily, just before the first user-tracked event. Cold-started processes that never call Owl.info() / Owl.step() / etc. produce no events at all. The matching sdk:session_ended event is emitted on shutdown() only if a session ever started

If you call configure() again (for example during hot reload), the previous transport is shut down cleanly before the new one starts.

isDev and Data Mode

The isDev option controls whether events are tagged as development or production data. The Data Mode filter in the dashboard and CLI lets you separate the two.

By default, isDev is true when NODE_ENV is anything other than "production". This means:

• Running node server.js locally tags events as dev
• Running NODE_ENV=production node server.js tags events as production

Override it explicitly if you need different behavior:

Owl.configure({
  endpoint: "https://ingest.owlmetry.com",
  apiKey: "owl_client_...",
  isDev: false, // always production, regardless of NODE_ENV
});

Graceful Shutdown

Call Owl.shutdown() before your process exits to flush remaining events and stop the background timer:

process.on("SIGTERM", async () => {
  await Owl.shutdown();
  process.exit(0);
});

For serverless environments, see the serverless guide which covers Owl.wrapHandler() as an alternative.