Configuration

Pass a configuration object to init():

import { init } from "auralog-sdk";

init({
  apiKey: "aura_your_api_key",
  environment: "production",
  captureConsole: false,
  captureErrors: true,
  flushInterval: 5000,
});

Options

Option	Type	Default	Description
apiKey	string	required	Your ingest key. Starts with aura_. Copy it from the startup modal or create another in project settings.
environment	string	undefined	Environment label attached to every log (e.g. "production", "staging").
captureConsole	boolean	false	When true, intercepts console.log, console.warn, and console.error and sends them as auralogs logs.
captureErrors	boolean	true	Automatically captures uncaught exceptions and unhandled promise rejections.
flushInterval	number	5000	How often (in milliseconds) batched logs are sent to the ingest endpoint.
endpoint	string	"https://ingest.auralog.ai"	Custom ingest endpoint URL. Only change this if you’re self-hosting.
globalMetadata	Record<string, unknown> | (() => Record<string, unknown>)	undefined	Baseline metadata merged into every log entry — including captured console.* calls and uncaught errors. See Global metadata below.

Global metadata

Available since auralog-sdk 0.2.0.

Use globalMetadata to attach session-scoped fields — user_id, org id, feature-flag snapshot, build SHA — to every log entry without threading them through every call site. The merged metadata flows through direct API calls and captured console.* output and uncaught errors, so attribution is consistent across all three.

Static form

If the value never changes for the lifetime of the SDK instance, pass an object:

init({
  apiKey: "aura_...",
  globalMetadata: { app: "checkout-service", region: "us-east-1" },
});

Supplier form

For values that change at runtime (the canonical case: the currently signed-in user), pass a function. It is invoked at every log emission, so it always reflects current host state:

init({
  apiKey: "aura_...",
  captureConsole: true,
  globalMetadata: () => ({
    user_id: currentUser?.id,
    user_email: currentUser?.email,
  }),
});

Now every direct call, every captured console.log, and every uncaught error carries user_id and user_email — searchable in the dashboard via user_id:abc and visible to your AI provider during analysis.

Merge semantics

When a per-call metadata argument is also provided, the two are shallow-merged with per-call winning on collision:

// globalMetadata: () => ({ user_id: "u_42", region: "us" })
auralog.info("impersonating session", { user_id: "u_99" });
// final metadata: { user_id: "u_99", region: "us" }

This lets a specific log line legitimately reference a different user (impersonation, admin actions) without mutating global state.

Failure modes

The SDK never crashes the host. If the supplier:

• throws — the entry ships without globalMetadata (per-call metadata is preserved). A single console.warn fires per logger instance; subsequent failures are silent.
• returns a thenable — same. Async suppliers are not supported; cache async state somewhere synchronously accessible.
• returns a non-serializable value (circular refs, BigInt, symbols) — same. The entry still ships with just per-call metadata.

Performance

The supplier runs on every log emission. Keep it O(1) — read from a cached variable, not a deep object walk or remote lookup.

Return value

init() returns an object with a flush method:

const { flush } = init({ apiKey: "aura_..." });

// Force-send all buffered logs
await flush();

Shutdown

Call shutdown() to flush remaining logs and clean up event listeners:

import { shutdown } from "auralog-sdk";

await shutdown();

This is important in serverless environments where the process may exit before the flush interval fires. See Environments for platform-specific guidance.