logquill 0.3.0 → 1.0.0

package/README.md

@@ -10,11 +10,12 @@ JSON log shape with its Python sibling, [`logquill`](https://pypi.org/project/lo
 (repo: `logquill-python`).
 
 Status: pre-release, under active development. The core `Logger`, level
-filtering, a full plugin pipeline (context/redaction/PII/tamper-evidence/
-sampling/alerting), `JSONFormatter`, and a broad transport catalog —
-console/file/HTTP, SQL, NoSQL, message queues, and cloud-native log
-platforms — are implemented; non-blocking async dispatch is not yet — see
-`CHANGELOG.md` for what's landed so far.
+filtering, non-blocking async dispatch with configurable backpressure, a
+full plugin pipeline (context/redaction/PII/tamper-evidence/sampling/
+alerting), `JSONFormatter`, a broad transport catalog — console/file/
+HTTP, SQL, NoSQL, message queues, and cloud-native log platforms — and a
+separate `logquill/browser` build are implemented; see `CHANGELOG.md` for
+what's landed so far.
 
 ## Features
 
@@ -26,7 +27,12 @@ platforms — are implemented; non-blocking async dispatch is not yet — see
 - **Child loggers** — `.child()` inherits level, transports, and plugins, and merges its own `meta` on top
 - **Typed throughout** — TypeScript strict mode, no `any` in the public API
 - **Dual package** — works via both `require()` (CJS) and `import` (ESM) from the same published package
-- *(planned)* non-blocking async dispatch, `AsyncLocalStorage`-based context propagation — see `CHANGELOG.md`
+- **Tracing & agentic logging** — `.thought()/.action()/.observation()/.decision()`, `Logger.span()` for nested/durationMs-stamped spans, `RunPlugin` (per-run id + step counter), and `TraceContextPlugin` (cross-service `traceId`, OTel-aware) — see [Tracing & agentic logging](#tracing--agentic-logging)
+- **LangChain.js / LangGraph.js adapter** — `LangChainAdapter`, a `BaseCallbackHandler` that maps chain/LLM/tool/agent events onto the calls above with zero manual instrumentation, from a separate `logquill/langchain` entry point — see [Agentic framework adapters](#agentic-framework-adapters)
+- **Non-blocking async dispatch** — a call returns before its write runs, via a bounded internal queue with a configurable backpressure policy (`dropOldest`/`dropNewest`/`block`); `logger.flush()`, `withLambda`/`withCloudFunction`/`withAzureFunction`, and `installShutdownHandlers` cover draining it before a process pauses or exits — see [Async dispatch & shutdown](#async-dispatch--shutdown)
+- **Request-scoped context propagation** — `bindContext()`, `AsyncLocalStorage`-backed, so a value set once is visible in every nested log call underneath it without threading it through every signature by hand; `RateLimitPlugin` caps a noisy loop without silencing everything else — see [Context propagation & error capture](#context-propagation--error-capture)
+- **Migration bridges** — `LogQuillWinstonTransport` (from `logquill/winston`) and `LogQuillPinoDestination` let an existing `winston`/`pino` app adopt LogQuill's transports/plugins with no call-site changes — see [Migration bridges](#migration-bridges)
+- **Browser build** — a separate `logquill/browser` entry (`Logger`, `JSONFormatter`, the plugin pipeline, `ConsoleTransport`, `BeaconTransport`) with no Node built-ins in its module graph — see [Browser build](#browser-build)
 
 ## Contents
 
@@ -42,6 +48,15 @@ platforms — are implemented; non-blocking async dispatch is not yet — see
   - [PII redaction](#pii-redaction)
   - [Tamper-evident logs](#tamper-evident-logs)
   - [Alerting](#alerting)
+  - [Rate limiting](#rate-limiting)
+- [Tracing & agentic logging](#tracing--agentic-logging)
+- [Agentic framework adapters](#agentic-framework-adapters)
+- [Async dispatch & shutdown](#async-dispatch--shutdown)
+  - [Kubernetes](#kubernetes)
+- [Context propagation & error capture](#context-propagation--error-capture)
+- [Migration bridges](#migration-bridges)
+- [Browser build](#browser-build)
+- [API reference](#api-reference)
 - [Development](#development)
 - [License](#license)
 
@@ -115,6 +130,7 @@ actually import; nothing is installed on your behalf.
 | Transport | Backend | Peer dependency | Setup |
 |---|---|---|---|
 | `ConsoleTransport` | stdout/stderr via `console.*` | *(none)* | zero-setup, isomorphic |
+| `BeaconTransport` | browser log endpoint, via `navigator.sendBeacon` | *(none, isomorphic)* | zero-setup — see [Browser build](#browser-build) |
 | `FileTransport` | local file, with rotation | *(none)* | zero-setup |
 | `HTTPTransport` | any HTTP log endpoint | *(none, uses `fetch`)* | zero-setup |
 | `SQLiteTransport` | SQLite | `better-sqlite3` | zero-setup (file or `:memory:`) |
@@ -502,6 +518,375 @@ logger.error("payment webhook failed", { orderId: "o-123" });
 inject a `sender`) follow the same shape. Write your own by extending
 `AlertingPlugin` and implementing `sendAlert(record, occurrences)`.
 
+### Rate limiting
+
+`RateLimitPlugin` drops records once a key — by default `(logger, level)`
+— exceeds `maxRecords` within a rolling `perSeconds` window, so a noisy
+loop (a retry logging the same error every iteration) can't drown out a
+logger's other messages. Each key gets its own window, so unrelated keys
+never reset in lockstep; pass `keyFunc` to key on something else, e.g. an
+error message or a `meta` field identifying the caller.
+
+```ts
+import { Logger, RateLimitPlugin } from "logquill";
+
+const logger = new Logger("app", { plugins: [new RateLimitPlugin(5, 60)] }); // at most 5 per key per minute
+
+for (let i = 0; i < 10; i++) {
+  logger.error("db connection failed"); // only the first 5 in any 60s window ship
+}
+```
+
+## Tracing & agentic logging
+
+`.thought()/.action()/.observation()/.decision()` are `.info()` with
+`meta.kind` pre-set, for tagging steps of an agent's reasoning loop:
+
+```ts
+import { Logger } from "logquill";
+
+const logger = new Logger("agent");
+logger.thought("deciding which tool to call", { candidates: ["search", "calculator"] });
+logger.action("calling search", { query: "current weather in nyc" });
+logger.observation("search returned 3 results");
+logger.decision("using search result #1");
+```
+
+`Logger.span()` wraps an operation, emitting one record on completion with
+`meta.spanId`/`meta.durationMs` — every record logged inside it, including
+across an `await`, is automatically stamped with `meta.parentSpanId`, so a
+full run's nesting can be reconstructed by sorting on `spanId`/`parentSpanId`.
+It still emits (at `ERROR`, with `meta.error`) and rethrows if the block
+throws:
+
+```ts
+import { Logger } from "logquill";
+
+async function callLlm(prompt: string): Promise<string> {
+  return `response to: ${prompt}`;
+}
+
+const logger = new Logger("agent");
+
+const answer = await logger.span(
+  "callLlm",
+  async () => {
+    logger.action("requesting completion", { model: "gpt-4" });
+    const response = await callLlm("current weather in nyc");
+    logger.observation("received completion");
+    return response;
+  },
+  { model: "gpt-4" },
+);
+```
+
+`RunPlugin` stamps `meta.runId` (generated, or given explicitly) plus an
+incrementing `meta.step` — attach a fresh instance per run so concurrent
+runs don't share a counter:
+
+```ts
+import { Logger, RunPlugin } from "logquill";
+
+const runLogger = new Logger("app").child("agent").use(new RunPlugin());
+runLogger.thought("step one"); // meta: { kind: "thought", runId: "...", step: 0 }
+runLogger.action("step two");  // meta: { kind: "action", runId: "...", step: 1 }
+```
+
+`TraceContextPlugin` stamps `meta.traceId`, for correlating one request
+across services — distinct from `runId`, which scopes one agent run. It
+resolves, in priority order: an active OpenTelemetry span (if
+`@opentelemetry/api` is installed — never a required dependency), an
+inbound `traceparent`/X-Ray/GCP trace header, or a freshly generated id:
+
+```ts
+import { Logger, setTraceparent, TraceContextPlugin } from "logquill";
+
+const logger = new Logger("app", { plugins: [new TraceContextPlugin()] });
+
+// in HTTP middleware, before the handler runs:
+const reset = setTraceparent(req.headers["traceparent"]);
+try {
+  logger.info("handling request"); // meta.traceId resolved from the inbound header
+} finally {
+  reset();
+}
+```
+
+## Agentic framework adapters
+
+`LangChainAdapter` implements LangChain.js's `BaseCallbackHandler`, mapping
+chain/LLM/tool/agent events onto `.action()/.observation()/.decision()` and
+`span()`-shaped records — pass it into `callbacks: [...]` and a chain's
+full call tree is captured with zero manual instrumentation:
+
+```ts
+import { RunnableLambda } from "@langchain/core/runnables";
+import { Logger, RunPlugin } from "logquill";
+import { LangChainAdapter } from "logquill/langchain";
+
+const logger = new Logger("agent").use(new RunPlugin());
+const handler = new LangChainAdapter(logger);
+
+const answerQuestion = RunnableLambda.from((question: string) => `answer: ${question}`);
+await answerQuestion.invoke("what is 2+2?", { callbacks: [handler] });
+// logs one record: { message: "RunnableLambda", meta: { kind: "span", spanId: "...", durationMs: ... } }
+```
+
+`LangGraphAdapter` is the same handler under its own name, for LangGraph.js
+graphs — its nodes run as ordinary LangChain `Runnable`s, so no extra
+mapping is needed; pass it the same way:
+
+```ts
+import { LangGraphAdapter } from "logquill/langchain";
+
+const handler = new LangGraphAdapter(logger);
+// const graph = builder.compile({ checkpointer });
+// await graph.invoke(input, { callbacks: [handler], configurable: { thread_id: "1" } });
+```
+
+This is a **separate entry point** — `import ... from "logquill/langchain"`,
+not the main `"logquill"` import — because `LangChainAdapter` has to
+`extends BaseCallbackHandler`, LangChain's own class. Importing plain
+`logquill` never touches `@langchain/core`; only importing
+`logquill/langchain` does. Install `@langchain/core` yourself (it's an
+optional peer dependency) — no separate `@langchain/langgraph` dependency
+is needed for `LangGraphAdapter`.
+
+## Async dispatch & shutdown
+
+Every `Logger` call returns before the write it triggers actually runs —
+the write (and any plugin `afterLog` hooks) is handed to an internal,
+bounded dispatch queue, drained outside the caller's own call stack:
+
+```ts
+import { CollectingTransport, Logger } from "logquill";
+
+const transport = new CollectingTransport();
+const logger = new Logger("app", { transports: [transport] });
+
+logger.info("hello");
+console.log(transport.records.length); // 0 — still queued
+await logger.flush();
+console.log(transport.records.length); // 1 — now written
+```
+
+The queue has a configurable size and backpressure policy, so a sustained
+burst can't grow memory without bound:
+
+```ts
+const logger = new Logger("app", {
+  transports: [transport],
+  queue: {
+    maxSize: 10_000, // default
+    policy: "dropOldest", // "dropOldest" (default) | "dropNewest" | "block"
+  },
+});
+```
+
+- `"dropOldest"` — once the queue is full, the longest-waiting record is
+  discarded to make room for the new one.
+- `"dropNewest"` — the incoming record is discarded; everything already
+  queued is left alone.
+- `"block"` — nothing is ever dropped: once the queue is full, a call runs
+  its write immediately, on the caller's own stack, instead of queueing it.
+
+Any dropped-record policy calls `onDrop(count, policy)` — rate-limited to
+once per `warnIntervalMs` (default 5000) — so sustained overload is
+visible without flooding your own logs with one warning per drop.
+
+`logger.flush()` waits for every record dispatched so far to reach its
+transports. Note it does *not* force a batching transport (SQL, a queue,
+`HTTPTransport`, ...) to send a batch still under its own threshold early
+— for that, use `withLambda`/`withCloudFunction`/`withAzureFunction`
+(same wrapper, three platform-matching names) around a serverless handler,
+which additionally forces every batching transport's buffer out before
+the wrapped function's result settles — important because a frozen or
+recycled execution environment may never come back to finish a partial
+batch on its own:
+
+```ts
+import { withLambda } from "logquill";
+
+export const handler = withLambda(logger, async (event) => {
+  logger.info("handling request", { requestId: event.requestId });
+  return { statusCode: 200 };
+});
+```
+
+For a long-running process, `installShutdownHandlers` flushes and closes a
+logger once on `SIGTERM`/`SIGINT`/`beforeExit`, so nothing queued is lost
+when the process stops:
+
+```ts
+import { installShutdownHandlers } from "logquill";
+
+installShutdownHandlers(logger); // Node only
+```
+
+### Kubernetes
+
+Default to `ConsoleTransport`, not `FileTransport`, for anything running in
+a container. A container's filesystem is ephemeral and invisible to the
+rest of the cluster — a log file written inside it disappears the moment
+the pod is rescheduled, and nothing aggregates it in the meantime unless
+you also run a sidecar to tail it back out. Writing to stdout/stderr
+instead costs nothing extra: every major container runtime already
+captures both streams, and the node-level log agent your cluster runs
+(Fluentd, Fluent Bit, Vector, or your cloud provider's own) ships them to
+your aggregator without any code on your side that needs to know that
+agent exists:
+
+```ts
+import { ConsoleTransport, Logger } from "logquill";
+
+const logger = new Logger("app", { transports: [new ConsoleTransport()] });
+```
+
+Kubernetes sends `SIGTERM` and then kills the process after
+`terminationGracePeriodSeconds` (30s by default) regardless of whether
+it's finished shutting down, so a record still sitting in the dispatch
+queue at that instant can be lost if nothing catches the signal.
+`installShutdownHandlers(logger)` closes that gap the same way
+`withLambda` closes it for a serverless freeze — call it once, on process
+start, so a pod that's told to stop still flushes and closes the logger
+before Kubernetes kills it.
+
+## Context propagation & error capture
+
+`bindContext()` merges values into a request-scoped context, backed by
+`AsyncLocalStorage`: every `Logger` call underneath it — through any
+number of function calls and `await`s deep — picks them up in `meta`
+automatically, without threading them through every signature by hand.
+Concurrent async operations sharing one `Logger` never see each other's
+bound context.
+
+```ts
+import { bindContext, Logger } from "logquill";
+
+const logger = new Logger("app");
+
+await bindContext({ requestId: "abc123" }, async () => {
+  await handleRequest(); // any logging in here, or in what it calls,
+                         // gets meta.requestId = "abc123" for free
+});
+
+function handleRequest() {
+  logger.info("handled"); // meta: { requestId: "abc123" }
+}
+```
+
+Nested `bindContext()` calls merge, with the inner value winning on key
+collision — the same way an explicit call-site `meta` value always wins
+over anything bound this way.
+
+Pass an `Error` as `meta.err` and it's replaced with a formatted
+`meta.stack`, the same shape `Logger.span()` already produces internally
+for a thrown error:
+
+```ts
+try {
+  await riskyOperation();
+} catch (err) {
+  logger.error("operation failed", { err, orderId: "o-123" });
+  // meta: { orderId: "o-123", stack: "Error: ...\n    at ..." } — no meta.err
+}
+```
+
+## Migration bridges
+
+For an app already using `winston` or `pino`, LogQuill can sit alongside
+either with no call-site changes, so a migration can happen transport by
+transport instead of all at once.
+
+`LogQuillWinstonTransport` (from the separate `logquill/winston` entry
+point, since it has to extend `winston-transport`'s own class) plugs a
+LogQuill `Logger` into an existing `winston.createLogger()` as one more
+transport:
+
+```ts
+import winston from "winston";
+import { Logger } from "logquill";
+import { LogQuillWinstonTransport } from "logquill/winston";
+
+const logquill = new Logger("app");
+const winstonLogger = winston.createLogger({
+  transports: [new LogQuillWinstonTransport(logquill)],
+});
+
+winstonLogger.info("still works exactly as before", { userId: 42 });
+```
+
+`LogQuillPinoDestination` is a pino `destination` — pass it straight into
+`pino()` and pino's own NDJSON output is parsed back into LogQuill calls.
+It needs no dependency on `pino` itself (a destination only has to be
+duck-type compatible with a Node `Writable`), so it ships from the main
+entry point:
+
+```ts
+import pino from "pino";
+import { Logger, LogQuillPinoDestination } from "logquill";
+
+const logquill = new Logger("app");
+const log = pino(new LogQuillPinoDestination(logquill));
+
+log.info({ userId: 42 }, "still works exactly as before");
+```
+
+Both re-filter by the LogQuill `Logger`'s own `level` after the
+source library's own filtering runs — the stricter of the two wins — and
+map that library's levels onto LogQuill's via a `levelMap` option,
+overridable for a non-default level configuration.
+
+## Browser build
+
+`import ... from "logquill/browser"` is a separate entry point shipping
+the same `Logger`, levels, `JSONFormatter`, and plugin pipeline
+(`ContextPlugin`/`RedactPlugin`/`PIIRedactPlugin`/`SamplingPlugin`), plus
+`ConsoleTransport` and `BeaconTransport`. `FileTransport`, `HTTPTransport`,
+every SQL/NoSQL/queue/cloud-native transport, and the LangChain adapters
+are absent from this entry's module graph entirely — not tree-shaken,
+simply never imported — so this bundle never pulls in a Node built-in.
+
+```ts
+import { BeaconTransport, ConsoleTransport, Logger } from "logquill/browser";
+
+const logger = new Logger("app", {
+  transports: [
+    new ConsoleTransport(),
+    new BeaconTransport("https://logs.example.com/ingest", { batchSize: 20 }),
+  ],
+});
+
+logger.info("page loaded", { path: location.pathname });
+window.addEventListener("pagehide", () => logger.close()); // flushes the pending beacon batch
+```
+
+`BeaconTransport` batches formatted records and sends them via
+`navigator.sendBeacon`, which — unlike `fetch` — can complete even after
+the page that queued it starts unloading; it falls back to a `keepalive`
+`fetch` where `sendBeacon` isn't available (a worker, an older browser).
+Keep `batchSize` small — `sendBeacon` payloads are capped (64KB in most
+browsers).
+
+One behavioral difference from the Node build: `Logger.span()`'s
+`parentSpanId` nesting is backed by a plain stack here instead of
+`AsyncLocalStorage` (which browsers don't have), so two spans on the same
+`Logger` running concurrently across an `await` can interleave and stamp
+the wrong `parentSpanId` — fine for the common case of one span in flight
+at a time.
+
+## API reference
+
+Every exported class and function carries a TSDoc comment; the full
+reference, generated from those comments with
+[TypeDoc](https://typedoc.org), is published at
+[nikhilvdev.github.io/logquill-js](https://nikhilvdev.github.io/logquill-js/)
+and rebuilt on every push to `main`. To build it locally:
+
+```sh
+npm run docs   # writes static HTML to site/
+```
+
 ## Development
 
 ```sh
@@ -510,6 +895,7 @@ npm run build      # dist/index.{mjs,cjs,d.ts} via tsup
 npm run lint        # eslint
 npm run typecheck   # tsc --noEmit
 npm run coverage    # vitest run --coverage
+npm run docs        # typedoc -> site/
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the PR workflow, the