argsbarg 6.1.8 → 6.1.9

package/index.d.ts

@@ -113,6 +113,59 @@ export declare class CliContext {
 	private _posMap;
 	private _positionalMap;
 }
+/** ECS version string written to every JSON log line. */
+export declare const ECS_VERSION = "8.11.0";
+/** Severity label for ECS `log.level`. */
+export type EcsLogLevel = "debug" | "info" | "warn" | "error";
+/** Fields merged into every ECS log line. */
+export interface EcsServiceFields {
+	name: string;
+	version: string;
+}
+/** Context for {@link CliLogConfig.enrich} and {@link CliLogConfig.serialize}. */
+export interface LogEnrichContext {
+	level: EcsLogLevel;
+	message: string;
+	action?: string;
+	requestId?: string;
+	traceId?: string;
+	spanId?: string;
+	labels?: Record<string, string | number | boolean>;
+	error?: unknown;
+	service: EcsServiceFields;
+	http?: {
+		method: string;
+		path: string;
+		status: number;
+		durationMs: number;
+		clientIp?: string;
+	};
+}
+/** Input for one ECS log event. */
+export interface EcsLogEvent {
+	level: EcsLogLevel;
+	message: string;
+	action?: string;
+	labels?: Record<string, string | number | boolean>;
+	error?: unknown;
+	fields?: Record<string, unknown>;
+	requestId?: string;
+	traceId?: string;
+	spanId?: string;
+	/** Populated on HTTP/MCP access log events for {@link CliLogConfig.enrich}. */
+	http?: LogEnrichContext["http"];
+}
+/** Options for {@link formatEcsLine}. */
+export interface FormatEcsLineOpts {
+	service: EcsServiceFields;
+	event: EcsLogEvent;
+	/** Additive fields merged after the ECS baseline (cannot override protected keys). */
+	enrich?: (ctx: LogEnrichContext) => Record<string, unknown>;
+}
+/** Formats one ECS Logging–compatible JSON log line (newline omitted). */
+export declare function formatEcsLine(opts: FormatEcsLineOpts): string;
+/** @deprecated Pass {@link FormatEcsLineOpts} instead. */
+export declare function formatEcsLine(service: EcsServiceFields, event: EcsLogEvent): string;
 /**
  * How a leaf handler was dispatched.
  */
