@viktorbarzin/log 0.1.0 → 1.0.0

package/README.md

@@ -1,38 +1,86 @@
 # @viktorbarzin/log
 
-A JSON-lines logger for the platform's log contract: one object per line on
-stderr with `ts` (Python `isoformat`, `+00:00`), `level`, `logger`, `msg`,
-then the call's extras (which never overwrite those four keys), then `exc`
-for an error. No dependencies; works on Bun and Node.
+A JSON-lines logger for the platform's log standard (app-kit ADR-0002): one
+object per line on stdout, with field names from the OpenTelemetry log data
+model and semantic conventions. No dependencies; works on Bun and Node.
 
 <!-- typecheck-preamble
 declare const err: unknown;
+declare const request: Request;
+declare const handle: (request: Request) => Promise<Response>;
 -->
 ```ts
-import { getLogger, installJsonConsole } from "@viktorbarzin/log";
+import {
+	getLogger,
+	installJsonConsole,
+	setLogContext,
+	withLogContext,
+} from "@viktorbarzin/log";
 
 const log = getLogger("myapp.sync");
-log.info("sync served", { user: "someone", lists: 3 });
+log.info("sync served", { lists: 3, duration_ms: 12 });
 log.exception("sync failed", err, { path: "/api/sync" });
 
+// Per request: every line inside carries enduser.id, trace_id and span_id.
+await withLogContext({ traceId: request.headers.get("x-trace-id") ?? undefined }, async () => {
+	setLogContext({ enduserId: "the person's OIDC sub" });
+	return handle(request);
+});
+
 installJsonConsole(); // console.* from the framework becomes JSON lines too (logger "console")
 ```
 
 ```json
-{"ts":"2026-10-16T04:05:06.789000+00:00","level":"INFO","logger":"myapp.sync","msg":"sync served","user":"someone","lists":3}
+{"timestamp":"2026-10-16T04:05:06.789000000Z","severity_text":"INFO","severity_number":9,"body":"sync served","logger.name":"myapp.sync","service.name":"myapp","service.version":"1a2b3c4d","deployment.environment.name":"production","enduser.id":"…","lists":3,"duration_ms":12}
 ```
 
+## Fields
+
+| Field | Meaning |
+|---|---|
+| `timestamp` | RFC 3339 in UTC with nine fractional digits and `Z`. JavaScript's clock has millisecond precision, so the last six digits are zero unless `formatRecord` is given nanoseconds |
+| `severity_text`, `severity_number` | `DEBUG` 5, `INFO` 9, `WARN` 13, `ERROR` 17, `FATAL` 21 |
+| `body` | the message |
+| `logger.name` | the name given to `getLogger` |
+| `service.name`, `service.version`, `deployment.environment.name` | from `setLogService`, else `OTEL_SERVICE_NAME`, `SERVICE_VERSION`, `DEPLOYMENT_ENVIRONMENT` |
+| `trace_id`, `span_id`, `enduser.id` | from the current `withLogContext` scope |
+| extras | the call's extras (snake_case keys by convention), after the scope's `attributes` |
+| `exception.type`, `exception.message`, `exception.stacktrace` | for an error, last |
+
+Fields with no value are left out rather than written as `null`. Extras
+never overwrite the standard fields.
+
+`logger.name` is our key. OpenTelemetry's data model records the logger
+name as the instrumentation scope name, which has no attribute key of its
+own in a flat JSON line, and the semantic conventions define no logger
+attribute. `logger.name` keeps the dotted OpenTelemetry style and says
+what the value is. The libraries for other languages should use the same
+key, so that one Loki query covers every app.
+
 ## API
 
 | Export | |
 |---|---|
