@almanac-ai/agentlogs-node

Structured local logs your coding agent can read — the Node/Express SDK. Writes the same JSONL contract as the Python SDK and the CLI, so one trace stitches your whole stack together. See the repo root and contract.

npm install @almanac-ai/agentlogs-node

Use

import { logger, agentMiddleware, loggedFetch } from "@almanac-ai/agentlogs-node";

// Express — per-request trace context + request.completed
app.use(agentMiddleware({ service: "backend" }));

const log = logger("pages");
log.info("publish.started", { pageId });

await log.time("publish", { pageId }, async () => {   // → publish.completed + duration_ms
  await savePage(pageId);
});

// outbound calls carry the trace and log fetch lifecycle events
await loggedFetch("https://payments.internal/charge", { method: "POST" });

Non-HTTP work (a worker, a script):

import { startTrace, logger } from "@almanac-ai/agentlogs-node";
const log = logger("sync");
await startTrace("nightly-sync", async () => {
  log.info("sync.started");
});

API

| Export | Does | |---|---| | logger(name) | a logger for one area of code | | log.debug/info/warn/error(event, fields?) | emit a structured event | | log.time(name, fields?, fn) | time an async/sync block | | agentMiddleware({ service }) | Express/Connect per-request trace context | | loggedFetch(url, init?) | fetch that propagates the trace and logs fetch lifecycle events | | startTrace(name, fn) | begin a trace outside HTTP | | configure({ service, file, enabled, environment }) | global config | | buildTraceparent / parseTraceparent | W3C header helpers |

Config

On by default → ~/.agentlogs/app.log. AGENTLOGS=0 disables; AGENTLOGS_FILE overrides the path (contained to ~/.agentlogs/ or temp). Trace context uses AsyncLocalStorage, so logs inside a request or startTrace/time block carry the right ids without you passing anything.

For the browser/React side — LoggingProvider, browser loggedFetch, and the ingest route — see @almanac-ai/agentlogs-next.

Develop

npm install
npm run test:node
npm run build