logquill 0.3.0 → 0.4.0

package/README.md

@@ -26,7 +26,9 @@ 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)
+- *(planned)* non-blocking async dispatch, `AsyncLocalStorage`-based general context propagation — see `CHANGELOG.md`
 
 ## Contents
 
@@ -42,6 +44,8 @@ platforms — are implemented; non-blocking async dispatch is not yet — see
   - [PII redaction](#pii-redaction)
   - [Tamper-evident logs](#tamper-evident-logs)
   - [Alerting](#alerting)
+- [Tracing & agentic logging](#tracing--agentic-logging)
+- [Agentic framework adapters](#agentic-framework-adapters)
 - [Development](#development)
 - [License](#license)
 
@@ -502,6 +506,121 @@ 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)`.
 
+## 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`.
+
 ## Development
 
 ```sh

package/dist/index.cjs

@@ -1,10 +1,13 @@
 'use strict';
 
 var crypto = require('crypto');
+var async_hooks = require('async_hooks');
+var module$1 = require('module');
 var zlib = require('zlib');
 var fs = require('fs');
 var path = require('path');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 // src/core/levels.ts
 var Level = /* @__PURE__ */ ((Level2) => {
   Level2[Level2["TRACE"] = 5] = "TRACE";
@@ -82,6 +85,99 @@ var ContextPlugin = class {
     return { ...record, meta: { ...this.context, ...record.meta } };
   }
 };
+var RunPlugin = class {
+  runId;
+  step = 0;
+  constructor(options = {}) {
+    this.runId = options.runId ?? crypto.randomUUID();
+  }
+  beforeLog(record) {
+    record.meta.runId ??= this.runId;
+    record.meta.step = this.step++;
+    return record;
+  }
+};
+var traceparentStore = new async_hooks.AsyncLocalStorage();
+function setTraceparent(value) {
+  const previous = traceparentStore.getStore();
+  traceparentStore.enterWith(value);
+  return () => {
+    traceparentStore.enterWith(previous);
+  };
+}
+function getTraceparent() {
+  return traceparentStore.getStore();
+}
+function generateTraceId() {
+  return crypto.randomBytes(16).toString("hex");
+}
+var W3C_TRACEPARENT_RE = /^[0-9a-f]{2}-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$/;
+var XRAY_ROOT_RE = /Root=1-([0-9a-f]{8})-([0-9a-f]{24})/;
+var GCP_TRACE_RE = /^([0-9a-f]{32})\/\d+(;o=\d)?$/;
+function parseTraceHeader(header) {
+  const trimmed = header.trim();
+  const w3c = W3C_TRACEPARENT_RE.exec(trimmed);
+  if (w3c?.[1]) {
+    return w3c[1];
+  }
+  const xray = XRAY_ROOT_RE.exec(trimmed);
+  if (xray?.[1] && xray[2]) {
+    return xray[1] + xray[2];
+  }
+  const gcp = GCP_TRACE_RE.exec(trimmed);
+  if (gcp?.[1]) {
+    return gcp[1];
+  }
+  return void 0;
+}
+function defaultResolveActiveOtelTraceId() {
+  try {
+    const require2 = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+    const otel = require2("@opentelemetry/api");
+    const span = otel.trace.getActiveSpan();
+    if (!span) {
+      return void 0;
+    }
+    const spanContext = span.spanContext();
+    if (!otel.trace.isSpanContextValid(spanContext)) {
+      return void 0;
+    }
+    return spanContext.traceId;
+  } catch {
+    return void 0;
+  }
+}
+var TraceContextPlugin = class {
+  traceKey;
+  explicitTraceparent;
+  resolveActiveOtelTraceId;
+  constructor(options = {}) {
+    this.traceKey = options.traceKey ?? "traceId";
+    this.explicitTraceparent = options.traceparent;
+    this.resolveActiveOtelTraceId = options.resolveActiveOtelTraceId ?? defaultResolveActiveOtelTraceId;
+  }
+  beforeLog(record) {
+    if (record.meta[this.traceKey] != null) {
+      return record;
+    }
+    record.meta[this.traceKey] = this.resolveTraceId();
+    return record;
+  }
+  resolveTraceId() {
+    const fromOtel = this.resolveActiveOtelTraceId();
+    if (fromOtel) {
+      return fromOtel;
+    }
+    const header = this.explicitTraceparent ?? getTraceparent();
+    if (header) {
+      const parsed = parseTraceHeader(header);
+      if (parsed) {
+        return parsed;
+      }
+    }
+    return generateTraceId();
+  }
+};
 
 // src/plugins/redact-plugin.ts
 var DEFAULT_REDACTED_KEYS = ["password", "token", "secret", "api_key", "authorization"];
@@ -1710,8 +1806,24 @@ var HTTPTransport = class extends Transport {
     this.flush();
   }
 };
+var spanIdStore = new async_hooks.AsyncLocalStorage();
+function currentSpanId() {
+  return spanIdStore.getStore();
+}
+function newSpanId() {
+  return crypto.randomBytes(8).toString("hex");
+}
+function runInSpan(spanId, fn) {
+  return spanIdStore.run(spanId, fn);
+}
 
 // src/core/logger.ts
+function formatSpanError(error) {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  return String(error);
+}
 var Logger = class _Logger {
   name;
   transports;
@@ -1775,6 +1887,10 @@ var Logger = class _Logger {
       message,
       meta: { ...this.baseMeta, ...meta }
     });
+    const parentSpanId = currentSpanId();
+    if (parentSpanId !== void 0) {
+      record.meta.parentSpanId ??= parentSpanId;
+    }
     for (const plugin of this.plugins) {
       let result;
       try {
@@ -1789,7 +1905,11 @@ var Logger = class _Logger {
       record = result;
     }
     for (const transport of this.transports) {
-      transport.write(transport.format(record), record);
+      try {
+        transport.write(transport.format(record), record);
+      } catch (error) {
+        console.error(`${transport.constructor.name}: failed to write a log record`, error);
+      }
     }
     for (const plugin of this.plugins) {
       try {
@@ -1818,6 +1938,66 @@ var Logger = class _Logger {
   fatal(message, meta = {}) {
     return this.dispatch(50 /* FATAL */, message, meta);
   }
+  /** `.info()` tagged `meta.kind = "thought"` — an agent's internal reasoning step, for harness/agentic tracing. */
+  thought(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "thought", ...meta });
+  }
+  /** `.info()` tagged `meta.kind = "action"` — an agent taking an action (a tool call, an LLM request), for harness/agentic tracing. */
+  action(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "action", ...meta });
+  }
+  /** `.info()` tagged `meta.kind = "observation"` — the result an agent observed from an action, for harness/agentic tracing. */
+  observation(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "observation", ...meta });
+  }
+  /** `.info()` tagged `meta.kind = "decision"` — an agent's concluding decision for a step or run, for harness/agentic tracing. */
+  decision(message, meta = {}) {
+    return this.dispatch(20 /* INFO */, message, { kind: "decision", ...meta });
+  }
+  /**
+   * `await logger.span("callLlm", async () => {...})` — runs `fn`, and on
+   * settling (success or throw) emits one record for the span itself
+   * carrying `meta.spanId` and `meta.durationMs`. Every record logged
+   * inside `fn` — through any method, and through any further `await` —
+   * is automatically stamped with `meta.parentSpanId` pointing at this
+   * span, so nested/sub-agent calls reconstruct their exact nesting when
+   * sorted by `spanId`/`parentSpanId`.
+   *
+   * Still emits its record — at `ERROR`, with `meta.error` set — if `fn`
+   * throws; the error itself propagates unchanged to the caller.
+   *
+   * `spanId`/`parentSpanId` normally auto-generate/auto-nest; pass them in
+   * `options` to adopt an id handed in from elsewhere (e.g. a framework
+   * adapter translating an id it already received).
+   */
+  async span(name, fn, options = {}) {
+    const { spanId: explicitSpanId, parentSpanId: explicitParentSpanId, ...meta } = options;
+    const spanId = explicitSpanId ?? newSpanId();
+    const start = performance.now();
+    try {
+      const result = await runInSpan(spanId, () => fn());
+      this.finishSpan(name, spanId, explicitParentSpanId, performance.now() - start, meta);
+      return result;
+    } catch (error) {
+      this.finishSpan(name, spanId, explicitParentSpanId, performance.now() - start, meta, error);
+      throw error;
+    }
+  }
+  finishSpan(name, spanId, explicitParentSpanId, durationMs, meta, error) {
+    const fullMeta = {
+      spanId,
+      durationMs: Math.round(durationMs * 1e3) / 1e3,
+      ...meta
+    };
+    if (explicitParentSpanId !== void 0) {
+      fullMeta.parentSpanId = explicitParentSpanId;
+    }
+    fullMeta.kind ??= "span";
+    if (error !== void 0) {
+      fullMeta.error = formatSpanError(error);
+    }
+    this.dispatch(error !== void 0 ? 40 /* ERROR */ : 20 /* INFO */, name, fullMeta);
+  }
 };
 
 // src/index.ts
@@ -1857,16 +2037,23 @@ exports.PubSubTransport = PubSubTransport;
 exports.RabbitMQTransport = RabbitMQTransport;
 exports.RedactPlugin = RedactPlugin;
 exports.RedisTransport = RedisTransport;
+exports.RunPlugin = RunPlugin;
 exports.SQLiteTransport = SQLiteTransport;
 exports.SQSTransport = SQSTransport;
 exports.SamplingPlugin = SamplingPlugin;
 exports.SlackAlertPlugin = SlackAlertPlugin;
 exports.TamperEvidentPlugin = TamperEvidentPlugin;
+exports.TraceContextPlugin = TraceContextPlugin;
 exports.Transport = Transport;
 exports.VERSION = VERSION;
 exports.createRecord = createRecord;
+exports.defaultResolveActiveOtelTraceId = defaultResolveActiveOtelTraceId;
+exports.generateTraceId = generateTraceId;
+exports.getTraceparent = getTraceparent;
 exports.levelName = levelName;
 exports.parseLevel = parseLevel;
+exports.parseTraceHeader = parseTraceHeader;
+exports.setTraceparent = setTraceparent;
 exports.utcTimestamp = utcTimestamp;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map