-| `getLogger(name)` | `debug`, `info`, `warning`, `error`, `exception(msg, err, extra?)`, `record(level, msg, extra?, err?)` |
-| `parseLogLevel(raw)` | `WARN` → `WARNING`; unknown or unset → `INFO` |
-| `setLogLevel(level)` | the threshold; starts from `LOG_LEVEL` |
+| `getLogger(name)` | `debug`, `info`, `warn` (and `warning`), `error`, `fatal`, `exception(msg, err, extra?)`, `record(level, msg, extra?, err?)` |
+| `withLogContext(context, fn)` | run `fn` with `enduserId`, `traceId`, `spanId` and `attributes` on every line written inside it, async work included; scopes nest |
+| `setLogContext(context)` | add fields to the current scope (for example once the session is known); false outside a scope |
+| `getLogContext()` | the current scope's fields |
+| `setLogService(service)` | set `name`, `version`, `environment` explicitly; returns a restore function |
+| `serviceFromEnv(env?)` | the service fields from the environment |
+| `parseLogLevel(raw)` | `WARNING` → `WARN`; unknown or unset → `INFO` |
+| `setLogLevel(level)` | the threshold; starts from `LOG_LEVEL` (`WARNING` is accepted for `WARN`) |
 | `setLogSink(sink)` | send lines elsewhere (tests); returns a restore function |
-| `installJsonConsole(target?)` | route `console.*` through the logger; an `Error` argument goes under `exc`; returns a restore function |
-| `formatRecord`, `pythonIsoTimestamp` | the formatting, exported for tests |
+| `installJsonConsole(target?)` | route `console.*` through the logger; an `Error` argument goes under `exception.*`; returns a restore function |
+| `formatRecord`, `formatTimestamp`, `SEVERITY_NUMBER` | the formatting, exported for tests |
+
+The sink, threshold, service fields and context store are one per process
+(kept on `globalThis`), so a server bundled twice still logs through one
+sink and one context. The environment variables read are `LOG_LEVEL`,
+`OTEL_SERVICE_NAME`, `SERVICE_VERSION` and `DEPLOYMENT_ENVIRONMENT`.
+
+## Upgrading from 0.x
 
-The sink and threshold are one per process (kept on `globalThis`), so a
-server bundled twice still logs through one sink. `LOG_LEVEL` is the only
-environment variable read.
+1.0 renames every field (ADR-0002) and writes to stdout instead of stderr.
+Code that calls the logger needs no change. Loki queries, dashboards and
+tests that read `ts`, `level`, `logger`, `msg` or `exc` move to
+`timestamp`, `severity_text`, `logger.name`, `body` and `exception.*`.

package/dist/index.d.ts

@@ -1,29 +1,87 @@
-export type LogLevel = "DEBUG" | "INFO" | "WARNING" | "ERROR";
+export type LogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL";
+/** What `setLogLevel` and `record` accept: a level, or `WARNING` for WARN. */
+export type LogLevelName = LogLevel | "WARNING";
 export type LogExtra = Record<string, unknown>;
 export type LogSink = (line: string) => void;
-/** `WARN` means WARNING; anything unknown or unset is INFO. */
+/** OpenTelemetry severity numbers: the first number of each range. */
+export declare const SEVERITY_NUMBER: Readonly<Record<LogLevel, number>>;
+/** The resource fields on every line. Unknown fields are left out. */
+export interface LogService {
+    /** `service.name`, the app. */
+    name?: string | undefined;
+    /** `service.version`, the release. */
+    version?: string | undefined;
+    /** `deployment.environment.name`, e.g. `production` or `dev`. */
+    environment?: string | undefined;
+}
+/** Per-request fields, set with `withLogContext` and `setLogContext`. */
+export interface LogContext {
+    /** `enduser.id`: the person's stable id (for example the OIDC `sub`). */
+    enduserId?: string | undefined;
+    /** `trace_id`, hex. */
+    traceId?: string | undefined;
+    /** `span_id`, hex. */
+    spanId?: string | undefined;
+    /** More snake_case attributes for every line in the scope. */
+    attributes?: LogExtra | undefined;
+}
+/** `WARNING` means WARN; anything unknown or unset is INFO. */
 export declare function parseLogLevel(raw: string | undefined): LogLevel;
