@ontrails/observability 1.0.0-beta.42

package/CHANGELOG.md

@@ -0,0 +1,202 @@
+# @ontrails/observability
+
+## 1.0.0-beta.42
+
+## 1.0.0-beta.41
+
+## 1.0.0-beta.40
+
+### Major Changes
+
+- [`b94cf85`](https://github.com/outfitter-dev/trails/commit/b94cf85011dfe18d34dfdaa74efe381b6295d5e1): Fold LogTape and Pino log forwarding into `@ontrails/observe/logtape` and `@ontrails/observe/pino`, and remove the standalone `@ontrails/logtape` and `@ontrails/pino` workspaces.
+
+## 1.0.0-beta.39
+
+## 1.0.0-beta.38
+
+## 1.0.0-beta.37
+
+## 1.0.0-beta.36
+
+## 1.0.0-beta.35
+
+### Patch Changes
+
+- [`417bd84`](https://github.com/outfitter-dev/trails/commit/417bd8471d0f0f47ad5f33cd2ac1c606eccd72f8): Promote signal trace helpers from tracing compatibility code to core exports, and make tracing's memory sink wrapper use the observe-owned implementation.
+
+## 1.0.0-beta.34
+
+## 1.0.0-beta.33
+
+## 1.0.0-beta.32
+
+### Patch Changes
+
+- Updated dependencies [3e5c0fc]
+- Updated dependencies [f3c4fef]
+- Updated dependencies [cb0a9d8]
+- Updated dependencies [21c6dda]
+- Updated dependencies [fe72b84]
+  - @ontrails/core@1.0.0-beta.32
+
+## 1.0.0-beta.31
+
+### Patch Changes
+
+- Updated dependencies [4cd5d4e]
+- Updated dependencies [38907cc]
+  - @ontrails/core@1.0.0-beta.31
+
+## 1.0.0-beta.30
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.30
+
+## 1.0.0-beta.29
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.29
+
+## 1.0.0-beta.28
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.28
+
+## 1.0.0-beta.27
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.27
+
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- Updated dependencies [1307568]
+- Updated dependencies [371d19e]
+  - @ontrails/core@1.0.0-beta.26
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- Updated dependencies [c36aca9]
+- Updated dependencies [3befcf1]
+- Updated dependencies [a4f9cf6]
+- Updated dependencies [9bcf34e]
+  - @ontrails/core@1.0.0-beta.25
+
+## 1.0.0-beta.24
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.24
+
+## 1.0.0-beta.23
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.23
+
+## 1.0.0-beta.22
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.22
+
+## 1.0.0-beta.21
+
+### Patch Changes
+
+- Updated dependencies [99523f2]
+  - @ontrails/core@1.0.0-beta.21
+
+## 1.0.0-beta.20
+
+### Patch Changes
+
+- Updated dependencies [851a2a3]
+  - @ontrails/core@1.0.0-beta.20
+
+## 1.0.0-beta.19
+
+### Patch Changes
+
+- 1eb5bdc: Rename first-class trail composition from the `cross` API family to the `compose` family across core contracts, testing helpers, topo projections, Warden rules, CLI scaffolds, and docs. `composes`, `ctx.compose`, `composeInput`, and `Compose*` type names are now the public authoring vocabulary; topo persistence migrates legacy composition rows and graph keys forward.
+- Updated dependencies [e41c382]
+- Updated dependencies [1eb5bdc]
+- Updated dependencies [f8d80b9]
+- Updated dependencies [846a597]
+- Updated dependencies [223aaad]
+- Updated dependencies [3125f4d]
+- Updated dependencies [2494dc6]
+- Updated dependencies [2d53717]
+- Updated dependencies [16cb740]
+- Updated dependencies [8894ecb]
+- Updated dependencies [fdf7ec9]
+- Updated dependencies [d76be13]
+- Updated dependencies [84f56a5]
+- Updated dependencies [431b04c]
+- Updated dependencies [5d88104]
+- Updated dependencies [f04a9ef]
+  - @ontrails/core@1.0.0-beta.19
+
+## 1.0.0-beta.18
+
+### Patch Changes
+
+- bf44972: Document Pino sink usage and publish-readiness checks.
+- e0ae995: Document the v1 `@ontrails/tracing/otel` OpenTelemetry adapter boundary, including callback export, stable `trails.*` attributes, flush behavior, and the absence of a standalone `@ontrails/otel` package.
+  - @ontrails/core@1.0.0-beta.18
+
+## 1.0.0-beta.17
+
+### Patch Changes
+
+- Updated dependencies [3dc8254]
+  - @ontrails/core@1.0.0-beta.17
+
+## 1.0.0-beta.16
+
+### Minor Changes
+
+- d40430d: Remove the retired `@ontrails/logging` workspace from the prerelease package set. Use `@ontrails/observe` for log and trace sink contracts and `@ontrails/logtape` for LogTape forwarding.
+- 9cdb0f2: Add `renderTraceTree(records: readonly TraceRecord[]): string` — a pure post-execution renderer that builds a readable execution tree from `TraceRecord` entries. Renders root spans with `●`, children with `├──`/`└──`, status glyphs (`✓`/`✗`/`⊘`), durations, and parallel-branch detection (overlapping siblings render as a bracketed group with wall-vs-total summary). Tolerates forward-compatible record shapes (signal/activation kinds, `attrs.layer` from upcoming layer composition) without crashing — unknown kinds fall through to a generic span renderer. No live streaming; the tree is drawn once after the trail completes.
+- 22c6c06: Accept ADR-0041 Unified Observability and ship the first activation and
+  observability primitives it depends on: activation trace records, topo-level
+  observe configuration, webhook activation materialization, signal/webhook
+  warden coaching, the `@ontrails/observe` package, sink composition, and
+  zero-dependency observe sinks.
+
+### Patch Changes
+
+- 6300f70: Refresh source comments and test labels for retired connector terminology as adapter guardrails become strict.
+- e898cc4: Add repo-level Knip dead-code detection and remove stale internal exports and unused package dependencies surfaced by the new check.
+- a8997ed: Add migration guidance for the retired `@ontrails/logging` package and align observability README examples around `@ontrails/observe`, `@ontrails/tracing`, and `@ontrails/logtape`.
+- fe03945: Document the v1 observability package boundary: `@ontrails/observe` is the production sink contract package, while `@ontrails/tracing` remains the compatibility and developer-state package with the supported `@ontrails/tracing/otel` adapter subpath.
+- 49c2e7d: Refresh published package README taxonomy to use adapter language instead of retired connector vocabulary.
+- Updated dependencies [73622ae]
+- Updated dependencies [6300f70]
+- Updated dependencies [d172013]
+- Updated dependencies [c3fc5c3]
+- Updated dependencies [20d7a5c]
+- Updated dependencies [be5fb46]
+- Updated dependencies [e898cc4]
+- Updated dependencies [3395234]
+- Updated dependencies [bcdc484]
+- Updated dependencies [331e3a9]
+- Updated dependencies [4399fdb]
+- Updated dependencies [4b8d13b]
+- Updated dependencies [112b9f2]
+- Updated dependencies [893025e]
+- Updated dependencies [eec5e9d]
+- Updated dependencies [ebd4434]
+- Updated dependencies [863d473]
+- Updated dependencies [344f2f7]
+- Updated dependencies [26f9ffd]
+- Updated dependencies [10eae9a]
+- Updated dependencies [22c6c06]
+  - @ontrails/core@1.0.0-beta.16

package/README.md

@@ -0,0 +1,40 @@
+# @ontrails/observability
+
+Primitive observability contracts for Trails.
+
+This package is the public home for log and trace sink shapes used by Trails apps and adapters. It includes zero-dependency sinks for local and server baselines, plus adapter composition for production observability.
+
+## V1 package boundary
+
+Use `@ontrails/observability` for app-facing observability contracts and sinks: `LogSink`, `TraceSink`, `combine(...)`, console/file sinks, bounded memory sinks, and trace rendering.
+
+`@ontrails/core` owns intrinsic tracing execution: `TraceRecord`, `ctx.trace()`, trace context propagation, and the process-level trace sink registry.
+
+`@ontrails/observability/dev` owns developer-state tooling: query/status trails, the SQLite dev store, sampling helpers, and state maintenance. Import intrinsic trace records, contexts, and the process-level sink registry from `@ontrails/core`.
+
+For v1, OpenTelemetry trace export lives at `@ontrails/observability/otel`; there is no standalone `@ontrails/otel` package. That adapter translates Trails-native `TraceRecord` values to callback-delivered OTel-shaped spans without requiring the OpenTelemetry SDK as a runtime dependency.
+
+```typescript
+import {
+  combine,
+  createConsoleSink,
+  createFileSink,
+  createMemorySink,
+} from '@ontrails/observability';
+
+const sink = combine(
+  createConsoleSink(),
+  createFileSink('./logs/app.log'),
+  createMemorySink({ maxRecords: 500 })
+);
+```
+
+`createFileSink()` is append-only and does not rotate files. Use external log rotation or a production adapter when retention policy matters.
+
+## Extracted logging adapters
+
+Pino and LogTape are foreign-library boundaries, so they live in extracted adapter packages rather than observability subpaths. Use `@ontrails/pino` for the real Pino integration and `@ontrails/logtape` for the real LogTape integration. `@ontrails/observability` intentionally has no dependency on either library.
+
+## Migration from `@ontrails/logging`
+
+`@ontrails/logging` was retired before v1. Move sink contracts, console/file sinks, formatters, and bounded memory sinks to `@ontrails/observability`. Use `@ontrails/logtape` for LogTape forwarding, `@ontrails/pino` for Pino forwarding, `@ontrails/observability/dev` for developer-state tooling, and `@ontrails/core` for intrinsic trace contracts.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@ontrails/observability",
+  "version": "1.0.0-beta.42",
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./dev": "./src/dev.ts",
+    "./otel": "./src/otel.ts",
+    "./package.json": "./package.json",
+    "./testing": "./src/testing.ts"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "peerDependencies": {
+    "@ontrails/core": "^1.0.0-beta.42",
+    "zod": "^4.3.5"
+  },
+  "trails": {
+    "adapterTargets": {
+      "observability": {
+        "conformance": {
+          "adapterType": "ObservabilityAdapterConformanceAdapter",
+          "casesFactory": "createObservabilityAdapterConformanceCases",
+          "runner": "runConformance"
+        },
+        "placements": [
+          "extracted"
+        ],
+        "testingImport": "@ontrails/observability/testing"
+      }
+    }
+  }
+}

package/src/combine.ts

@@ -0,0 +1,280 @@
+import { ValidationError } from '@ontrails/core';
+import type {
+  LogRecord,
+  LogSink,
+  ObserveCapabilities,
+  TraceRecord,
+  TraceSink,
+} from '@ontrails/core';
+
+type ObserveRecord = LogRecord | TraceRecord;
+type ObserveSink = LogSink | TraceSink;
+type SinkWrite = (record: ObserveRecord) => void | Promise<void>;
+type FlushableSink = ObserveSink & { readonly flush?: () => Promise<void> };
+
+interface SinkFailure {
+  readonly error: unknown;
+  readonly index: number;
+  readonly sinkName: string | undefined;
+}
+
+export interface CombinedSink {
+  readonly name: string;
+  readonly observes: ObserveCapabilities;
+  write(record: LogRecord): void;
+  write(record: TraceRecord): void | Promise<void>;
+  flush(): Promise<void>;
+}
+
+const isPromiseLike = (value: unknown): value is PromiseLike<unknown> =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as { readonly then?: unknown }).then === 'function';
+
+const isLogSink = (sink: ObserveSink): sink is LogSink =>
+  'name' in sink && typeof sink.name === 'string';
+
+const isLogRecord = (record: ObserveRecord): record is LogRecord =>
+  'level' in record && 'message' in record && 'timestamp' in record;
+
+const readObserveCapabilities = (
+  sink: ObserveSink
+): ObserveCapabilities | undefined => {
+  const capabilities = (sink as { readonly observes?: unknown }).observes;
+  if (typeof capabilities !== 'object' || capabilities === null) {
+    return undefined;
+  }
+  const log = (capabilities as ObserveCapabilities).log === true;
+  const trace = (capabilities as ObserveCapabilities).trace === true;
+  if (!log && !trace) {
+    return undefined;
+  }
+  return Object.freeze({
+    ...(log ? { log: true as const } : {}),
+    ...(trace ? { trace: true as const } : {}),
+  });
+};
+
+const capabilitiesForSink = (sink: ObserveSink): ObserveCapabilities =>
+  readObserveCapabilities(sink) ??
+  Object.freeze(
+    isLogSink(sink) ? { log: true as const } : { trace: true as const }
+  );
+
+const combineCapabilities = (
+  sinks: readonly ObserveSink[]
+): ObserveCapabilities => {
+  let log = false;
+  let trace = false;
+  for (const sink of sinks) {
+    const capabilities = capabilitiesForSink(sink);
+    log ||= capabilities.log === true;
+    trace ||= capabilities.trace === true;
+  }
+  return Object.freeze({
+    ...(log ? { log: true as const } : {}),
+    ...(trace ? { trace: true as const } : {}),
+  });
+};
+
+const sinkName = (sink: ObserveSink): string | undefined =>
+  'name' in sink && typeof sink.name === 'string' ? sink.name : undefined;
+
+const flushForSink = (sink: ObserveSink): (() => Promise<void>) | undefined => {
+  const { flush } = sink as FlushableSink;
+  return typeof flush === 'function' ? flush.bind(sink) : undefined;
+};
+
+const canReceiveRecord = (
+  sink: ObserveSink,
+  record: ObserveRecord
+): boolean => {
+  const capabilities = capabilitiesForSink(sink);
+  return isLogRecord(record)
+    ? capabilities.log === true
+    : capabilities.trace === true;
+};
+
+const describeError = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+const createFailureRecord = (
+  failure: SinkFailure,
+  record: ObserveRecord
+): LogRecord => ({
+  category: 'observe.combine',
+  level: 'warn',
+  message: 'Observe sink write failed; continuing with remaining sinks',
+  metadata: {
+    error: describeError(failure.error),
+    sinkIndex: failure.index,
+    ...(failure.sinkName === undefined ? {} : { sinkName: failure.sinkName }),
+    ...(isLogRecord(record)
+      ? { recordCategory: record.category }
+      : { recordId: record.id, traceId: record.traceId }),
+  },
+  timestamp: new Date(),
+});
+
+const writeToSink = (
+  sink: ObserveSink,
+  record: ObserveRecord
+): void | Promise<void> => {
+  // Call via the sink so class-based sinks keep `this` bound. Detaching the
+  // method (e.g. `(sink.write as SinkWrite)(record)`) would lose `this` and
+  // any class-method `write` would throw — silently dropping records since
+  // combine() swallows child errors. Mirrors flushForSink's binding.
+  const write = sink.write as SinkWrite;
+  return write.call(sink, record);
+};
+
+const ignoreReportFailure = async (
+  result: PromiseLike<unknown>
+): Promise<void> => {
+  try {
+    await result;
+  } catch {
+    // Error reporting is best-effort.
+  }
+};
+
+const reportFailures = (
+  sinks: readonly ObserveSink[],
+  failures: readonly SinkFailure[],
+  record: ObserveRecord
+): void => {
+  if (failures.length === 0) {
+    return;
+  }
+
+  const logSinks = sinks
+    .map((sink, index) => ({ index, sink }))
+    .filter(
+      (entry): entry is { readonly index: number; readonly sink: LogSink } =>
+        capabilitiesForSink(entry.sink).log === true && isLogSink(entry.sink)
+    );
+
+  for (const failure of failures) {
+    const failureRecord = createFailureRecord(failure, record);
+    for (const entry of logSinks) {
+      if (entry.index === failure.index) {
+        continue;
+      }
+      try {
+        const result = entry.sink.write(failureRecord);
+        if (isPromiseLike(result)) {
+          void ignoreReportFailure(result);
+        }
+      } catch {
+        // Error reporting is best-effort; the original write path is already isolated.
+      }
+    }
+  }
+};
+
+const createFailure = (
+  sink: ObserveSink,
+  index: number,
+  error: unknown
+): SinkFailure => ({
+  error,
+  index,
+  sinkName: sinkName(sink),
+});
+
+const isolateAsyncWriteFailure = async (
+  result: PromiseLike<unknown>,
+  sink: ObserveSink,
+  index: number,
+  failures: SinkFailure[]
+): Promise<void> => {
+  try {
+    await result;
+  } catch (error) {
+    failures.push(createFailure(sink, index, error));
+  }
+};
+
+const reportAfterPendingWrites = async (
+  pending: readonly Promise<void>[],
+  sinks: readonly ObserveSink[],
+  failures: readonly SinkFailure[],
+  record: ObserveRecord
+): Promise<void> => {
+  await Promise.all(pending);
+  reportFailures(sinks, failures, record);
+};
+
+/**
+ * Compose multiple observability sinks into one fan-out sink.
+ *
+ * @example
+ * ```typescript
+ * const sink = combine(otelSink, fileSink)
+ * const app = topo('app', trails, { observe: sink })
+ * ```
+ *
+ * @remarks
+ * A child sink failure never prevents sibling sinks from receiving the same
+ * record. Failures are swallowed and reported to log-capable sibling sinks
+ * when one is present.
+ */
+export function combine(...sinks: readonly LogSink[]): CombinedSink;
+export function combine(...sinks: readonly TraceSink[]): CombinedSink;
+export function combine(...sinks: readonly ObserveSink[]): CombinedSink;
+export function combine(...sinks: readonly ObserveSink[]): CombinedSink {
+  if (sinks.length === 0) {
+    throw new ValidationError(
+      'combine() requires at least one sink; an empty composition has no observe capabilities and would fail topo validation.'
+    );
+  }
+
+  const observes = combineCapabilities(sinks);
+
+  return {
+    async flush(): Promise<void> {
+      await Promise.all(
+        sinks.map(async (sink) => {
+          const flush = flushForSink(sink);
+          if (flush === undefined) {
+            return;
+          }
+          try {
+            await flush();
+          } catch {
+            // Flush follows write isolation: one broken sink should not block shutdown.
+          }
+        })
+      );
+    },
+    name: 'combined',
+    observes,
+    write(record: ObserveRecord): void | Promise<void> {
+      const failures: SinkFailure[] = [];
+      const pending: Promise<void>[] = [];
+
+      for (const [index, sink] of sinks.entries()) {
+        if (!canReceiveRecord(sink, record)) {
+          continue;
+        }
+        try {
+          const result = writeToSink(sink, record);
+          if (isPromiseLike(result)) {
+            pending.push(
+              isolateAsyncWriteFailure(result, sink, index, failures)
+            );
+          }
+        } catch (error) {
+          failures.push(createFailure(sink, index, error));
+        }
+      }
+
+      if (pending.length === 0) {
+        reportFailures(sinks, failures, record);
+        return undefined;
+      }
+
+      return reportAfterPendingWrites(pending, sinks, failures, record);
+    },
+  };
+}