argsbarg 6.1.8 → 6.1.9

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.1.9] - 2026-07-27
+
+### Added
+
+- **ECS Logging–compatible JSON logs** — default JSON output includes `ecs.version`, nested `labels`, canonical HTTP fields (`http.request.method`, `url.path`, `http.response.status_code`, `event.duration` in nanoseconds), and W3C `trace.id` / `span.id` when `traceparent` is present on HTTP requests.
+- **`program.log.enrich`** — additive hook for custom JSON fields (cannot override ECS baseline keys).
+- **`program.log.serialize`** — optional full-line JSON formatter that bypasses the built-in ECS formatter.
+
+### Changed
+
+- **HTTP trace propagation** — parses incoming `traceparent`, logs trace/span ids, and echoes an updated `traceparent` on responses.
+- **CLI log-format help** — describes JSON as ECS Logging, not generic ECS.
+- **Docs** — new [logging.md](logging.md) (`program.log`, `enrich`, `serialize`, examples); `http-server.md` links there.
+
 ## [6.1.8] - 2026-07-27
 
 ### Changed
@@ -865,7 +879,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.8...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.9...HEAD
+[6.1.9]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.9
 [6.1.8]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.8
 [6.1.7]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.7
 [6.1.6]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.6

package/docs/README.md

@@ -11,6 +11,7 @@ Start here to pick the right guide.
 | **JSON Schema validation** | [json-schema-subset.md](json-schema-subset.md) — Draft-07 / 2019-09 / 2020-12 (`$schema` on each schema; default Draft-07) |
 | **Exposing MCP tools** | [mcp.md](mcp.md) — stdio server, `inputSchema`, varargs, `configure --sync` |
 | **HTTP tool server** | [http-server.md](http-server.md) — `myapp http`, endpoints, curl examples |
+| **Server logging** (`program.log`, `enrich`, `serialize`) | [logging.md](logging.md) — ECS JSON lines, trace headers, custom formats |
 | **Shipping configure / agent artifacts** | [configure.md](configure.md) — Homebrew + `myapp configure --sync` |
 | **Homebrew tap-from-repo distribution** | [distribution-homebrew.md](distribution-homebrew.md) — formula pattern, `argsbarg create` |
 | **Bundling `myapp docs` topics** | [bundled-docs.md](bundled-docs.md) — consumer docgen vs framework docs |

package/docs/cli-program.md