-/** Python's `datetime.isoformat()` for an aware UTC datetime: `...T04:05:06.789000+00:00`. */
-export declare function pythonIsoTimestamp(date: Date): string;
-/** Send lines somewhere other than stderr (tests). Returns a restore function. */
+/** The service fields from OTEL_SERVICE_NAME, SERVICE_VERSION and DEPLOYMENT_ENVIRONMENT. */
+export declare function serviceFromEnv(env?: Record<string, string | undefined>): LogService;
+/**
+ * RFC 3339 in UTC with nine fractional digits: `2026-10-16T04:05:06.789000000Z`.
+ * Takes a Date (millisecond precision, so the last six digits are zero) or
+ * nanoseconds since the epoch as a bigint (every digit kept).
+ */
+export declare function formatTimestamp(time: Date | bigint): string;
+/** Send lines somewhere other than stdout (tests). Returns a restore function. */
 export declare function setLogSink(sink: LogSink): () => void;
-export declare function setLogLevel(level: LogLevel): void;
-export declare function formatRecord(level: LogLevel, logger: string, msg: string, extra?: LogExtra, err?: unknown, now?: Date): string;
+export declare function setLogLevel(level: LogLevelName): void;
+/**
+ * Set the service fields explicitly; given fields replace the ones from the
+ * environment. Returns a restore function.
+ */
+export declare function setLogService(service: LogService): () => void;
+/**
+ * Run `fn` with `context` added to every log line written inside it,
+ * including in async work it starts. Nested scopes inherit the outer fields
+ * and may override them.
+ */
+export declare function withLogContext<T>(context: LogContext, fn: () => T): T;
+/**
+ * Add fields to the current `withLogContext` scope, for example `enduserId`
+ * once the session is known. The whole scope sees them, including lines
+ * written after this call by code that started earlier. Outside a scope it
+ * changes nothing and returns false.
+ */
+export declare function setLogContext(context: LogContext): boolean;
+/** The current scope's fields, or undefined outside `withLogContext`. */
+export declare function getLogContext(): LogContext | undefined;
+/** The service and context for one record; `formatRecord` reads the process's when omitted. */
+export interface RecordScope {
+    service?: LogService | undefined;
+    context?: LogContext | undefined;
+}
+export declare function formatRecord(level: LogLevelName, logger: string, body: string, extra?: LogExtra, err?: unknown, now?: Date | bigint, scope?: RecordScope): string;
 export interface Logger {
     debug(msg: string, extra?: LogExtra): void;
     info(msg: string, extra?: LogExtra): void;
+    warn(msg: string, extra?: LogExtra): void;
+    /** The same as `warn`. */
     warning(msg: string, extra?: LogExtra): void;
     error(msg: string, extra?: LogExtra): void;
-    /** ERROR with the error's stack under `exc`, like Python's logger.exception. */
+    fatal(msg: string, extra?: LogExtra): void;
+    /** ERROR with the error under `exception.*`, like Python's logger.exception. */
     exception(msg: string, err: unknown, extra?: LogExtra): void;
-    /** Any level, with an optional error under `exc`. */
-    record(level: LogLevel, msg: string, extra?: LogExtra, err?: unknown): void;
+    /** Any level, with an optional error under `exception.*`. */
+    record(level: LogLevelName, msg: string, extra?: LogExtra, err?: unknown): void;
 }
 export declare function getLogger(name: string): Logger;
 /**
  * Route console.* through the JSON-lines logger (logger "console"), so the
  * framework's own output (Nitro's error handler, srvx's banner, uncaught
- * errors) is JSON lines too. An Error argument goes under `exc` with its
- * stack, as one line. Returns a function that puts the old methods back.
+ * errors) is JSON lines too. An Error argument goes under `exception.*`, as
+ * one line. Returns a function that puts the old methods back.
  */
 export declare function installJsonConsole(target?: Console): () => void;

package/dist/index.js

