argsbarg 6.1.8 → 6.1.10

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;
+}

package/src/log/emitter.test.ts

@@ -0,0 +1,95 @@
+/*
+Unit tests for LogEmitter enrich and serialize hooks.
+*/
+
+import { describe, expect, test } from "bun:test";
+import type { CliProgram } from "../core/types.ts";
+import type { LogEnrichContext } from "./ecs.ts";
+import { LogEmitter } from "./emitter.ts";
+
+const program = {
+  key: "testapp",
+  version: "1.0.0",
+  description: "test",
+  handler: () => {},
+} satisfies CliProgram;
+
+function captureStderr(run: () => void): string {
+  const chunks: string[] = [];
+  const original = process.stderr.write.bind(process.stderr);
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    chunks.push(typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk));
+    return true;
+  }) as typeof process.stderr.write;
+  try {
+    run();
+  } finally {
+    process.stderr.write = original;
+  }
+  return chunks.join("");
+}
+
+describe("LogEmitter hooks", () => {
+  test("serialize bypasses built-in ECS formatter", () => {
+    const serialize = (ctx: LogEnrichContext) => JSON.stringify({ custom: true, msg: ctx.message });
+    const emitter = new LogEmitter({
+      program,
+      resolved: { format: "json", access: true, errors: true, dev: false, serialize },
+    });
+    const out = captureStderr(() => emitter.emit({ level: "info", message: "hello" }));
+    const parsed = JSON.parse(out.trim()) as Record<string, unknown>;
+    expect(parsed.custom).toBe(true);
+    expect(parsed.msg).toBe("hello");
+    expect(parsed["ecs.version"]).toBeUndefined();
+  });
+
+  test("enrich adds fields to access logs", () => {
+    const enrich = () => ({ "labels.team": "payments" });
+    const emitter = new LogEmitter({
+      program,
+      resolved: { format: "json", access: true, errors: true, dev: false, enrich },
+    });
+    const out = captureStderr(() =>
+      emitter.emitAccess({
+        method: "GET",
+        path: "/workspaces",
+        status: 200,
+        durationMs: 12,
+        requestId: "req-1",
+        clientIp: "127.0.0.1",
+      }),
+    );
+    const parsed = JSON.parse(out.trim()) as Record<string, unknown>;
+    expect(parsed["http.request.method"]).toBe("GET");
+    expect(parsed["url.path"]).toBe("/workspaces");
+    expect(parsed["labels.team"]).toBe("payments");
+    expect(parsed["ecs.version"]).toBeDefined();
+  });
+
+  test("enrich receives http on access logs", () => {
+    let seen: LogEnrichContext | undefined;
+    const enrich = (ctx: LogEnrichContext) => {
+      seen = ctx;
+      return {};
+    };
+    const emitter = new LogEmitter({
+      program,
+      resolved: { format: "json", access: true, errors: true, dev: false, enrich },
+    });
+    captureStderr(() =>
+      emitter.emitAccess({
+        method: "GET",
+        path: "/workspaces",
+        status: 200,
+        durationMs: 12,
+      }),
+    );
+    expect(seen?.http).toEqual({
+      method: "GET",
+      path: "/workspaces",
+      status: 200,
+      durationMs: 12,
+      clientIp: undefined,
+    });
+  });
+});

package/src/log/emitter.ts

@@ -4,8 +4,9 @@ Framework log emitter: ECS json or human text to stderr with optional file tee.
 
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
-import type { CliProgram } from "../core/types.ts";
-import { type EcsLogEvent, type EcsLogLevel, formatEcsLine } from "./ecs.ts";
+import type { CliLogConfig, CliProgram } from "../core/types.ts";
+import type { LogEnrichContext } from "./ecs.ts";
+import { durationMsToEcsNanos, type EcsLogEvent, type EcsLogLevel, formatEcsLine } from "./ecs.ts";
 
 /** Resolved logging options for a server or invoke session. */
 export interface ResolvedLogConfig {
@@ -14,6 +15,8 @@ export interface ResolvedLogConfig {
   access: boolean;
   errors: boolean;
   dev: boolean;
+  enrich?: CliLogConfig["enrich"];
+  serialize?: CliLogConfig["serialize"];
 }
 
 /** Options for {@link LogEmitter}. */
@@ -38,6 +41,8 @@ export function resolveLogConfig(program: CliProgram, overrides: Partial<Resolve
     access: overrides.access ?? log?.access ?? true,
     errors: overrides.errors ?? log?.errors ?? true,
     dev: overrides.dev ?? false,
+    enrich: log?.enrich,
+    serialize: log?.serialize,
   };
 }
 
