argsbarg 6.1.8 → 6.1.10

package/examples/full-example/docs/cli.md

@@ -195,7 +195,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -231,7 +231,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -408,7 +408,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -444,7 +444,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -649,7 +649,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -685,7 +685,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -872,7 +872,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -908,7 +908,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -1085,7 +1085,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -1121,7 +1121,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -1309,7 +1309,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -1345,7 +1345,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -1522,7 +1522,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -1558,7 +1558,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -1735,7 +1735,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -1771,7 +1771,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
@@ -1948,7 +1948,7 @@ MCP server and bundle tools.
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |
 
@@ -1984,7 +1984,7 @@ HTTP API server for tools.
 | `--port` | number | optional | — | Listen port. |
 | `--trust-proxy` | flag | optional | — | Honor X-Forwarded-For for client IP. |
 | `--obscure-errors` | flag | optional | — | Hide unexpected errors from clients. |
-| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS) or text. |
+| `--log-format` | enum (`json`, `text`) | optional | — | Log format: json (ECS Logging) or text. |
 | `--log-file` | string | optional | — | Append logs to this file (relative → app config dir). |
 | `--no-access-log` | flag | optional | — | Disable HTTP access logs. |
 | `--dev` | flag | optional | — | Print full stacks to stderr on errors. |

package/examples/full-example/docs/http.md

@@ -1,3 +1,5 @@
+<!-- Generated by full-example docs http --save; do not edit. -->
+
 # HTTP API (full-example)
 
 full-example exposes user commands over HTTP REST routes derived from the CLI tree.
@@ -10,7 +12,7 @@ full-example http
 
 Listens on **http://127.0.0.1:3000** by default (`httpServer.host` / `httpServer.port`).
 
-Bind is localhost-only in v0 — use a reverse proxy for remote access.
+Bind is localhost-only by default — use a reverse proxy for remote access.
 
 ## Endpoints
 
@@ -45,6 +47,16 @@ Handlers must use `ctx.respond()` or return a value for API/MCP tool calls.
 
 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.
+
 ## REST routes
 
 - `POST /echo` (CLI: `full-example echo`) — Echo a message (MCP-friendly leaf).

package/examples/full-example/justfile

@@ -34,6 +34,22 @@ migrate DB="./workspaces.db":
 # Run schemagen, typecheck, and format
 check: schemagen format typecheck
 
+# demo the HTTP API
+demo-http:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    bun ./src/index.ts http --port 13000 &
+    trap 'kill $! 2>/dev/null || true' EXIT
+    until curl -sf http://127.0.0.1:13000/health/liveness >/dev/null; do sleep 0.1; done
+
+# demo a CLI command
+demo-cli:
+    @just run {{cli_key}} status
+
+# demo a CLI command
+demo-help:
+    @just run {{cli_key}} --help
+
 # Run the CLI from source with optional args; restarts on file changes
 dev *ARGS:
     bun --watch ./src/index.ts {{ARGS}}
@@ -53,6 +69,10 @@ alias fmt := format
 format:
     bun run biome check ./src ./scripts --write --unsafe
 
+# Run the HTTP server
+http:
+    @just run http
+
 # Alias for backward compatibility
 install: install-local
 

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.10",
   "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

@@ -45,7 +45,7 @@ export function generateHttpGuide(root: CliProgram): string {
     "",
     `Listens on **${baseUrl}** by default (\`httpServer.host\` / \`httpServer.port\`).`,
     "",
-    "Bind is localhost-only in v0 — use a reverse proxy for remote access.",
+    "Bind is localhost-only by default — use a reverse proxy for remote access.",
     "",
     "## Endpoints",
     "",
@@ -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/docs/save.ts

@@ -8,7 +8,7 @@ import { docsTopicContent } from "./resolve.ts";
 export const DOCS_SAVE_DIR = "docs";
 
 /** Builtin docs topics generated by argsbarg (not consumer `docs.topics`). */
-export const DOCS_GENERATED_SAVE_TOPICS = ["mcp", "cli", "skill"] as const;
+export const DOCS_GENERATED_SAVE_TOPICS = ["mcp", "cli", "skill", "http"] as const;
 
 /** Whether `--save` should prepend a generated-file hint (argsbarg writers only). */
 export function docsTopicIsGeneratedByArgsbarg(topic: string): boolean {

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";