@@ -1,27 +1,53 @@
 /**
- * JSON-lines logging, the platform's log contract: one JSON object per line
- * on stderr with `ts` (Python isoformat, `+00:00`), `level`, `logger`, `msg`,
- * then the extras passed at the call site, then `exc` for an error. Extras
- * never overwrite the four standard keys. Loki and the dashboards parse this
- * shape.
+ * JSON-lines logging with OpenTelemetry log data model field names (app-kit
+ * ADR-0002): one JSON object per line on stdout with `timestamp`,
+ * `severity_text`, `severity_number`, `body`, `logger.name`, the service
+ * fields, the request context (`trace_id`, `span_id`, `enduser.id`), then
+ * the extras passed at the call site, then `exception.*` for an error.
+ * Extras never overwrite the standard keys.
  *
- * The sink and threshold are one per process, kept on globalThis: a server
- * bundled twice (Nitro's entry plus Start's SSR graph) still has one of each.
- * The initial threshold comes from LOG_LEVEL, the only variable read here.
+ * The sink, threshold, service fields and the context store are one per
+ * process, kept on globalThis: a server bundled twice (Nitro's entry plus
+ * Start's SSR graph) still has one of each. The initial values come from
+ * LOG_LEVEL, OTEL_SERVICE_NAME, SERVICE_VERSION and DEPLOYMENT_ENVIRONMENT.
  */
+import { AsyncLocalStorage } from "node:async_hooks";
 import { format } from "node:util";