@@ -80,6 +85,8 @@ export class LogEmitter {
     durationMs: number;
     requestId?: string;
     clientIp?: string;
+    traceId?: string;
+    spanId?: string;
   }): void {
     if (!this.resolved.access) {
       return;
@@ -91,17 +98,42 @@ export class LogEmitter {
       this.appendFile(line);
       return;
     }
+
+    const isHttp = fields.method !== "MCP";
+    const action = isHttp ? "http.access" : "mcp.access";
+    const httpFields: Record<string, unknown> = isHttp
+      ? {
+          "http.request.method": fields.method,
+          "url.path": fields.path,
+          "http.response.status_code": fields.status,
+          "event.duration": durationMsToEcsNanos(fields.durationMs),
+        }
+      : {
+          "event.duration": durationMsToEcsNanos(fields.durationMs),
+        };
+
+    if (fields.clientIp && fields.clientIp !== "unknown") {
+      httpFields["client.ip"] = fields.clientIp;
+    }
+
     this.emit({
       level: "info",
       message: `${fields.method} ${fields.path}`,
-      action: "http.access",
+      action,
+      requestId: fields.requestId,
+      traceId: fields.traceId,
+      spanId: fields.spanId,
+      fields: httpFields,
       labels: {
         ...(fields.requestId ? { request_id: fields.requestId } : {}),
-        ...(fields.clientIp ? { client_ip: fields.clientIp } : {}),
-        http_method: fields.method,
-        http_path: fields.path,
-        http_status: fields.status,
-        duration_ms: fields.durationMs,
+        ...(isHttp ? {} : { rpc_method: fields.path }),
+      },
+      http: {
+        method: fields.method,
+        path: fields.path,
+        status: fields.status,
+        durationMs: fields.durationMs,
+        clientIp: fields.clientIp,
       },
     });
   }
@@ -111,7 +143,12 @@ export class LogEmitter {
     failureKind: string,
     error: unknown,
     clientMessage: string,
-    labels?: Record<string, string | number | boolean>,
+    meta?: {
+      labels?: Record<string, string | number | boolean>;
+      requestId?: string;
+      traceId?: string;
+      spanId?: string;
+    },
   ): void {
     if (!this.resolved.errors) {
       return;
@@ -120,7 +157,10 @@ export class LogEmitter {
       level: failureKind === "unexpected" ? "error" : "warn",
       message: clientMessage,
       action: "invoke.error",
-      labels: { failure_kind: failureKind, ...labels },
+      labels: { failure_kind: failureKind, ...meta?.labels },
+      requestId: meta?.requestId,
+      traceId: meta?.traceId,
+      spanId: meta?.spanId,
       error,
     });
     if (this.resolved.dev && error instanceof Error && error.stack) {
@@ -133,7 +173,30 @@ export class LogEmitter {
     if (this.resolved.format === "text") {
       return this.formatTextLine(event);
     }
-    return formatEcsLine(this.service, event);
+    const enrichCtx = this.buildEnrichContext(event);
+    if (this.resolved.serialize) {
+      return this.resolved.serialize(enrichCtx);
+    }
+    return formatEcsLine({
+      service: this.service,
+      event,
+      enrich: this.resolved.enrich,
+    });
+  }
+
+  private buildEnrichContext(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: this.service,
+      http: event.http,
+    };
   }
 
   private formatTextLine(event: EcsLogEvent): string {

package/src/log/trace.test.ts

@@ -0,0 +1,60 @@
+/*
+Unit tests for W3C Trace Context parsing and formatting.
+*/
+
+import { describe, expect, test } from "bun:test";
+import { extractTraceContext, formatTraceparent, parseTraceparent, randomSpanId } from "./trace.ts";
+
+describe("parseTraceparent", () => {
+  test("parses valid traceparent", () => {
+    const parsed = parseTraceparent("00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01");
+    expect(parsed).toEqual({
+      traceId: "0af7651916cd43dd8448eb211c80319c",
+      spanId: "b7ad6b7169203331",
+      sampled: true,
+    });
+  });
+
+  test("returns undefined for invalid header", () => {
+    expect(parseTraceparent("not-a-traceparent")).toBeUndefined();
+    expect(parseTraceparent("")).toBeUndefined();
+  });
+});
+
+describe("formatTraceparent", () => {
+  test("formats traceparent with sampled flag", () => {
+    expect(
+      formatTraceparent({
+        traceId: "0af7651916cd43dd8448eb211c80319c",
+        spanId: "b7ad6b7169203331",
+        sampled: true,
+      }),
+    ).toBe("00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01");
+  });
+});
+
+describe("extractTraceContext", () => {
+  test("creates a new span id for the server hop", () => {
+    const request = new Request("http://localhost/workspaces", {
+      headers: {
+        traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+      },
+    });
+    const ctx = extractTraceContext(request);
+    expect(ctx?.traceId).toBe("0af7651916cd43dd8448eb211c80319c");
+    expect(ctx?.parentSpanId).toBe("b7ad6b7169203331");
+    expect(ctx?.spanId).toHaveLength(16);
+    expect(ctx?.spanId).not.toBe("b7ad6b7169203331");
+  });
+
+  test("returns undefined when header is missing", () => {
+    const request = new Request("http://localhost/workspaces");
+    expect(extractTraceContext(request)).toBeUndefined();
+  });
+});
+
+describe("randomSpanId", () => {
+  test("returns 16 hex chars", () => {
+    expect(randomSpanId()).toMatch(/^[0-9a-f]{16}$/);
+  });
+});

package/src/log/trace.ts

@@ -0,0 +1,62 @@
+/*
+W3C Trace Context (traceparent) parsing and formatting for HTTP request correlation.
+*/
+
+import { randomBytes } from "node:crypto";
+
+/** Parsed trace context for one HTTP request hop. */
+export interface IncomingTraceContext {
+  /** 128-bit trace id (32 lowercase hex chars). */
+  traceId: string;
+  /** Parent span id from the incoming traceparent (caller's span). */
+  parentSpanId: string;
+  /** New span id for this server hop (16 lowercase hex chars). */
+  spanId: string;
+  /** Whether the trace is marked sampled in trace-flags. */
+  sampled: boolean;
+}
+
+const TRACEPARENT_RE = /^[\da-f]{2}-([\da-f]{32})-([\da-f]{16})-([\da-f]{2})$/i;
+
+/** Generates a new 64-bit span id (16 hex chars). */
+export function randomSpanId(): string {
+  return randomBytes(8).toString("hex");
+}
+
+/** Parses a W3C `traceparent` header value, or returns undefined when invalid. */
+export function parseTraceparent(header: string): { traceId: string; spanId: string; sampled: boolean } | undefined {
+  const match = header.trim().match(TRACEPARENT_RE);
+  if (!match) {
+    return undefined;
+  }
+  const [, traceId, spanId, flags] = match;
+  if (!traceId || !spanId || !flags) {
+    return undefined;
+  }
+  const flagByte = Number.parseInt(flags, 16);
+  return {
+    traceId: traceId.toLowerCase(),
+    spanId: spanId.toLowerCase(),
+    sampled: (flagByte & 0x01) === 0x01,
+  };
+}
+
+/** Extracts trace context from an HTTP request, or undefined when no valid traceparent is present. */
+export function extractTraceContext(request: Request): IncomingTraceContext | undefined {
+  const parsed = parseTraceparent(request.headers.get("traceparent") ?? "");
+  if (!parsed) {
+    return undefined;
+  }
+  return {
+    traceId: parsed.traceId,
+    parentSpanId: parsed.spanId,
+    spanId: randomSpanId(),
+    sampled: parsed.sampled,
+  };
+}
+
+/** Formats a W3C `traceparent` header value for the current hop. */
+export function formatTraceparent(ctx: { traceId: string; spanId: string; sampled?: boolean }): string {
+  const flags = ctx.sampled === false ? "00" : "01";
+  return `00-${ctx.traceId}-${ctx.spanId}-${flags}`;
+}

package/src/runtime/cli.ts

@@ -195,7 +195,7 @@ export class Cli {
       invocation?: CliInvocation;
       toolArgs?: Record<string, unknown>;
       requestId?: string;
-      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 };
     },
   ): Promise<CliInvokeResult> {