@@ -324,6 +377,10 @@ export interface CliHttpWireContext {
 	clientIp: string;
 	path: string;
 	method: string;
+	/** W3C trace id when `traceparent` is present on the request. */
+	traceId?: string;
+	/** Span id for this server hop when `traceparent` is present. */
+	spanId?: string;
 }
 /** Wire-level MCP hooks on JSON-RPC messages (observe-only). */
 export interface CliMcpWireHooks {
@@ -672,6 +729,8 @@ export interface InvokeHookContext {
 		request: Request;
 		clientIp: string;
 		requestId: string;
+		traceId?: string;
+		spanId?: string;
 	};
 	mcp?: {
 		rpcMethod: string;
@@ -717,9 +776,9 @@ export interface ReadinessContext {
 	appConfig: AnyAppConfigSnapshot;
 	runtime: ServerRuntime;
 }
-/** Framework logging defaults (ECS json or human text on stderr). */
+/** Framework logging defaults (ECS Logging json or human text on stderr). */
 export interface CliLogConfig {
-	/** `json` = ECS lines; `text` = human stderr lines. Default: `json`. */
+	/** `json` = ECS Logging lines; `text` = human stderr lines. Default: `json`. */
 	format?: "json" | "text";
 	/** Tee stderr + append; relative paths resolve under the app config dir. */
 	file?: string;
@@ -727,6 +786,16 @@ export interface CliLogConfig {
 	access?: boolean;
 	/** Emit error events after the hook pipeline. Default: true. */
 	errors?: boolean;
+	/**
+	 * Add non-standard fields to each JSON log line after the ECS baseline.
+	 * Cannot override `@timestamp`, `log.level`, `message`, `ecs.version`, or service fields.
+	 */
+	enrich?: (ctx: LogEnrichContext) => Record<string, unknown>;
+	/**
+	 * Full control over JSON log line serialization. When set, bypasses the built-in ECS formatter.
+	 * The consumer owns the entire line (including newline omission).
+	 */
+	serialize?: (ctx: LogEnrichContext) => string;
 }
 /**
  * Program root passed to {@link Cli}.
@@ -870,17 +939,6 @@ export interface CliSchemaRootExport extends CliSchemaExport {
 	/** Program-level error JSON Schema when configured on `httpServer.errors` or `mcpServer.errors`. */
 	errorSchema?: Record<string, unknown>;
 }
-/** Severity label for ECS `log.level`. */
-export type EcsLogLevel = "debug" | "info" | "warn" | "error";
-/** Input for one ECS log event. */
-export interface EcsLogEvent {
-	level: EcsLogLevel;
-	message: string;
-	action?: string;
-	labels?: Record<string, string | number | boolean>;
-	error?: unknown;
-	fields?: Record<string, unknown>;
-}
 /** Resolved logging options for a server or invoke session. */
 export interface ResolvedLogConfig {
 	format: "json" | "text";
@@ -888,6 +946,8 @@ export interface ResolvedLogConfig {
 	access: boolean;
 	errors: boolean;
 	dev: boolean;
+	enrich?: CliLogConfig["enrich"];
+	serialize?: CliLogConfig["serialize"];
 }
 /** Options for {@link LogEmitter}. */
 export interface LogEmitterOpts {
@@ -911,10 +971,18 @@ declare class LogEmitter {
 		durationMs: number;
 		requestId?: string;
 		clientIp?: string;
+		traceId?: string;
+		spanId?: string;
 	}): void;
 	/** Error log after the hook pipeline (real stack always included). */
-	emitInvokeError(failureKind: string, error: unknown, clientMessage: string, labels?: Record<string, string | number | boolean>): void;
+	emitInvokeError(failureKind: string, error: unknown, clientMessage: string, meta?: {
+		labels?: Record<string, string | number | boolean>;
+		requestId?: string;
+		traceId?: string;
+		spanId?: string;
+	}): void;
 	private formatLine;
+	private buildEnrichContext;
 	private formatTextLine;
 	private appendFile;
 }
@@ -996,6 +1064,8 @@ export declare class Cli {
 			request: Request;
 			clientIp: string;
 			requestId: string;
+			traceId?: string;
+			spanId?: string;
 		};
 		mcp?: {
 			rpcMethod: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "6.1.8",
+  "version": "6.1.9",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/builtins/http.ts

@@ -18,7 +18,7 @@ const HTTP_SERVE_OPTIONS: CliOption[] = [
   { name: "obscure-errors", description: "Hide unexpected errors from clients.", kind: CliOptionKind.Presence },
   {
     name: "log-format",
-    description: "Log format: json (ECS) or text.",
+    description: "Log format: json (ECS Logging) or text.",
     kind: CliOptionKind.Enum,
     choices: ["json", "text"],
   },

package/src/builtins/mcp.ts

@@ -13,7 +13,7 @@ const MCP_SERVE_OPTIONS: CliOption[] = [
   { name: "obscure-errors", description: "Hide unexpected errors from clients.", kind: CliOptionKind.Presence },
   {
     name: "log-format",
-    description: "Log format: json (ECS) or text.",
+    description: "Log format: json (ECS Logging) or text.",
     kind: CliOptionKind.Enum,
     choices: ["json", "text"],
   },

package/src/core/types.ts

@@ -219,6 +219,10 @@ export interface CliHttpWireContext {
   clientIp: string;
   path: string;
   method: string;
+  /** W3C trace id when `traceparent` is present on the request. */
+  traceId?: string;
+  /** Span id for this server hop when `traceparent` is present. */
+  spanId?: string;
 }
 
 /** Wire-level MCP hooks on JSON-RPC messages (observe-only). */
@@ -596,7 +600,7 @@ export interface InvokeHookContext {
   locals: CliLocals;
   runtime?: ServerRuntime;
   appConfig: AnyAppConfigSnapshot;
-  http?: { request: Request; clientIp: string; requestId: string };
+  http?: { request: Request; clientIp: string; requestId: string; traceId?: string; spanId?: string };
   mcp?: { rpcMethod: string; toolName?: string; requestId: string };
 }
 
@@ -641,9 +645,9 @@ export interface ReadinessContext {
   runtime: ServerRuntime;
 }
 
-/** Framework logging defaults (ECS json or human text on stderr). */
+/** Framework logging defaults (ECS Logging json or human text on stderr). */
 export interface CliLogConfig {
-  /** `json` = ECS lines; `text` = human stderr lines. Default: `json`. */
+  /** `json` = ECS Logging lines; `text` = human stderr lines. Default: `json`. */
   format?: "json" | "text";
   /** Tee stderr + append; relative paths resolve under the app config dir. */
   file?: string;
@@ -651,6 +655,16 @@ export interface CliLogConfig {
   access?: boolean;
   /** Emit error events after the hook pipeline. Default: true. */
   errors?: boolean;
+  /**
+   * Add non-standard fields to each JSON log line after the ECS baseline.
+   * Cannot override `@timestamp`, `log.level`, `message`, `ecs.version`, or service fields.
+   */
+  enrich?: (ctx: import("../log/ecs.ts").LogEnrichContext) => Record<string, unknown>;
+  /**
+   * Full control over JSON log line serialization. When set, bypasses the built-in ECS formatter.
+   * The consumer owns the entire line (including newline omission).
+   */
+  serialize?: (ctx: import("../log/ecs.ts").LogEnrichContext) => string;
 }
 
 /**

package/src/docs/http-guide.ts

@@ -80,6 +80,16 @@ export function generateHttpGuide(root: CliProgram): string {
     "",
     'Errors use `{ "error": "..." }` with `400`, `404`, `503`, or `500`.',
     "",
+    "## Logging",
+    "",
+    "Server logs go to **stderr** (one JSON object per line by default).",
+    "",
+    "- Configure with `program.log` on the program root",
+    "- **`enrich`** — add custom JSON fields on top of the default line",
+    "- **`serialize`** — replace the formatter and emit your own line shape",
+    "",
+    "See the argsbarg [logging guide](https://github.com/bdombro/bun-argsbarg/blob/main/docs/logging.md) for examples and the full `LogEnrichContext` shape.",
+    "",
   ];
 
   if (root.appConfig?.entries && Object.keys(root.appConfig.entries).length > 0) {

package/src/headless/tool-call.ts

@@ -139,7 +139,7 @@ export async function executeHttpRouteCall(
   pathParams: Record<string, string>,
   query: Record<string, string>,
   body: Record<string, unknown>,
-  http?: { request: Request; clientIp: string; requestId: string },
+  http?: { request: Request; clientIp: string; requestId: string; traceId?: string; spanId?: string },
 ): Promise<HeadlessToolCallResult> {
   const argvResult = httpRequestToArgv(cli.program, route, pathParams, query, body);
   if ("error" in argvResult) {

package/src/hooks/run.ts

@@ -134,8 +134,13 @@ export async function runErrorPipeline(
     failureKind === "unexpected" && obscureUnexpected ? obscureUnexpectedClientMessage() : clientError.message;
 
   emitter?.emitInvokeError(failureKind, err, displayMessage, {
-    invocation: hookCtx.invocation,
-    path: hookCtx.path.join(" "),
+    labels: {
+      invocation: hookCtx.invocation,
+      path: hookCtx.path.join(" "),
+    },
+    requestId: hookCtx.locals.requestId,
+    traceId: hookCtx.http?.traceId,
+    spanId: hookCtx.http?.spanId,
   });
 
   return { failureKind, clientError, errorMsg: displayMessage };

package/src/http/server.ts

@@ -9,6 +9,7 @@ import {
   headlessFailureToHttpResponse,
   headlessSuccessToHttpResponse,
 } from "../headless/tool-call.ts";
+import { extractTraceContext, formatTraceparent } from "../log/trace.ts";
 import type { Cli } from "../runtime/cli.ts";
 import { leafHttpResponseDefaults } from "../runtime/exposure.ts";
 import type { ResolvedHttpServeConfig } from "../server/overrides.ts";
@@ -70,12 +71,14 @@ export async function handleApiRequest(
   const requestId = randomUUID();
   const url = new URL(request.url);
   const clientIp = resolveClientIp(request, trustProxy);
+  const trace = extractTraceContext(request);
   const wireCtx: CliHttpWireContext = {
     request,
     requestId,
     clientIp,
     path: url.pathname,
     method: request.method,
+    ...(trace ? { traceId: trace.traceId, spanId: trace.spanId } : {}),
   };
   const hooks = cli.server?.httpHooks ?? cli.program.httpServer?.hooks;
   const emitter = cli.server?.emitter;
@@ -99,8 +102,22 @@ export async function handleApiRequest(
       durationMs,
       requestId,
       clientIp,
+      traceId: trace?.traceId,
+      spanId: trace?.spanId,
+    });
+    if (!trace) {
+      return response;
+    }
+    const headers = new Headers(response.headers);
+    headers.set(
+      "traceparent",
+      formatTraceparent({ traceId: trace.traceId, spanId: trace.spanId, sampled: trace.sampled }),
+    );
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
     });
-    return response;
   };
 
   await hooks?.onRequest?.(wireCtx);
@@ -168,6 +185,7 @@ export async function handleApiRequest(
       request,
       clientIp,
       requestId,
+      ...(trace ? { traceId: trace.traceId, spanId: trace.spanId } : {}),
     });
     if (result.ok) {
       const leafHttp = leafHttpResponseDefaults(match.route.leaf);

package/src/index.ts

@@ -79,6 +79,8 @@ export {
   wantsExplicitJson,
 } from "./headless/routing.ts";
 export { generateOpenApi, openApiJson } from "./http/openapi.ts";
+export type { EcsLogEvent, LogEnrichContext } from "./log/ecs.ts";
+export { ECS_VERSION, formatEcsLine } from "./log/ecs.ts";
 export type { McpBundlePaths, PackMcpBundleOpts } from "./mcp/bundle.ts";
 export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
 export { Cli, type CliInvokeKind, type CliInvokeResult } from "./runtime/cli.ts";

package/src/log/ecs.test.ts

@@ -3,10 +3,10 @@ Unit tests for ECS log line formatting.
 */
 
 import { describe, expect, test } from "bun:test";
-import { formatEcsLine } from "./ecs.ts";
+import { ECS_VERSION, formatEcsLine, mergeEnrichFields, PROTECTED_ECS_KEYS } from "./ecs.ts";
 
 describe("formatEcsLine", () => {
-  test("includes service fields and event action", () => {
+  test("includes ECS Logging baseline fields", () => {
     const line = formatEcsLine(
       { name: "myapp", version: "7.0.0" },
       {
@@ -21,9 +21,49 @@ describe("formatEcsLine", () => {
     expect(parsed["event.action"]).toBe("http.server.start");
     expect(parsed.message).toBe("HTTP API listening");
     expect(parsed["log.level"]).toBe("info");
+    expect(parsed["ecs.version"]).toBe(ECS_VERSION);
     expect(typeof parsed["@timestamp"]).toBe("string");
   });
 
+  test("nests labels object instead of flattening", () => {
+    const line = formatEcsLine(
+      { name: "app", version: "1.0.0" },
+      {
+        level: "info",
+        message: "ok",
+        labels: { request_id: "abc", team: "demo" },
+      },
+    );
+    const parsed = JSON.parse(line) as Record<string, unknown>;
+    expect(parsed.labels).toEqual({ request_id: "abc", team: "demo" });
+    expect(parsed["labels.request_id"]).toBeUndefined();
+  });
+
+  test("includes trace and canonical http fields", () => {
+    const line = formatEcsLine(
+      { name: "app", version: "1.0.0" },
+      {
+        level: "info",
+        message: "GET /workspaces",
+        action: "http.access",
+        traceId: "0af7651916cd43dd8448eb211c80319c",
+        spanId: "b7ad6b7169203331",
+        fields: {
+          "http.request.method": "GET",
+          "url.path": "/workspaces",
+          "http.response.status_code": 200,
+          "event.duration": 45_000_000,
+        },
+      },
+    );
+    const parsed = JSON.parse(line) as Record<string, unknown>;
+    expect(parsed["trace.id"]).toBe("0af7651916cd43dd8448eb211c80319c");
+    expect(parsed["span.id"]).toBe("b7ad6b7169203331");
+    expect(parsed["http.request.method"]).toBe("GET");
+    expect(parsed["url.path"]).toBe("/workspaces");
+    expect(parsed["event.duration"]).toBe(45_000_000);
+  });
+
   test("includes error stack fields", () => {
     const err = new Error("boom");
     const line = formatEcsLine(
@@ -40,4 +80,30 @@ describe("formatEcsLine", () => {
     expect(parsed["error.type"]).toBe("Error");
     expect(String(parsed["error.stack_trace"])).toContain("boom");
   });
+
+  test("enrich merges additive fields but not protected keys", () => {
+    const line = formatEcsLine({
+      service: { name: "app", version: "1.0.0" },
+      event: { level: "info", message: "hello" },
+      enrich: () => ({
+        "custom.field": "yes",
+        message: "overridden",
+      }),
+    });
+    const parsed = JSON.parse(line) as Record<string, unknown>;
+    expect(parsed.message).toBe("hello");
+    expect(parsed["custom.field"]).toBe("yes");
+  });
+});
+
+describe("mergeEnrichFields", () => {
+  test("skips protected and existing keys", () => {
+    const line: Record<string, unknown> = { message: "keep", "trace.id": "set" };
+    mergeEnrichFields(line, { message: "nope", "ecs.version": "0.0.0", "trace.id": "bad", extra: 1 });
+    expect(line.message).toBe("keep");
+    expect(line["ecs.version"]).toBeUndefined();
+    expect(line["trace.id"]).toBe("set");
+    expect(line.extra).toBe(1);
+    expect(PROTECTED_ECS_KEYS.has("message")).toBe(true);
+  });
 });

package/src/log/ecs.ts

@@ -2,6 +2,9 @@
 Elastic Common Schema (ECS) JSON log line formatting for framework observability.
 */
 
+/** ECS version string written to every JSON log line. */
+export const ECS_VERSION = "8.11.0";
+
 /** Severity label for ECS `log.level`. */
 export type EcsLogLevel = "debug" | "info" | "warn" | "error";
 
@@ -11,6 +14,26 @@ export interface EcsServiceFields {
   version: string;
 }
 
+/** Context for {@link CliLogConfig.enrich} and {@link CliLogConfig.serialize}. */
+export interface LogEnrichContext {
+  level: EcsLogLevel;
+  message: string;
+  action?: string;
+  requestId?: string;
+  traceId?: string;
+  spanId?: string;
+  labels?: Record<string, string | number | boolean>;
+  error?: unknown;
+  service: EcsServiceFields;
+  http?: {
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    clientIp?: string;
+  };
+}
+
 /** Input for one ECS log event. */
 export interface EcsLogEvent {
   level: EcsLogLevel;
@@ -19,8 +42,31 @@ export interface EcsLogEvent {
   labels?: Record<string, string | number | boolean>;
   error?: unknown;
   fields?: Record<string, unknown>;
+  requestId?: string;
+  traceId?: string;
+  spanId?: string;
+  /** Populated on HTTP/MCP access log events for {@link CliLogConfig.enrich}. */
+  http?: LogEnrichContext["http"];
+}
+
+/** Options for {@link formatEcsLine}. */
+export interface FormatEcsLineOpts {
+  service: EcsServiceFields;
+  event: EcsLogEvent;
+  /** Additive fields merged after the ECS baseline (cannot override protected keys). */
+  enrich?: (ctx: LogEnrichContext) => Record<string, unknown>;
 }
 
+/** ECS baseline keys that {@link FormatEcsLineOpts.enrich} must not override. */
+export const PROTECTED_ECS_KEYS = new Set([
+  "@timestamp",
+  "log.level",
+  "message",
+  "ecs.version",
+  "service.name",
+  "service.version",
+]);
+
 function errorFields(error: unknown): Record<string, unknown> {
   if (error instanceof Error) {
     return {
@@ -32,28 +78,77 @@ function errorFields(error: unknown): Record<string, unknown> {
   return { "error.message": String(error) };
 }
 
-/** Formats one ECS-compatible JSON log line (newline omitted). */
-export function formatEcsLine(service: EcsServiceFields, event: EcsLogEvent): string {
+function buildEnrichContext(service: EcsServiceFields, event: EcsLogEvent): LogEnrichContext {
+  return {
+    level: event.level,
+    message: event.message,
+    action: event.action,
+    requestId: event.requestId,
+    traceId: event.traceId,
+    spanId: event.spanId,
+    labels: event.labels,
+    error: event.error,
+    service,
+    http: event.http,
+  };
+}
+
+/** Merges enrich output without overriding protected or existing ECS baseline keys. */
+export function mergeEnrichFields(line: Record<string, unknown>, enrich: Record<string, unknown> | undefined): void {
+  if (!enrich) {
+    return;
+  }
+  for (const [key, value] of Object.entries(enrich)) {
+    if (PROTECTED_ECS_KEYS.has(key) || key in line) {
+      continue;
+    }
+    line[key] = value;
+  }
+}
+
+/** Formats one ECS Logging–compatible JSON log line (newline omitted). */
+export function formatEcsLine(opts: FormatEcsLineOpts): string;
+/** @deprecated Pass {@link FormatEcsLineOpts} instead. */
+export function formatEcsLine(service: EcsServiceFields, event: EcsLogEvent): string;
+export function formatEcsLine(serviceOrOpts: EcsServiceFields | FormatEcsLineOpts, event?: EcsLogEvent): string {
+  const opts: FormatEcsLineOpts =
+    event !== undefined ? { service: serviceOrOpts as EcsServiceFields, event } : (serviceOrOpts as FormatEcsLineOpts);
+  const { service, event: ev } = opts;
+
   const line: Record<string, unknown> = {
     "@timestamp": new Date().toISOString(),
-    "log.level": event.level,
-    message: event.message,
+    "log.level": ev.level,
+    message: ev.message,
+    "ecs.version": ECS_VERSION,
     "service.name": service.name,
     "service.version": service.version,
   };
-  if (event.action) {
-    line["event.action"] = event.action;
+
+  if (ev.action) {
+    line["event.action"] = ev.action;
   }
-  if (event.labels) {
-    for (const [key, value] of Object.entries(event.labels)) {
-      line[`labels.${key}`] = value;
-    }
+  if (ev.traceId) {
+    line["trace.id"] = ev.traceId;
+  }
+  if (ev.spanId) {
+    line["span.id"] = ev.spanId;
   }
-  if (event.fields) {
-    Object.assign(line, event.fields);
+  if (ev.labels && Object.keys(ev.labels).length > 0) {
+    line.labels = { ...ev.labels };
   }
-  if (event.error !== undefined) {
-    Object.assign(line, errorFields(event.error));
+  if (ev.fields) {
+    Object.assign(line, ev.fields);
   }
+  if (ev.error !== undefined) {
+    Object.assign(line, errorFields(ev.error));
+  }
+
+  mergeEnrichFields(line, opts.enrich?.(buildEnrichContext(service, ev)));
+
   return JSON.stringify(line);
 }
+
+/** Converts HTTP access duration from milliseconds to ECS `event.duration` nanoseconds. */
+export function durationMsToEcsNanos(durationMs: number): number {
+  return durationMs * 1_000_000;
+}