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