-const LEVEL_RANK = {
-    DEBUG: 10,
-    INFO: 20,
-    WARNING: 30,
-    ERROR: 40,
+/** OpenTelemetry severity numbers: the first number of each range. */
+export const SEVERITY_NUMBER = {
+    DEBUG: 5,
+    INFO: 9,
+    WARN: 13,
+    ERROR: 17,
+    FATAL: 21,
 };
-/** `WARN` means WARNING; anything unknown or unset is INFO. */
+function toLevel(level) {
+    return level === "WARNING" ? "WARN" : level;
+}
+/** `WARNING` means WARN; anything unknown or unset is INFO. */
 export function parseLogLevel(raw) {
     const upper = (raw ?? "").trim().toUpperCase();
-    if (upper === "WARN")
-        return "WARNING";
-    return upper in LEVEL_RANK ? upper : "INFO";
+    if (upper === "WARNING")
+        return "WARN";
+    return upper in SEVERITY_NUMBER ? upper : "INFO";
+}
+function nonBlank(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+/** The service fields from OTEL_SERVICE_NAME, SERVICE_VERSION and DEPLOYMENT_ENVIRONMENT. */
+export function serviceFromEnv(env = process.env) {
+    const service = {};
+    const name = nonBlank(env.OTEL_SERVICE_NAME);
+    const version = nonBlank(env.SERVICE_VERSION);
+    const environment = nonBlank(env.DEPLOYMENT_ENVIRONMENT);
+    if (name !== undefined)
+        service.name = name;
+    if (version !== undefined)
+        service.version = version;
+    if (environment !== undefined)
+        service.environment = environment;
+    return service;
 }
 function state() {
     const store = globalThis;
@@ -30,19 +56,31 @@ function state() {
     if (found === undefined) {
         found = {
             sink: (line) => {
-                process.stderr.write(`${line}\n`);
+                process.stdout.write(`${line}\n`);
             },
-            threshold: LEVEL_RANK[parseLogLevel(process.env.LOG_LEVEL)],
+            threshold: SEVERITY_NUMBER[parseLogLevel(process.env.LOG_LEVEL)],
+            service: serviceFromEnv(),
+            context: new AsyncLocalStorage(),
         };
         store[slot] = found;
     }
     return found;
 }
-/** Python's `datetime.isoformat()` for an aware UTC datetime: `...T04:05:06.789000+00:00`. */
-export function pythonIsoTimestamp(date) {
-    return date.toISOString().replace("Z", "000+00:00");
+const NANOS_PER_MS = 1000000n;
+const NANOS_PER_SECOND = 1000000000n;
+/**
+ * RFC 3339 in UTC with nine fractional digits: `2026-10-16T04:05:06.789000000Z`.
+ * Takes a Date (millisecond precision, so the last six digits are zero) or
+ * nanoseconds since the epoch as a bigint (every digit kept).
+ */
+export function formatTimestamp(time) {
+    const nanos = typeof time === "bigint" ? time : BigInt(time.getTime()) * NANOS_PER_MS;
+    const seconds = nanos / NANOS_PER_SECOND;
+    const fraction = (nanos % NANOS_PER_SECOND).toString().padStart(9, "0");
+    const whole = new Date(Number(seconds) * 1000).toISOString().slice(0, 19);
+    return `${whole}.${fraction}Z`;
 }
-/** Send lines somewhere other than stderr (tests). Returns a restore function. */
+/** Send lines somewhere other than stdout (tests). Returns a restore function. */
 export function setLogSink(sink) {
     const current = state();
     const previous = current.sink;
@@ -52,57 +90,153 @@ export function setLogSink(sink) {
     };
 }
 export function setLogLevel(level) {
-    state().threshold = LEVEL_RANK[level];
+    state().threshold = SEVERITY_NUMBER[toLevel(level)];
+}
+/**
+ * Set the service fields explicitly; given fields replace the ones from the
+ * environment. Returns a restore function.
+ */
+export function setLogService(service) {
+    const current = state();
+    const previous = current.service;
+    const next = { ...previous };
+    for (const key of ["name", "version", "environment"]) {
+        const value = nonBlank(service[key]);
+        if (value !== undefined)
+            next[key] = value;
+    }
+    current.service = next;
+    return () => {
+        current.service = previous;
+    };
+}
+function mergeContext(parent, child) {
+    const merged = { ...parent };
+    if (child.enduserId !== undefined)
+        merged.enduserId = child.enduserId;
+    if (child.traceId !== undefined)
+        merged.traceId = child.traceId;
+    if (child.spanId !== undefined)
+        merged.spanId = child.spanId;
+    if (child.attributes !== undefined)
+        merged.attributes = { ...parent?.attributes, ...child.attributes };
+    return merged;
+}
+/**
+ * Run `fn` with `context` added to every log line written inside it,
+ * including in async work it starts. Nested scopes inherit the outer fields
+ * and may override them.
+ */
+export function withLogContext(context, fn) {
+    const store = state().context;
+    return store.run(mergeContext(store.getStore(), context), fn);
+}
+/**
+ * Add fields to the current `withLogContext` scope, for example `enduserId`
+ * once the session is known. The whole scope sees them, including lines
+ * written after this call by code that started earlier. Outside a scope it
+ * changes nothing and returns false.
+ */
+export function setLogContext(context) {
+    const current = state().context.getStore();
+    if (current === undefined)
+        return false;
+    Object.assign(current, mergeContext(current, context));
+    return true;
+}
+/** The current scope's fields, or undefined outside `withLogContext`. */
+export function getLogContext() {
+    const current = state().context.getStore();
+    return current === undefined ? undefined : { ...current };
 }
 function jsonReplacer(_key, value) {
-    // Python's json.dumps(default=str) stringifies what JSON cannot carry.
+    // Stringify what JSON cannot carry instead of throwing.
     if (typeof value === "bigint")
         return value.toString();
     if (value instanceof Error)
         return String(value);
     return value;
 }
-function formatError(err) {
-    if (err instanceof Error)
-        return err.stack ?? `${err.name}: ${err.message}`;
-    return String(err);
+function exceptionFields(err) {
+    if (!(err instanceof Error))
+        return { "exception.message": String(err) };
+    const ctor = err.constructor?.name;
+    const type = ctor && ctor !== "Error" ? ctor : err.name;
+    return {
+        "exception.type": type,
+        "exception.message": err.message,
+        "exception.stacktrace": err.stack ?? `${type}: ${err.message}`,
+    };
 }
-export function formatRecord(level, logger, msg, extra, err, now = new Date()) {
+const RESERVED = new Set([
+    "timestamp",
+    "severity_text",
+    "severity_number",
+    "body",
+    "logger.name",
+    "service.name",
+    "service.version",
+    "deployment.environment.name",
+    "trace_id",
+    "span_id",
+    "enduser.id",
+    "exception.type",
+    "exception.message",
+    "exception.stacktrace",
+]);
+export function formatRecord(level, logger, body, extra, err, now = new Date(), scope) {
+    const severity = toLevel(level);
+    const service = scope?.service ?? state().service;
+    const context = scope ? scope.context : state().context.getStore();
     const payload = {
-        ts: pythonIsoTimestamp(now),
-        level,
-        logger,
-        msg,
+        timestamp: formatTimestamp(now),
+        severity_text: severity,
+        severity_number: SEVERITY_NUMBER[severity],
+        body,
+        "logger.name": logger,
     };
-    if (extra) {
-        for (const [key, value] of Object.entries(extra)) {
-            if (!(key in payload))
-                payload[key] = value;
-        }
+    if (service.name !== undefined)
+        payload["service.name"] = service.name;
+    if (service.version !== undefined)
+        payload["service.version"] = service.version;
+    if (service.environment !== undefined)
+        payload["deployment.environment.name"] = service.environment;
+    if (context?.traceId !== undefined)
+        payload.trace_id = context.traceId;
+    if (context?.spanId !== undefined)
+        payload.span_id = context.spanId;
+    if (context?.enduserId !== undefined)
+        payload["enduser.id"] = context.enduserId;
+    const attributes = { ...context?.attributes, ...extra };
+    for (const [key, value] of Object.entries(attributes)) {
+        if (!RESERVED.has(key))
+            payload[key] = value;
     }
     if (err !== undefined)
-        payload.exc = formatError(err);
+        Object.assign(payload, exceptionFields(err));
     return JSON.stringify(payload, jsonReplacer);
 }
 export function getLogger(name) {
     const emit = (level, msg, extra, err) => {
         const current = state();
-        if (LEVEL_RANK[level] < current.threshold)
+        if (SEVERITY_NUMBER[toLevel(level)] < current.threshold)
             return;
         current.sink(formatRecord(level, name, msg, extra, err));
     };
     return {
         debug: (msg, extra) => emit("DEBUG", msg, extra),
         info: (msg, extra) => emit("INFO", msg, extra),
-        warning: (msg, extra) => emit("WARNING", msg, extra),
+        warn: (msg, extra) => emit("WARN", msg, extra),
+        warning: (msg, extra) => emit("WARN", msg, extra),
         error: (msg, extra) => emit("ERROR", msg, extra),
+        fatal: (msg, extra) => emit("FATAL", msg, extra),
         exception: (msg, err, extra) => emit("ERROR", msg, extra, err),
         record: emit,
     };
 }
 const CONSOLE_LEVELS = {
     error: "ERROR",
-    warn: "WARNING",
+    warn: "WARN",
     log: "INFO",
     info: "INFO",
     debug: "DEBUG",
@@ -111,8 +245,8 @@ const CONSOLE_LEVELS = {
 /**
  * Route console.* through the JSON-lines logger (logger "console"), so the
  * framework's own output (Nitro's error handler, srvx's banner, uncaught
- * errors) is JSON lines too. An Error argument goes under `exc` with its
- * stack, as one line. Returns a function that puts the old methods back.
+ * errors) is JSON lines too. An Error argument goes under `exception.*`, as
+ * one line. Returns a function that puts the old methods back.
  */
 export function installJsonConsole(target = console) {
     const consoleLog = getLogger("console");

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@viktorbarzin/log",
-	"version": "0.1.0",
-	"description": "JSON-lines logger for the homelab app platform: ts, level, logger, msg, extras, exc.",
+	"version": "1.0.0",
+	"description": "JSON-lines logger with OpenTelemetry log field names: timestamp, severity, body, service, trace and enduser context, exception fields.",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",