@ontrails/observability 0.2.0

package/src/dev.ts

@@ -0,0 +1,37 @@
+/**
+ * Developer-state observability tools.
+ *
+ * This subpath owns local trace storage, query trails, and sampling state.
+ * Core retains the runtime trace record and sink registry contracts.
+ */
+export { DEFAULT_SAMPLING, shouldSample } from './dev/sampling.js';
+export type { SamplingConfig } from './dev/sampling.js';
+export { tracingResource } from './dev/tracing-resource.js';
+export { tracingQuery } from './dev/trails/tracing-query.js';
+export { tracingStatus } from './dev/trails/tracing-status.js';
+export {
+  clearTraceStore,
+  clearTracingState,
+  getTraceStore,
+  getTracingState,
+  registerTraceStore,
+  registerTracingState,
+} from './dev/tracing-state.js';
+export type { TracingState } from './dev/tracing-state.js';
+export { createDevStore, toTraceStore } from './dev/store.js';
+export type {
+  DevStore,
+  DevStoreOptions,
+  DevStoreQueryOptions,
+  TraceStore,
+} from './dev/store.js';
+export {
+  applyTraceCleanup,
+  countTraceRecords,
+  DEFAULT_MAX_AGE,
+  DEFAULT_MAX_RECORDS,
+  ensureTraceSchema,
+  previewTraceCleanup,
+  withTraceStoreDb,
+} from './dev/internal/dev-state.js';
+export type { TraceCleanupReport } from './dev/internal/dev-state.js';

package/src/formatters.ts

