@viktorbarzin/log 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @viktorbarzin/log
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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,
+	setLogContext,
+	withLogContext,
+} from "@viktorbarzin/log";
+
+const log = getLogger("myapp.sync");
+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
+{"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`, `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 `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
+
+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

@@ -0,0 +1,87 @@
+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;
+/** 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;
+/** 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: 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;
+    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 `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 `exception.*`, as
+ * one line. Returns a function that puts the old methods back.
+ */
+export declare function installJsonConsole(target?: Console): () => void;

package/dist/index.js

@@ -0,0 +1,268 @@
+/**
+ * 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, 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";
+/** OpenTelemetry severity numbers: the first number of each range. */
+export const SEVERITY_NUMBER = {
+    DEBUG: 5,
+    INFO: 9,
+    WARN: 13,
+    ERROR: 17,
+    FATAL: 21,
+};
+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 === "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;
+    const slot = Symbol.for("@viktorbarzin:log");
+    let found = store[slot];
+    if (found === undefined) {
+        found = {
+            sink: (line) => {
+                process.stdout.write(`${line}\n`);
+            },
+            threshold: SEVERITY_NUMBER[parseLogLevel(process.env.LOG_LEVEL)],
+            service: serviceFromEnv(),
+            context: new AsyncLocalStorage(),
+        };
+        store[slot] = found;
+    }
+    return found;
+}
+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 stdout (tests). Returns a restore function. */
+export function setLogSink(sink) {
+    const current = state();
+    const previous = current.sink;
+    current.sink = sink;
+    return () => {
+        current.sink = previous;
+    };
+}
+export function setLogLevel(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) {
+    // 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 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}`,
+    };
+}
+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 = {
+        timestamp: formatTimestamp(now),
+        severity_text: severity,
+        severity_number: SEVERITY_NUMBER[severity],
+        body,
+        "logger.name": logger,
+    };
+    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)
+        Object.assign(payload, exceptionFields(err));
+    return JSON.stringify(payload, jsonReplacer);
+}
+export function getLogger(name) {
+    const emit = (level, msg, extra, err) => {
+        const current = state();
+        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),
+        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: "WARN",
+    log: "INFO",
+    info: "INFO",
+    debug: "DEBUG",
+    trace: "DEBUG",
+};
+/**
+ * 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 `exception.*`, as
+ * one line. Returns a function that puts the old methods back.
+ */
+export function installJsonConsole(target = console) {
+    const consoleLog = getLogger("console");
+    const methods = target;
+    const saved = new Map();
+    for (const [method, level] of Object.entries(CONSOLE_LEVELS)) {
+        saved.set(method, methods[method]);
+        methods[method] = (...args) => {
+            const err = args.find((arg) => arg instanceof Error);
+            const rest = args.filter((arg) => arg !== err);
+            const msg = rest.length > 0 ? format(...rest) : err ? String(err) : "";
+            consoleLog.record(level, msg, undefined, err);
+        };
+    }
+    return () => {
+        for (const [method, fn] of saved)
+            methods[method] = fn;
+    };
+}

package/package.json

@@ -1,6 +1,36 @@
 {
-  "name": "@viktorbarzin/log",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@viktorbarzin/log",
+	"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",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"sideEffects": false,
+	"engines": {
+		"bun": ">=1.4.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ViktorBarzin/app-kit.git",
+		"directory": "packages/log"
+	},
+	"homepage": "https://github.com/ViktorBarzin/app-kit/tree/master/packages/log#readme",
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"build": "tsc -b",
+		"test": "bun test"
+	}
+}