auralogs-sdk

JavaScript/TypeScript SDK for Auralogs — agentic logging and application awareness.

Auralogs acts as an on-call engineer — powered by your choice of model (Claude, OpenAI, or any MCP-compatible LLM) — monitoring your logs and errors, alerting you when something's wrong, and opening fix PRs automatically.

Install

npm install auralogs-sdk

Quick start

import { auralogs, init } from "auralogs-sdk";

init({
  apiKey: process.env.AURALOG_API_KEY!,
  environment: "production",
  captureConsole: true,  // forward console.* to Auralogs
  captureErrors: true,   // capture uncaught errors (default: true)
});

auralogs.info("user signed in", { userId: "123" });
auralogs.error("payment failed", { orderId: "abc" });

Configuration

Option	Type	Default	Description
apiKey	string	required	Your Auralogs project API key
environment	string	required	e.g. "production", "staging", "dev"
endpoint	string	https://ingest.auralogs.ai	Ingest endpoint override. Must be https:// unless allowInsecureEndpoint is set.
allowInsecureEndpoint	boolean	false	Permit http:// endpoints (e.g. http://localhost:8080 for local dev). Off by default — a plaintext endpoint would leak the API key on the wire.
flushInterval	number	5000	Ms between batched flushes
maxQueueSize	number	1000	Max buffered log entries before the SDK drops the oldest. Bounds memory if the ingest endpoint is unreachable.
captureConsole	boolean	false	Forward console.* calls
captureErrors	boolean	true	Capture uncaught errors and unhandled rejections
traceId	string	auto-generated	Custom trace ID for distributed tracing
globalMetadata	Record<string, unknown> or () => Record<string, unknown>	undefined	Baseline metadata merged into every log entry — including captureConsole and captureErrors entries. Per-call metadata wins on key collision (shallow merge).

Attaching session-scoped fields to every log

Use globalMetadata to attach things like user_id, org id, or feature-flag snapshots to every log Auralogs emits — including console.* captures and uncaught errors. The supplier form is the canonical recipe because it's evaluated at log time, so it always sees the current host state:

import { auralogs, init } from "auralogs-sdk";

init({
  apiKey: process.env.AURALOG_API_KEY!,
  environment: "production",
  captureConsole: true,
  captureErrors: true,
  globalMetadata: () => ({
    user_id: currentUser?.id,
    org_id: currentUser?.orgId,
  }),
});

auralogs.info("checkout started");
// metadata: { user_id: "...", org_id: "..." }

auralogs.info("admin impersonating", { user_id: "impersonated-id" });
// per-call wins: { user_id: "impersonated-id", org_id: "..." }

A few caveats:

• Sync only. The supplier must return synchronously. If it returns a Promise (or any thenable), Auralogs drops globalMetadata for that entry, warns once, and ships the entry without it. Cache async state on the sync side (e.g. in a context-local) before reading it here.
• Keep it cheap. The supplier runs on every log emission. Avoid I/O or expensive computation.
• If it throws or produces a non-serializable value, the entry is still delivered — just without globalMetadata. Auralogs warns once per logger instance and stays silent thereafter.

Graceful shutdown

import { shutdown } from "auralogs-sdk";

process.on("SIGTERM", async () => {
  await shutdown();  // flushes pending logs
  process.exit(0);
});

Documentation

Full docs at docs.auralogs.ai.

Verify this package

Every release is published with sigstore provenance attestations built directly in GitHub Actions. The attestation proves the tarball was built from a specific commit in this repository via .github/workflows/release.yml — without having to trust npm or the maintainer.

To verify in your own project:

npm audit signatures

Or inspect the attestation on npmjs.com/package/auralogs-sdk under "Provenance".

Security

Found a vulnerability? See SECURITY.md for how to report it.

License

MIT © James Thomas