@kindgi/log 0.0.0-stage → 0.1.4

package/src/trace.ts

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * W3C Trace Context (`traceparent`), the ids every record written inside a
+ * request or a run carries: honour a caller's trace, or start one, and give
+ * each request its own span. Pure functions on Web Crypto, so they run in
+ * Node and in workers alike. No spans are recorded or exported here.
+ */
+
+export interface TraceContext {
+  /** 32 lowercase hex characters, not all zero. */
+  readonly traceId: string;
+  /** 16 lowercase hex characters, not all zero: this span. */
+  readonly spanId: string;
+  /** The span this one is a child of, when there is one. */
+  readonly parentSpanId?: string;
+  /** Trace flags, two hex characters; `01` is sampled. */
+  readonly flags: string;
+}
+
+const TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(?:-.*)?$/;
+
+/**
+ * An incoming `traceparent`'s trace id and parent span, or `undefined`
+ * when the header is absent or malformed: then the caller starts a fresh
+ * trace (a bad header is replaced, never trusted). Version `ff` is
+ * invalid; a future version is read by its first four fields, as the
+ * spec says. All-zero ids are invalid.
+ */
+export function parseTraceparent(
+  header: string | null | undefined,
+): { readonly traceId: string; readonly parentSpanId: string; readonly flags: string } | undefined {
+  if (typeof header !== 'string') return undefined;
+  // Hex must be lowercase (the spec): an uppercase header is malformed.
+  const m = TRACEPARENT.exec(header.trim());
+  if (m === null) return undefined;
+  const [, version, traceId, parentSpanId, flags] = m as unknown as [
+    string,
+    string,
+    string,
+    string,
+    string,
+  ];
+  if (version === 'ff') return undefined;
+  if (version === '00' && header.trim().length !== 55) return undefined;
+  if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId)) return undefined;
+  return { traceId, parentSpanId, flags };
+}
+
+function randomHex(bytes: number): string {
+  for (;;) {
+    const buf = new Uint8Array(bytes);
+    globalThis.crypto.getRandomValues(buf);
+    const hex = [...buf].map((b) => b.toString(16).padStart(2, '0')).join('');
+    if (!/^0+$/.test(hex)) return hex;
+  }
+}
+
+/** A fresh trace: a new trace id and a first span, sampled. */
+export function newTraceContext(): TraceContext {
+  return { traceId: randomHex(16), spanId: randomHex(8), flags: '01' };
+}
+
+/** A new span in the same trace, whose parent is `parent`'s span. */
+export function childSpan(parent: TraceContext): TraceContext {
+  return {
+    traceId: parent.traceId,
+    spanId: randomHex(8),
+    parentSpanId: parent.spanId,
+    flags: parent.flags,
+  };
+}
+
+/**
+ * The context for a request: a child span of the caller's trace when its
+ * `traceparent` is valid, else a fresh trace.
+ */
+export function traceFromHeader(header: string | null | undefined): TraceContext {
+  const incoming = parseTraceparent(header);
+  if (incoming === undefined) return newTraceContext();
+  return {
+    traceId: incoming.traceId,
+    spanId: randomHex(8),
+    parentSpanId: incoming.parentSpanId,
+    flags: incoming.flags,
+  };
+}
+
+/** The `traceparent` (and `traceresponse`) value for a context: `00-<trace>-<span>-<flags>`. */
+export function formatTraceparent(ctx: TraceContext): string {
+  return `00-${ctx.traceId}-${ctx.spanId}-${ctx.flags}`;
+}

package/src/types.ts

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { LogLevel } from './levels.js';
+
+/** A record's fields: values, never text pasted into the message. */
+export type LogFields = Readonly<Record<string, unknown>>;
+
+/**
+ * One log record, the JSON format's line. `time` (RFC 3339), `level`,
+ * `severity` (Cloud Logging's name for the level), `subsystem` and
+ * `message` are always there; the correlation fields come next when
+ * known, then the event's own fields. An error is `err`.
+ */
+export interface LogRecord {
+  readonly time: string;
+  readonly level: LogLevel;
+  readonly severity: string;
+  readonly subsystem: string;
+  readonly message: string;
+  readonly traceId?: string;
+  readonly spanId?: string;
+  readonly requestId?: string;
+  readonly tenantId?: string;
+  readonly projectId?: string;
+  readonly runId?: string;
+  readonly err?: SerializedError;
+  readonly [field: string]: unknown;
+}
+
+/** An error, as a record carries it. `stack` at `error`, or when the logger is at `debug` or below. */
+export interface SerializedError {
+  readonly name: string;
+  readonly message: string;
+  readonly code?: string;
+  readonly stack?: string;
+  readonly cause?: SerializedError | string;
+}
+
+/**
+ * How one record is written, beyond its fields.
+ *
+ *   - `inMessage`: the fields its message already states. The access
+ *     line `GET /v1/runs/:runId 200 12ms` states `method`, `route`,
+ *     `status` and `durationMs`. The pretty format leaves them out, so
+ *     a terminal line doesn't say everything twice; JSON keeps every
+ *     field, for queries.
+ */
+export interface LogOptions {
+  readonly inMessage?: readonly string[];
+}
+
+/**
+ * A logger. `child` returns one whose records all carry `bindings`
+ * (`log.child({ subsystem: 'leases' })`, `log.child({ runId })`); a
+ * child's `subsystem` replaces its parent's, so name it in full
+ * (`kernel.sweeper`). Pass an error as `{ err: error }`.
+ */
+export interface Logger {
+  error(message: string, fields?: LogFields, options?: LogOptions): void;
+  warn(message: string, fields?: LogFields, options?: LogOptions): void;
+  info(message: string, fields?: LogFields, options?: LogOptions): void;
+  debug(message: string, fields?: LogFields, options?: LogOptions): void;
+  trace(message: string, fields?: LogFields, options?: LogOptions): void;
+  child(bindings: LogFields): Logger;
+  /** Whether a record at `level` would be written: skip building costly fields when it wouldn't. */
+  isLevelEnabled(level: LogLevel): boolean;
+}
+
+export type LogFormat = 'json' | 'pretty';