@@ -0,0 +1,160 @@
+import type { LogFormatter, LogRecord } from '@ontrails/core';
+
+export interface PrettyFormatterOptions {
+  /** Show timestamps. Defaults to true. */
+  readonly timestamps?: boolean | undefined;
+  /** Use ANSI colors. Defaults to false for deterministic output. */
+  readonly colors?: boolean | undefined;
+}
+
+/**
+ * Build a JSON.stringify replacer that:
+ *  - serializes BigInt as a decimal string,
+ *  - replaces functions/symbols with a tagged sentinel,
+ *  - breaks circular references with a sentinel rather than throwing.
+ *
+ * Circular detection tracks the *ancestor path* from root to the current
+ * value rather than the set of all previously visited objects. This lets
+ * a metadata payload reuse the same nested object in multiple sibling
+ * positions (for example `{ a: shared, b: shared }`) without the second
+ * occurrence being mislabelled as `[Circular]`. JSON.stringify invokes
+ * the replacer with `this` bound to the immediate parent, so we can
+ * maintain a path stack by popping entries until the top matches the
+ * current parent before deciding whether the new value is on that path.
+ *
+ * The replacer is created per `JSON.stringify` invocation so the path
+ * stack does not leak across log records or between metadata entries.
+ */
+const createSafeReplacer = (): ((
+  this: unknown,
+  key: string,
+  value: unknown
+) => unknown) => {
+  const path: object[] = [];
+  return function safeReplacer(
+    this: unknown,
+    _key: string,
+    value: unknown
+  ): unknown {
+    if (typeof value === 'bigint') {
+      return value.toString();
+    }
+    if (typeof value === 'function') {
+      return '[Function]';
+    }
+    if (typeof value === 'symbol') {
+      return value.toString();
+    }
+    if (typeof value !== 'object' || value === null) {
+      return value;
+    }
+    // Pop entries that are no longer ancestors of the current value.
+    // JSON.stringify's depth-first walk binds `this` to the immediate
+    // parent, so anything above `this` on the stack has been left.
+    while (path.length > 0 && path.at(-1) !== this) {
+      path.pop();
+    }
+    if (path.includes(value)) {
+      return '[Circular]';
+    }
+    path.push(value);
+    return value;
+  };
+};
+
+/**
+ * Format log records as newline-delimited JSON objects.
+ *
+ * Metadata values that JSON.stringify cannot natively serialize are sanitized
+ * to safe representations: `BigInt` becomes its decimal string, functions and
+ * symbols are tagged sentinels, and circular references are replaced with
+ * `"[Circular]"` rather than throwing. The formatter never throws on a
+ * structurally valid `LogRecord`.
+ */
+export const createJsonFormatter = (): LogFormatter => ({
+  format(record: LogRecord): string {
+    const { category, level, message, metadata, timestamp } = record;
+    return JSON.stringify(
+      {
+        ...metadata,
+        category,
+        level,
+        message,
+        timestamp: timestamp.toISOString(),
+      },
+      createSafeReplacer()
+    );
+  },
+});
+
+const LEVEL_COLORS: Record<string, string> = {
+  debug: '\u001B[36m',
+  error: '\u001B[31m',
+  fatal: '\u001B[35m',
+  info: '\u001B[32m',
+  trace: '\u001B[90m',
+  warn: '\u001B[33m',
+};
+
+const RESET = '\u001B[0m';
+
+const formatTimestamp = (timestamp: Date): string =>
+  `${timestamp.toISOString().slice(11, 19)} `;
+
+const formatMetadata = (metadata: Record<string, unknown>): string => {
+  const entries = Object.entries(metadata);
+  if (entries.length === 0) {
+    return '';
+  }
+  // Use the same safe replacer as the JSON formatter so BigInt, functions,
+  // symbols, and circular references never throw from the pretty path.
+  // The replacer is created per `format` call so the ancestor path stack
+  // does not leak across log records. The stack self-resets at the start
+  // of each `JSON.stringify` invocation because the new call's wrapper is
+  // a fresh object that does not match anything left on the stack, so the
+  // pop-loop drains it before the first value is inspected. Wrapping each
+  // value in an array ensures the replacer observes top-level BigInt,
+  // function, and symbol values, which `JSON.stringify` would otherwise
+  // drop or throw on before invoking it.
+  const replacer = createSafeReplacer();
+  return `  ${entries
+    .map(([key, value]) => {
+      if (typeof value === 'string') {
+        return `${key}=${value}`;
+      }
+      const wrapped = JSON.stringify([value], replacer);
+      // Strip the surrounding `[` and `]` from the wrapped array form.
+      const display = wrapped.slice(1, -1);
+      return `${key}=${display}`;
+    })
+    .join(' ')}`;
+};
+
+const formatLevel = (level: string, useColors: boolean): string => {
+  const label = level.toUpperCase().padEnd(5);
+  if (!useColors) {
+    return label;
+  }
+  const color = LEVEL_COLORS[level] ?? '';
+  return `${color}${label}${RESET}`;
+};
+
+/** Format log records for human-readable local output. */
+export const createPrettyFormatter = (
+  options: PrettyFormatterOptions = {}
+): LogFormatter => {
+  const showTimestamps = options.timestamps !== false;
+  const useColors = options.colors === true;
+
+  return {
+    format(record: LogRecord): string {
+      const prefix = showTimestamps ? formatTimestamp(record.timestamp) : '';
+      const level = formatLevel(record.level, useColors);
+      const metadata = formatMetadata(record.metadata);
+      const body = `${level} [${record.category}] ${record.message}`;
+      return metadata.length > 0
+        ? `${prefix}${body}${metadata}`
+        : `${prefix}${body}`;
+    },
+  };
+};

