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()
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. Emits a sdk:session_started event -- marks the beginning of this service session

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.