@@ -41,6 +41,8 @@ const cli = {
 
 `httpServer` and `mcpServer` are independent. Tool exposure uses the same rules (`mcpTool.enabled: false` hides from MCP and HTTP). See [http-server.md](http-server.md).
 
+**Logging** — HTTP and MCP server logs go to stderr (JSON by default). Configure `program.log` on the program root; use **`enrich`** to add fields or **`serialize`** for a fully custom line. See **[logging.md](logging.md)**.
+
 ## Inline schema by default
 
 ArgsBarg is **schema-first** — the program tree is the product. **Keep `CliProgram` and leaf fields inline** (`key`, `description`, `options`, `positionals`, `handler`) so a reader sees the full command contract in one place.

package/docs/decisions.md

@@ -37,4 +37,23 @@ Yes Zod implements some features we do custom for JSON-SCHEMA, but is opinionate
 3. For uses like API pass-through, proxy, dynamic schemas, Zod may actually explode complexity for consumers.
 4. Our TS->json-schema approach is actually easier and better in many cases
   - Just write plain typescript, done.
-  - Better intellisense -- substantially less abstraction/inference, much better control
+  - Better intellisense -- substantially less abstraction/inference, much better control
+
+## Structured logging (ECS Logging)
+
+Decision: **ECS Logging–compatible NDJSON to stderr** (default), with optional `enrich` / `serialize` hooks
+
+### Context
+
+- HTTP/MCP servers need access logs, error logs, and trace correlation in production log pipelines
+- Consumers may need custom fields (team labels, vendor-specific shapes) without baking proprietary formats into argsbarg core
+- OpenTelemetry log export is out of scope for the framework runtime (no third-party observability SDK dependency)
+
+### Rationale
+
+1. **ECS Logging** is an open standard (NDJSON, `ecs.version`, canonical field names) — works with Elasticsearch, Datadog, GCP log agents, etc.
+2. **stderr + JSONL** keeps stdout free for CLI output and matches twelve-factor log collection
+3. **W3C Trace Context** (`traceparent`) enables cross-service correlation without vendor-specific field layouts
+4. **`program.log.enrich`** — additive hook for consumer-specific fields; cannot override the ECS baseline
+5. **`program.log.serialize`** — escape hatch for full custom lines in consumer repos (argsbarg does not endorse that output as ECS)
+6. **No Tyson / OTel SDK in core** — proprietary or heavy observability stacks belong in consumer config or infra (Fluent Bit remapping), not in the open-source framework

package/docs/http-server.md

@@ -49,7 +49,9 @@ Set `httpServer` on the **program root only**. Validation rejects `httpServer` o
 
 `httpServer` and `mcpServer` are independent — enable either or both.
 
-Program-level `program.log` controls ECS JSON vs human text on stderr (and optional file tee). See [docs/decisions.md](decisions.md).
+## Logging
+
+Server logs (access lines, errors, startup) go to **stderr** as JSON by default. See **[logging.md](logging.md)** for `program.log`, **`enrich`**, **`serialize`**, trace headers, and examples.
 
 ## REST routes
 

package/docs/logging.md

@@ -0,0 +1,149 @@
+# Server logging
+
+When you run `myapp http` or `myapp mcp`, Argsbarg writes **server logs to stderr** — not to stdout (handlers and CLI output stay on stdout).
+
+By default each log line is **one JSON object** (NDJSON), shaped for the [ECS Logging](https://github.com/elastic/ecs-logging) convention. That plays nicely with Datadog, Elasticsearch, GCP Logging, and similar collectors.
+
+For local development, switch to plain text with `--log-format text` or `program.log.format: "text"`.
+
+## What gets logged
+
+| Event | When | `event.action` |
+| --- | --- | --- |
+| Server start | HTTP/MCP process listens | `http.server.start` / `server.start` |
+| Access | After each HTTP request or MCP JSON-RPC message | `http.access` / `mcp.access` |
+| Invoke error | After `formatError` → `onError`, before the client sees the error | `invoke.error` |
+
+Toggle access or error lines with `program.log.access` and `program.log.errors` (both default to `true`).
+
+## Example line (default JSON)
+
+After `GET /workspaces` returns 200 in 45ms:
+
+```json
+{
+  "@timestamp": "2026-07-27T14:00:00.000Z",
+  "log.level": "info",
+  "message": "GET /workspaces",
+  "ecs.version": "8.11.0",
+  "service.name": "myapp",
+  "service.version": "1.0.0",
+  "event.action": "http.access",
+  "http.request.method": "GET",
+  "url.path": "/workspaces",
+  "http.response.status_code": 200,
+  "event.duration": 45000000,
+  "labels": { "request_id": "…" }
+}
+```
+
+`event.duration` is in **nanoseconds** (ECS convention). Durations in hook callbacks (`durationMs`) stay in milliseconds.
+
+When the client sends a W3C **`traceparent`** header, lines also include `trace.id` and `span.id`, and the response echoes an updated `traceparent`.
+
+## `program.log` options
+
+Set on the **program root** (same level as `httpServer` / `mcpServer`):
+
+```typescript
+const program = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "…",
+  log: {
+    format: "json",   // "text" for human-readable stderr
+    file: "server.log", // optional tee; relative paths → app config dir
+    access: true,     // HTTP/MCP access lines
+    errors: true,     // invoke error lines
+  },
+  // …
+} satisfies CliProgram;
+```
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `format` | `"json"` | `"json"` = ECS Logging NDJSON; `"text"` = `INFO [http.access]: GET /path` |
+| `file` | — | Append the same lines to this path |
+| `access` | `true` | Emit one line per HTTP request / MCP message |
+| `errors` | `true` | Emit when a user command fails on HTTP/MCP |
+| `enrich` | — | Add custom fields to each JSON line (see below) |
+| `serialize` | — | Replace the built-in formatter entirely (see below) |
+
+CLI overrides on `myapp http` and `myapp mcp serve`: `--log-format`, `--log-file`, `--no-access-log` (HTTP only), `--dev` (print full stacks to stderr on errors).
+
+## `program.log.enrich` — add fields
+
+Use **`enrich`** when you want **extra JSON fields** on top of the default ECS line — for example a team label, deployment cell, or a shape your log pipeline expects.
+
+`enrich` is **additive only**. It cannot change `@timestamp`, `log.level`, `message`, `ecs.version`, `service.name`, `service.version`, or any field Argsbarg already set on that line.
+
+```typescript
+import type { LogEnrichContext } from "argsbarg";
+
+const program = {
+  // …
+  log: {
+    format: "json",
+    enrich: (ctx: LogEnrichContext) => {
+      // Always available:
+      // ctx.level, ctx.message, ctx.action, ctx.service.name, ctx.service.version
+      // ctx.requestId, ctx.traceId, ctx.spanId (when present)
+      // ctx.labels, ctx.error (on error lines)
+
+      // On access logs (http.access / mcp.access):
+      // ctx.http.method, ctx.http.path, ctx.http.status, ctx.http.durationMs, ctx.http.clientIp
+
+      return {
+        deployment: "prod",
+      };
+    },
+  },
+} satisfies CliProgram;
+```
+
+Return a flat object of field names → values. Argsbarg merges each key onto the log line unless that key is already set. To add team metadata inside ECS `labels`, put it in `event.labels` via hooks rather than fighting merge order — or use `serialize` for full control.
+
+## `program.log.serialize` — own the whole line
+
+Use **`serialize`** when the default ECS line is not what you need — for example a legacy JSON schema used only in your organization.
+
+When `serialize` is set, Argsbarg **does not** run the ECS formatter. Your function receives the same `LogEnrichContext` as `enrich` and must return the **full line text without a trailing newline** (Argsbarg adds `\n`).
+
+```typescript
+import type { LogEnrichContext } from "argsbarg";
+
+const program = {
+  // …
+  log: {
+    format: "json",
+    serialize: (ctx: LogEnrichContext) =>
+      JSON.stringify({
+        message: ctx.message,
+        level: ctx.level.toUpperCase(),
+        contextMap: {
+          ...(ctx.traceId ? { trace_id: ctx.traceId } : {}),
+          ...(ctx.spanId ? { span_id: ctx.spanId } : {}),
+        },
+      }),
+  },
+} satisfies CliProgram;
+```
+
+Do **not** set both `enrich` and `serialize` expecting both to apply — `serialize` wins and `enrich` is ignored.
+
+Prefer **`enrich`** when you only need a few extra fields. Reserve **`serialize`** for fully custom output.
+
+## Trace correlation (HTTP)
+
+If an upstream service (gateway, sidecar, mesh) sends a standard **`traceparent`** header:
+
+1. Argsbarg parses it and logs `trace.id` / `span.id`.
+2. The HTTP response includes an updated `traceparent` for this hop.
+
+No configuration required. If the header is missing, Argsbarg does not invent a trace id.
+
+## Related
+
+- [http-server.md](http-server.md) — HTTP server setup and endpoints
+- [mcp.md](mcp.md) — MCP server (same `program.log` applies)
+- [decisions.md](decisions.md#structured-logging-ecs-logging) — why ECS Logging and hooks instead of a bundled observability SDK

package/examples/full-example/docs/cli-schema.json

@@ -161,7 +161,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -215,7 +215,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -394,7 +394,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -448,7 +448,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -649,7 +649,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -703,7 +703,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -886,7 +886,7 @@
                 },
                 {
                   "name": "log-format",
-                  "description": "Log format: json (ECS) or text.",
+                  "description": "Log format: json (ECS Logging) or text.",
                   "kind": "enum",
                   "choices": [
                     "json",
@@ -940,7 +940,7 @@
                 },
                 {
                   "name": "log-format",
-                  "description": "Log format: json (ECS) or text.",
+                  "description": "Log format: json (ECS Logging) or text.",
                   "kind": "enum",
                   "choices": [
                     "json",
@@ -1119,7 +1119,7 @@
                 },
                 {
                   "name": "log-format",
-                  "description": "Log format: json (ECS) or text.",
+                  "description": "Log format: json (ECS Logging) or text.",
                   "kind": "enum",
                   "choices": [
                     "json",
@@ -1173,7 +1173,7 @@
                 },
                 {
                   "name": "log-format",
-                  "description": "Log format: json (ECS) or text.",
+                  "description": "Log format: json (ECS Logging) or text.",
                   "kind": "enum",
                   "choices": [
                     "json",
@@ -1356,7 +1356,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1410,7 +1410,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1589,7 +1589,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1643,7 +1643,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1822,7 +1822,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1876,7 +1876,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -2055,7 +2055,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -2109,7 +2109,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",

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

@@ -45,6 +45,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).