package/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Primitive observability API for Trails.
+ *
+ * `@ontrails/observability` is the public package for log and trace sink contracts.
+ * Adapter packages should build on these types instead of importing
+ * framework internals directly.
+ *
+ * @see {@link https://github.com/outfitter-dev/trails/blob/main/docs/adr/0041-unified-observability.md | ADR-0041 Unified Observability}
+ */
+export { combine } from './combine.js';
+export { createJsonFormatter, createPrettyFormatter } from './formatters.js';
+export {
+  DEFAULT_MEMORY_SINK_MAX_RECORDS,
+  createBoundedMemorySink,
+  createMemorySink,
+} from './memory.js';
+export { renderTraceTree } from './renderer.js';
+export { createConsoleSink, createFileSink } from './sinks.js';
+export type { CombinedSink } from './combine.js';
+export type { PrettyFormatterOptions } from './formatters.js';
+export type { MemorySinkOptions, MemoryTraceSink } from './memory.js';
+export type {
+  ConsoleSinkOptions,
+  FileLogSink,
+  FileSinkConfig,
+  FileSinkOptions,
+} from './sinks.js';
+
+export type {
+  Logger,
+  LogFormatter,
+  LogLevel,
+  LogRecord,
+  LogSink,
+  ObserveCapabilities,
+  ObserveConfig,
+  ObserveInput,
+  TraceContext,
+  TraceRecord,
+  TraceSink,
+} from '@ontrails/core';

package/src/memory.ts

@@ -0,0 +1,61 @@
+import type { TraceRecord, TraceSink } from '@ontrails/core';
+
+export const DEFAULT_MEMORY_SINK_MAX_RECORDS = 1000;
+
+export interface MemorySinkOptions {
+  /** Maximum records retained in memory. Defaults to {@link DEFAULT_MEMORY_SINK_MAX_RECORDS}. */
+  readonly maxRecords?: number | undefined;
+}
+
+export interface MemoryTraceSink extends TraceSink {
+  /** Maximum retained records before older entries are dropped. */
+  readonly maxRecords: number;
+  /** Number of records dropped since the last clear. */
+  readonly droppedCount: number;
+  /** Remove retained records and reset the dropped counter. */
+  clear(): void;
+  /** Return retained records, oldest first, as a stable snapshot. */
+  records(): readonly TraceRecord[];
+}
+
+const normalizeMaxRecords = (value: number | undefined): number => {
+  const maxRecords = value ?? DEFAULT_MEMORY_SINK_MAX_RECORDS;
+  if (!Number.isInteger(maxRecords) || maxRecords < 1) {
+    throw new RangeError(
+      'Memory trace sink maxRecords must be a positive integer'
+    );
+  }
+  return maxRecords;
+};
+
+/** Bounded in-memory trace sink for tests, dogfood tooling, and local trace rendering. */
+export const createMemorySink = (
+  options: MemorySinkOptions = {}
+): MemoryTraceSink => {
+  const maxRecords = normalizeMaxRecords(options.maxRecords);
+  const retained: TraceRecord[] = [];
+  let droppedCount = 0;
+
+  return {
+    clear() {
+      retained.length = 0;
+      droppedCount = 0;
+    },
+    get droppedCount() {
+      return droppedCount;
+    },
+    maxRecords,
+    records: () => [...retained],
+    write(record) {
+      retained.push(record);
+      const overflow = retained.length - maxRecords;
+      if (overflow > 0) {
+        retained.splice(0, overflow);
+        droppedCount += overflow;
+      }
+    },
+  };
+};
+
+/** @alias */
+export const createBoundedMemorySink = createMemorySink;

package/src/otel.ts

@@ -0,0 +1,274 @@
+import type { TraceRecord, TraceSink } from '@ontrails/core';
+
+type OtelAttributeValue = string | number | boolean;
+
+/** OTel span representation produced by the adapter. */
+export interface OtelSpan {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly parentSpanId?: string | undefined;
+  readonly operationName: string;
+  readonly startTime: number;
+  readonly endTime?: number | undefined;
+  readonly status: 'OK' | 'ERROR' | 'UNSET';
+  readonly kind: 'INTERNAL' | 'SERVER';
+  readonly attributes: Readonly<Record<string, OtelAttributeValue>>;
+}
+
+/** Callback that receives translated OTel spans. */
+export type OtelExporter = (spans: readonly OtelSpan[]) => void | Promise<void>;
+
+/** Configuration for the OTel adapter. */
+export interface OtelAdapterOptions {
+  readonly exporter: OtelExporter;
+  readonly batchSize?: number;
+}
+
+/** Map from TraceRecord status to OTel status. */
+const STATUS_MAP: Record<TraceRecord['status'], OtelSpan['status']> = {
+  cancelled: 'UNSET',
+  err: 'ERROR',
+  ok: 'OK',
+};
+
+/** Derive OTel span kind from parentId presence. */
+const deriveKind = (parentId: string | undefined): OtelSpan['kind'] =>
+  parentId === undefined ? 'SERVER' : 'INTERNAL';
+
+const SAFE_SIGNAL_PAYLOAD_ATTRIBUTE_KEYS = new Set([
+  'trails.signal.payload.byte_length',
+  'trails.signal.payload.digest',
+  'trails.signal.payload.redacted',
+  'trails.signal.payload.shape',
+  'trails.signal.payload.top_level_entry_count',
+]);
+
+const UNSAFE_SENSITIVE_ATTRIBUTE_SEGMENTS = new Set([
+  'authorization',
+  'cookie',
+  'password',
+  'secret',
+  'token',
+]);
+const UNSAFE_RAW_ATTRIBUTE_NAMES = new Set([
+  'body',
+  'input',
+  'output',
+  'payload',
+]);
+
+const UNSAFE_ATTRIBUTE_KEYS = new Set([
+  'error.message',
+  'error.stack',
+  'exception.message',
+  'exception.stacktrace',
+  'message',
+  'stack',
+  'stacktrace',
+]);
+
+const normalizeAttributeKey = (key: string): string =>
+  key.replaceAll(/([a-z\d])([A-Z])/g, '$1_$2').toLowerCase();
+
+const splitAttributeKey = (key: string): readonly string[] =>
+  normalizeAttributeKey(key).split(/[._-]+/u);
+
+const isUnsafeCustomAttributeKey = (key: string): boolean => {
+  const normalized = normalizeAttributeKey(key);
+  if (SAFE_SIGNAL_PAYLOAD_ATTRIBUTE_KEYS.has(normalized)) {
+    return false;
+  }
+  if (
+    UNSAFE_ATTRIBUTE_KEYS.has(normalized) ||
+    normalized.endsWith('.error.message') ||
+    normalized.endsWith('.error.stack') ||
+    normalized.endsWith('.exception.message') ||
+    normalized.endsWith('.exception.stacktrace')
+  ) {
+    return true;
+  }
+  const parts = splitAttributeKey(normalized);
+  if (parts.some((part) => UNSAFE_SENSITIVE_ATTRIBUTE_SEGMENTS.has(part))) {
+    return true;
+  }
+  const last = parts.at(-1);
+  if (last !== undefined && UNSAFE_RAW_ATTRIBUTE_NAMES.has(last)) {
+    return true;
+  }
+  return parts.includes('payload');
+};
+
+const isOtelAttributeValue = (value: unknown): value is OtelAttributeValue =>
+  typeof value === 'string' ||
+  typeof value === 'number' ||
+  typeof value === 'boolean';
+
+/** Attribute mapping: record field → OTel attribute key + extractor. */
+const ATTR_MAP: readonly {
+  key: string;
+  get: (r: TraceRecord) => OtelAttributeValue | undefined;
+}[] = [
+  {
+    get: (r) => (r.kind === 'activation' ? r.name : undefined),
+    key: 'trails.activation.event',
+  },
+  { get: (r) => r.errorCategory, key: 'trails.error.category' },
+  { get: (r) => r.intent, key: 'trails.intent' },
+  { get: (r) => r.permit?.id, key: 'trails.permit.id' },
+  { get: (r) => r.permit?.tenantId, key: 'trails.permit.tenant_id' },
+  { get: (r) => r.kind, key: 'trails.record.kind' },
+  { get: (r) => r.name, key: 'trails.record.name' },
+  { get: (r) => r.sampled, key: 'trails.sampled' },
+  {
+    get: (r) => (r.kind === 'signal' ? r.name : undefined),
+    key: 'trails.signal.event',
+  },
+  { get: (r) => r.id, key: 'trails.span.id' },
+  { get: (r) => r.parentId, key: 'trails.span.parent_id' },
+  { get: (r) => r.rootId, key: 'trails.span.root_id' },
+  { get: (r) => r.status, key: 'trails.status' },
+  { get: (r) => r.surface, key: 'trails.surface' },
+  {
+    get: (r) => (r.endedAt === undefined ? undefined : r.endedAt - r.startedAt),
+    key: 'trails.timing.duration_ms',
+  },
+  { get: (r) => r.endedAt, key: 'trails.timing.ended_at_ms' },
+  { get: (r) => r.startedAt, key: 'trails.timing.started_at_ms' },
+  { get: (r) => r.traceId, key: 'trails.trace.id' },
+  { get: (r) => r.trailId, key: 'trails.trail.id' },
+];
+
+const STABLE_ATTRIBUTE_KEYS = new Set(ATTR_MAP.map(({ key }) => key));
+
+/** Build the trails-namespaced attributes from a TraceRecord. */
+const buildAttributes = (
+  record: TraceRecord
+): Record<string, OtelAttributeValue> => {
+  const attrs: Record<string, OtelAttributeValue> = {};
+  for (const { key, get } of ATTR_MAP) {
+    const val = get(record);
+    if (val !== undefined) {
+      attrs[key] = val;
+    }
+  }
+  for (const [key, val] of Object.entries(record.attrs)) {
+    if (
+      attrs[key] === undefined &&
+      !STABLE_ATTRIBUTE_KEYS.has(key) &&
+      !isUnsafeCustomAttributeKey(key) &&
+      isOtelAttributeValue(val)
+    ) {
+      attrs[key] = val;
+    }
+  }
+  return attrs;
+};
+
+/** Translate a TraceRecord into an OTel span. */
+const toOtelSpan = (record: TraceRecord): OtelSpan => ({
+  attributes: buildAttributes(record),
+  endTime: record.endedAt,
+  kind: deriveKind(record.parentId),
+  operationName: record.name,
+  parentSpanId: record.parentId,
+  spanId: record.id,
+  startTime: record.startedAt,
+  status: STATUS_MAP[record.status],
+  traceId: record.traceId,
+});
+
+/** A TraceSink extended with an explicit flush for shutdown. */
+export interface OtelSink extends TraceSink {
+  /**
+   * Flush any remaining buffered spans to the exporter.
+   *
+   * Call this during shutdown after the app stops accepting new work. Concurrent
+   * flush calls await the same in-flight export. If the exporter rejects, the
+   * failed batch is restored to the buffer so a later flush can retry it.
+   */
+  readonly flush: () => Promise<void>;
+}
+
+/**
+ * Create a TraceSink that translates Tracing to OTel spans.
+ *
+ * The adapter maps Trails-native fields to OpenTelemetry span attributes
+ * under a `trails.*` namespace. Pass any OTel-compatible exporter callback
+ * to forward spans to your collector.
+ *
+ * Translates and exports spans on each write. Call `flush()` on shutdown
+ * to send any remaining buffered spans.
+ */
+export const createOtelAdapter = (options: OtelAdapterOptions): OtelSink => {
+  const batchSize = options.batchSize ?? 1;
+  if (!(Number.isSafeInteger(batchSize) && batchSize > 0)) {
+    throw new RangeError('OTel adapter batchSize must be a positive integer');
+  }
+  const buffer: OtelSpan[] = [];
+  let activeFlush: Promise<void> | undefined;
+  let flushAllRequested = false;
+
+  const exportBuffered = async (): Promise<void> => {
+    const batch = buffer.splice(0);
+    try {
+      await options.exporter(batch);
+    } catch (error) {
+      // Restore batch on exporter failure so data is not lost.
+      buffer.unshift(...batch);
+      throw error;
+    }
+  };
+
+  const startFlush = (request?: {
+    readonly flushAll?: boolean;
+  }): Promise<void> => {
+    if (request?.flushAll === true) {
+      flushAllRequested = true;
+    }
+    if (activeFlush !== undefined) {
+      return activeFlush;
+    }
+    if (
+      buffer.length === 0 ||
+      (request?.flushAll !== true && buffer.length < batchSize)
+    ) {
+      if (buffer.length === 0) {
+        flushAllRequested = false;
+      }
+      return Promise.resolve();
+    }
+    activeFlush = (async () => {
+      try {
+        let shouldContinue = true;
+        do {
+          await exportBuffered();
+          shouldContinue =
+            buffer.length > 0 &&
+            (flushAllRequested || buffer.length >= batchSize);
+        } while (shouldContinue);
+      } finally {
+        activeFlush = undefined;
+        if (buffer.length === 0) {
+          flushAllRequested = false;
+        }
+      }
+    })();
+    return activeFlush;
+  };
+
+  const flush = (): Promise<void> => startFlush({ flushAll: true });
+
+  const maybeFlush = async (): Promise<void> => {
+    while (buffer.length >= batchSize) {
+      await startFlush();
+    }
+  };
+
+  return {
+    flush,
+    write: async (record: TraceRecord): Promise<void> => {
+      buffer.push(toOtelSpan(record));
+      await maybeFlush();
+    },
+  };
+};