@graphorin/observability 0.6.0 → 0.7.0

package/src/replay/replay.ts

@@ -0,0 +1,196 @@
+/**
+ * `createReplay(...)` - sanitized-by-default replay primitives.
+ *
+ * Replay never opens the underlying file directly; callers feed it an
+ * iterable of `SpanRecord`s. The {@link createTraceLogReader} helper
+ * (file-backed JSONL) and `getTraceLog(...)` aggregate utility live
+ * alongside this module.
+ *
+ * @packageDocumentation
+ */
+
+import type { Sensitivity } from '@graphorin/core';
+
+import type { SpanRecord } from '../exporters/types.js';
+import { sanitizeRecord } from '../exporters/with-validation.js';
+import type { RedactionValidatorInstance } from '../redaction/types.js';
+import { compareSensitivityTiers, createRedactionValidator } from '../redaction/validator.js';
+
+import type {
+  ReplayAuditBridge,
+  ReplayAuditEvent,
+  ReplayEvent,
+  ReplayOptions,
+  ReplayRunInput,
+} from './types.js';
+
+const DEFAULT_VALIDATOR = createRedactionValidator({ minTier: 'public' });
+const DEFAULT_ACTOR: ReplayAuditEvent['actor'] = { kind: 'system', id: 'in-process' };
+
+/**
+ * @stable
+ */
+export interface Replay {
+  run(input: ReplayRunInput): AsyncIterable<ReplayEvent>;
+}
+
+/**
+ * Build a replay primitive. The returned object exposes a single
+ * `run(...)` async iterator that yields {@link ReplayEvent} records.
+ *
+ * Sanitized mode is the default and applies the configured
+ * {@link RedactionValidatorInstance} to every record. Raw mode
+ * requires the `canReadRaw` callback to return `true` AND emits an
+ * audit log entry on every invocation.
+ *
+ * @stable
+ */
+export function createReplay(opts: ReplayOptions = {}): Replay {
+  const validator: RedactionValidatorInstance = opts.validator ?? DEFAULT_VALIDATOR;
+  const audit: ReplayAuditBridge | undefined = opts.audit;
+  const defaultActor = opts.defaultActor ?? DEFAULT_ACTOR;
+  const canReadRaw = opts.canReadRaw ?? (() => true);
+
+  return {
+    async *run(input: ReplayRunInput): AsyncIterable<ReplayEvent> {
+      const mode = input.mode ?? 'sanitized';
+      const minSensitivity: Sensitivity = input.minSensitivity ?? 'public';
+      const actor = input.actor ?? defaultActor;
+      const start = Date.now();
+
+      if (mode === 'raw' && !canReadRaw({ target: input.target })) {
+        emitAudit(audit, {
+          action: 'trace.replay.accessed',
+          actor,
+          target: input.target,
+          decision: 'denied',
+          metadata: { mode, minSensitivity, eventCount: 0, durationMs: Date.now() - start },
+        });
+        yield { type: 'replay.start', target: input.target, mode };
+        yield { type: 'replay.skipped', reason: 'access-denied', spanId: input.target };
+        yield {
+          type: 'replay.end',
+          durationMs: Date.now() - start,
+          eventsEmitted: 0,
+          eventsSkipped: 1,
+        };
+        return;
+      }
+
+      let emitted = 0;
+      let skipped = 0;
+      let started = false;
+      let reachedFrom = input.fromSpanId === undefined;
+
+      const iterator = isAsyncIterable(input.source)
+        ? input.source[Symbol.asyncIterator]()
+        : asAsync(input.source[Symbol.iterator]());
+
+      try {
+        while (true) {
+          const next = await iterator.next();
+          if (next.done === true) break;
+          const record = next.value;
+
+          if (!started) {
+            started = true;
+            yield { type: 'replay.start', target: input.target, mode };
+          }
+
+          if (!reachedFrom) {
+            if (record.id === input.fromSpanId) reachedFrom = true;
+            else continue;
+          }
+
+          if (mode === 'raw') {
+            yield { type: 'replay.event', span: record, sanitized: false };
+            emitted += 1;
+            continue;
+          }
+
+          if (skipBySensitivity(record, minSensitivity)) {
+            skipped += 1;
+            yield { type: 'replay.skipped', reason: 'sensitivity', spanId: record.id };
+            continue;
+          }
+
+          const sanitized = sanitizeRecord(record, validator);
+          // RP-18: sanitization is attribute-granular and never drops the whole
+          // span. A record arrives pre-flagged with `droppedReason` only if an
+          // upstream stage marked it; honour that, otherwise replay the
+          // stripped span.
+          if (sanitized.droppedReason !== undefined) {
+            skipped += 1;
+            yield {
+              type: 'replay.skipped',
+              reason: 'redaction-violation',
+              spanId: record.id,
+            };
+            continue;
+          }
+
+          yield { type: 'replay.event', span: sanitized, sanitized: true };
+          emitted += 1;
+        }
+      } finally {
+        const durationMs = Date.now() - start;
+        if (!started) {
+          yield { type: 'replay.start', target: input.target, mode };
+        }
+        emitAudit(audit, {
+          action: 'trace.replay.accessed',
+          actor,
+          target: input.target,
+          decision: 'success',
+          metadata: {
+            mode,
+            minSensitivity,
+            ...(input.fromSpanId === undefined ? {} : { fromSpanId: input.fromSpanId }),
+            eventCount: emitted,
+            durationMs,
+          },
+        });
+        yield {
+          type: 'replay.end',
+          durationMs,
+          eventsEmitted: emitted,
+          eventsSkipped: skipped,
+        };
+      }
+    },
+  };
+}
+
+function emitAudit(bridge: ReplayAuditBridge | undefined, event: ReplayAuditEvent): void {
+  if (bridge === undefined) return;
+  try {
+    bridge.emit(event);
+  } catch {
+    // Audit listener errors must never break the replay pipeline.
+  }
+}
+
+function skipBySensitivity(record: SpanRecord, floor: Sensitivity): boolean {
+  if (record.sensitivityByAttribute === undefined) return false;
+  for (const value of Object.values(record.sensitivityByAttribute)) {
+    if (typeof value === 'string') {
+      const tier = value as Sensitivity;
+      if (tier === 'public' || tier === 'internal' || tier === 'secret') {
+        if (compareSensitivityTiers(tier, floor) > 0) return true;
+      }
+    }
+  }
+  return false;
+}
+
+function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T> {
+  return value !== null && typeof value === 'object' && Symbol.asyncIterator in (value as object);
+}
+
+function asAsync<T>(it: Iterator<T>): AsyncIterator<T> {
+  return {
+    next(): Promise<IteratorResult<T>> {
+      return Promise.resolve(it.next());
+    },
+  };
+}

package/src/replay/types.ts

@@ -0,0 +1,112 @@
+/**
+ * Public types for the replay surface.
+ *
+ * @packageDocumentation
+ */
+
+import type { Sensitivity } from '@graphorin/core';
+
+import type { SpanRecord } from '../exporters/types.js';
+import type { RedactionValidatorInstance } from '../redaction/types.js';
+
+/**
+ * Replay scope hint. Server mode requires `'raw'` to be backed by a
+ * token carrying the `traces:read:raw` scope. The library mode uses
+ * the same flag but without scope enforcement (the server is the only
+ * boundary that can grant `'raw'`).
+ *
+ * @stable
+ */
+export type ReplayMode = 'sanitized' | 'raw';
+
+/**
+ * Audit-bridge contract used by the replay layer. Every replay
+ * invocation emits one entry through the bridge - sanitized + raw
+ * alike. The actual audit storage lives in `@graphorin/security`; the
+ * replay layer keeps the bridge generic so the package stays free of
+ * a hard dependency on the security package.
+ *
+ * @stable
+ */
+export interface ReplayAuditBridge {
+  emit(event: ReplayAuditEvent): void;
+}
+
+/**
+ * Sanitized event passed to the audit bridge.
+ *
+ * @stable
+ */
+export interface ReplayAuditEvent {
+  readonly action: 'trace.replay.accessed';
+  readonly actor: { readonly kind: 'token' | 'cli' | 'agent' | 'system'; readonly id: string };
+  readonly target: string;
+  readonly decision: 'success' | 'denied';
+  readonly metadata: {
+    readonly mode: ReplayMode;
+    readonly minSensitivity: Sensitivity;
+    readonly fromSpanId?: string;
+    readonly eventCount: number;
+    readonly durationMs: number;
+  };
+}
+
+/**
+ * Single record yielded by the replay iterator.
+ *
+ * @stable
+ */
+export type ReplayEvent =
+  | {
+      readonly type: 'replay.start';
+      readonly target: string;
+      readonly mode: ReplayMode;
+      readonly eventCount?: number;
+    }
+  | { readonly type: 'replay.event'; readonly span: SpanRecord; readonly sanitized: boolean }
+  | {
+      readonly type: 'replay.skipped';
+      readonly reason: 'sensitivity' | 'redaction-violation' | 'access-denied';
+      readonly spanId: string;
+    }
+  | {
+      readonly type: 'replay.end';
+      readonly durationMs: number;
+      readonly eventsEmitted: number;
+      readonly eventsSkipped: number;
+    };
+
+/**
+ * Configuration shape for {@link createReplay}.
+ *
+ * @stable
+ */
+export interface ReplayOptions {
+  /** Validator used to sanitize records when `mode === 'sanitized'`. */
+  readonly validator?: RedactionValidatorInstance;
+  /** Optional audit bridge - called once per replay invocation. */
+  readonly audit?: ReplayAuditBridge;
+  /** Default actor reported via `audit.actor` when none is supplied. */
+  readonly defaultActor?: ReplayAuditEvent['actor'];
+  /**
+   * Scope check invoked when the caller asks for `mode: 'raw'`. Returns
+   * `true` to allow, `false` to deny. The server (Phase 14) wires this
+   * to the `traces:read:raw` token scope; in library mode it defaults
+   * to `() => true` (operators trust their own process).
+   */
+  readonly canReadRaw?: (context: { readonly target: string }) => boolean;
+}
+
+/**
+ * Per-call options consumed by `Replay.run(...)`.
+ *
+ * @stable
+ */
+export interface ReplayRunInput {
+  readonly source: AsyncIterable<SpanRecord> | Iterable<SpanRecord>;
+  readonly target: string;
+  readonly mode?: ReplayMode;
+  readonly minSensitivity?: Sensitivity;
+  readonly fromSpanId?: string;
+  readonly actor?: ReplayAuditEvent['actor'];
+}

package/src/telemetry/index.ts

@@ -0,0 +1,94 @@
+/**
+ * Zero-default telemetry stub.
+ *
+ * The framework promises to make zero outbound network calls without
+ * an explicit user action. This module exists so consumers can:
+ *
+ * - inspect the telemetry posture from CLI / health endpoints,
+ * - register the reserved `GRAPHORIN_TELEMETRY` / `GRAPHORIN_NO_PHONE_HOME`
+ *   environment variables for forward compatibility,
+ * - assert in tests that no implicit telemetry surface exists.
+ *
+ * Attempting to enable telemetry pre-v0.2 returns a sentinel result; it
+ * never opens a socket.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Result returned by {@link getTelemetryStatus}.
+ *
+ * @stable
+ */
+export interface TelemetryStatus {
+  /** Always `false` in v0.1. Reserved field. */
+  readonly enabled: false;
+  /** Plain-English explanation of the current state. */
+  readonly reason: string;
+  /** Resolved value of `GRAPHORIN_TELEMETRY` (if any). */
+  readonly env?: string;
+  /** Resolved value of `GRAPHORIN_NO_PHONE_HOME` (if any). */
+  readonly noPhoneHome?: string;
+}
+
+/**
+ * Snapshot of the telemetry posture. Reads from `process.env` once
+ * unless `env` is provided.
+ *
+ * @stable
+ */
+export function getTelemetryStatus(env: NodeJS.ProcessEnv = process.env): TelemetryStatus {
+  const telemetry = env.GRAPHORIN_TELEMETRY;
+  const noPhoneHome = env.GRAPHORIN_NO_PHONE_HOME;
+  return {
+    enabled: false,
+    reason: 'telemetry not yet implemented (v0.1 ships zero default telemetry)',
+    ...(telemetry === undefined ? {} : { env: telemetry }),
+    ...(noPhoneHome === undefined ? {} : { noPhoneHome }),
+  };
+}
+
+/**
+ * Best-effort enable hook. Always returns the sentinel
+ * `{ status: 'disabled', reason: ... }` payload. Reserved for v0.2+.
+ *
+ * @stable
+ */
+export function enableTelemetry(): {
+  readonly status: 'disabled';
+  readonly reason: string;
+} {
+  return {
+    status: 'disabled',
+    reason: 'telemetry not yet implemented (v0.1 ships zero default telemetry)',
+  };
+}
+
+/**
+ * Detect the reserved env vars and emit one informational line per
+ * process. Returns the lines as an array so callers can route them to
+ * any sink they like (defaults to `console.info`).
+ *
+ * @stable
+ */
+export function announceTelemetryPosture(
+  opts: { readonly env?: NodeJS.ProcessEnv; readonly sink?: (line: string) => void } = {},
+): ReadonlyArray<string> {
+  const env = opts.env ?? process.env;
+  const sink = opts.sink ?? ((line: string) => console.info(line));
+  const lines: string[] = [];
+  if (env.GRAPHORIN_TELEMETRY !== undefined) {
+    lines.push(
+      `[graphorin/observability] info: GRAPHORIN_TELEMETRY=${env.GRAPHORIN_TELEMETRY} ` +
+        ' - acknowledged. Telemetry is hardcoded `disabled` in v0.1.',
+    );
+  }
+  if (env.GRAPHORIN_NO_PHONE_HOME !== undefined) {
+    lines.push(
+      `[graphorin/observability] info: GRAPHORIN_NO_PHONE_HOME=${env.GRAPHORIN_NO_PHONE_HOME} ` +
+        ' - acknowledged. Graphorin already makes zero outbound calls without explicit user action.',
+    );
+  }
+  for (const line of lines) sink(line);
+  return lines;
+}

package/src/tracer/ids.ts

@@ -0,0 +1,27 @@
+/**
+ * Trace and span ID generators. The tracer prefers `crypto.randomUUID()`
+ * over a custom RNG for parity with the OpenTelemetry SDK behaviour and
+ * to avoid pulling another runtime dependency.
+ *
+ * @packageDocumentation
+ */
+
+import { randomBytes } from 'node:crypto';
+
+/**
+ * Generate a 32-hex-character (16-byte) trace id.
+ *
+ * @stable
+ */
+export function newTraceId(): string {
+  return randomBytes(16).toString('hex');
+}
+
+/**
+ * Generate a 16-hex-character (8-byte) span id.
+ *
+ * @stable
+ */
+export function newSpanId(): string {
+  return randomBytes(8).toString('hex');
+}

package/src/tracer/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Tracer surface for `@graphorin/observability`.
+ *
+ * @packageDocumentation
+ */
+
+export { newSpanId, newTraceId } from './ids.js';
+export {
+  createSampler,
+  type Sampler,
+  type SamplingDecisionMaker,
+  type SamplingOptions,
+  type SamplingRule,
+} from './sampling.js';
+export type { GraphorinSpan, SetAttributeOptions } from './span.js';
+export { spanNameFor } from './span-names.js';
+export {
+  asGraphorinSpan,
+  createTracer,
+  type GraphorinTracer,
+  type TracerOptions,
+} from './tracer.js';

package/src/tracer/sampling.ts

@@ -0,0 +1,170 @@
+/**
+ * Head + tail sampling helpers. The tracer pairs the configured
+ * sampler with a per-type override registry so chatty span types
+ * (`memory.embed`, `tool.execute.partial`, …) can be downsampled
+ * without affecting the rest of the trace stream. Under the default
+ * `'parent-based'` decision maker the per-type rules apply to CHILDREN
+ * of a sampled trace too (W-090) - a rule can only downsample inside a
+ * sampled trace, never resurrect children of an unsampled parent.
+ *
+ * @packageDocumentation
+ */
+
+import type { SpanType } from '@graphorin/core';
+
+/** @stable */
+export type SamplingDecisionMaker = 'parent-based' | 'always-on' | 'rate-limit';
+
+/**
+ * Per-span-type rate override. Applies on the probabilistic root path
+ * AND (W-090) to children of a sampled parent under `'parent-based'` -
+ * `{ type: 'tool.execute', rate: 0.01 }` thins the per-call spans
+ * inside every sampled `agent.run` trace. A child dropped by its rule
+ * breaks the tree below it: its own descendants inherit
+ * `parentSampled=false`.
+ *
+ * @stable
+ */
+export interface SamplingRule {
+  readonly type: SpanType | string;
+  readonly rate: number;
+}
+
+/**
+ * Configuration shape consumed by {@link createSampler}.
+ *
+ * @stable
+ */
+export interface SamplingOptions {
+  /** Default head-sampling rate. Must be in `[0, 1]`. Defaults to `1.0`. */
+  readonly rate?: number;
+  /** Per-type overrides. Last write wins on duplicate `type`. */
+  readonly rules?: ReadonlyArray<SamplingRule>;
+  /** Decision maker. Defaults to `'parent-based'`. */
+  readonly decisionMaker?: SamplingDecisionMaker;
+  /**
+   * Cap for the `'rate-limit'` decision maker: at most this many root spans
+   * are sampled per rolling 1-second window (RP-19). `undefined` ⇒ no cap
+   * (samples everything); `0` ⇒ sample nothing. Ignored by the other
+   * decision makers.
+   */
+  readonly maxPerSecond?: number;
+  /**
+   * Clock for the `'rate-limit'` window. Defaults to `Date.now`.
+   *
+   * @internal
+   */
+  readonly now?: () => number;
+  /**
+   * Optional override for streaming-event sampling.
+   * @see RB-52 - streaming event family `tool.execute.{progress,partial}`.
+   */
+  readonly streaming?: {
+    readonly eventSamplingRate?: number;
+    readonly includeChunkContent?: 'none' | 'text-only' | 'all';
+  };
+  /**
+   * Override for the random source. Useful for deterministic tests.
+   *
+   * @internal
+   */
+  readonly random?: () => number;
+}
+
+/**
+ * @stable
+ */
+export interface Sampler {
+  /** Decide whether a span of the given type should be recorded. */
+  shouldSample(type: SpanType | string, parentSampled?: boolean): boolean;
+  /** Decide whether a span event of the given name should be recorded. */
+  shouldRecordEvent(name: string): boolean;
+  /** Returns whether chunk *content* should travel through the exporter. */
+  shouldIncludeChunkContent(): boolean;
+}
+
+/**
+ * Build a {@link Sampler} from the supplied options. The sampler is
+ * intentionally inexpensive - every decision boils down to a single
+ * `random < threshold` comparison.
+ *
+ * @stable
+ */
+export function createSampler(opts: SamplingOptions = {}): Sampler {
+  const baseRate = clampRate(opts.rate ?? 1.0);
+  const decisionMaker: SamplingDecisionMaker = opts.decisionMaker ?? 'parent-based';
+  const ruleByType = new Map<string, number>();
+  for (const rule of opts.rules ?? []) {
+    ruleByType.set(rule.type, clampRate(rule.rate));
+  }
+  const streamingRate = clampRate(opts.streaming?.eventSamplingRate ?? 1.0);
+  const includeChunks = opts.streaming?.includeChunkContent ?? 'none';
+  const random = opts.random ?? Math.random;
+  const maxPerSecond = opts.maxPerSecond;
+  const now = opts.now ?? Date.now;
+  let windowStart: number | undefined;
+  let windowCount = 0;
+
+  return {
+    shouldSample(type, parentSampled): boolean {
+      if (decisionMaker === 'always-on') return true;
+      if (decisionMaker === 'parent-based') {
+        // RP-19: true parent-based - follow the parent's real sampling
+        // decision. A child of an unsampled parent is NOT recorded (it would
+        // otherwise be an orphan); a root span (no parent) falls through to
+        // the rate.
+        //
+        // W-090: a per-type rule ACTS on children of a sampled parent -
+        // that is where the volume lives (`tool.execute` inside a sampled
+        // `agent.run` trace), and the docstring always promised it. A rule
+        // never resurrects children of an UNSAMPLED parent (orphans); a
+        // child dropped by its rule makes its own descendants inherit
+        // parentSampled=false.
+        if (parentSampled === true) {
+          const rule = ruleByType.get(type);
+          if (rule === undefined) return true;
+          if (rule >= 1) return true;
+          if (rule <= 0) return false;
+          return random() < rule;
+        }
+        if (parentSampled === false) return false;
+      }
+      if (decisionMaker === 'rate-limit') {
+        // RP-19: a real token-window limiter, distinct from the probabilistic
+        // path. Caps sampled spans to `maxPerSecond` per rolling second.
+        if (maxPerSecond === undefined) return true;
+        if (maxPerSecond <= 0) return false;
+        const t = now();
+        if (windowStart === undefined || t - windowStart >= 1000) {
+          windowStart = t;
+          windowCount = 0;
+        }
+        if (windowCount < maxPerSecond) {
+          windowCount += 1;
+          return true;
+        }
+        return false;
+      }
+      const rate = ruleByType.get(type) ?? baseRate;
+      if (rate >= 1) return true;
+      if (rate <= 0) return false;
+      return random() < rate;
+    },
+    shouldRecordEvent(name): boolean {
+      const rate = ruleByType.get(name) ?? streamingRate;
+      if (rate >= 1) return true;
+      if (rate <= 0) return false;
+      return random() < rate;
+    },
+    shouldIncludeChunkContent(): boolean {
+      return includeChunks !== 'none';
+    },
+  };
+}
+
+function clampRate(rate: number): number {
+  if (Number.isNaN(rate)) return 1;
+  if (rate < 0) return 0;
+  if (rate > 1) return 1;
+  return rate;
+}

package/src/tracer/span-names.ts

@@ -0,0 +1,52 @@
+/**
+ * Default human-readable span name per {@link SpanType}. Operators
+ * can override the name by passing `name` through a custom
+ * `setAttributes(...)` call after `startSpan(...)` returns.
+ *
+ * E8 (audit 2026-07-04): the OTel GenAI semantic conventions name spans
+ * `"{operation} {target}"` (`chat gpt-4.1`, `execute_tool get_weather`,
+ * `invoke_agent planner`) so trace UIs group like operations while
+ * keeping the target visible. When the span's initial attributes carry
+ * the target we emit that shape; otherwise the raw span type remains
+ * the stable fallback.
+ *
+ * @packageDocumentation
+ */
+
+import type { SpanType } from '@graphorin/core';
+
+function attrString(
+  attrs: Readonly<Record<string, unknown>> | undefined,
+  keys: readonly string[],
+): string | undefined {
+  if (attrs === undefined) return undefined;
+  for (const key of keys) {
+    const value = attrs[key];
+    if (typeof value === 'string' && value.length > 0) return value;
+  }
+  return undefined;
+}
+
+/**
+ * @stable
+ */
+export function spanNameFor(type: SpanType, attrs?: Readonly<Record<string, unknown>>): string {
+  switch (type) {
+    case 'provider.generate':
+    case 'provider.stream': {
+      const model = attrString(attrs, ['gen_ai.request.model', 'graphorin.provider.model']);
+      return model === undefined ? type : `chat ${model}`;
+    }
+    case 'tool.execute': {
+      const tool = attrString(attrs, ['gen_ai.tool.name', 'graphorin.tool.name']);
+      return tool === undefined ? type : `execute_tool ${tool}`;
+    }
+    case 'agent.run':
+    case 'agent.step': {
+      const agent = attrString(attrs, ['gen_ai.agent.name', 'gen_ai.agent.id']);
+      return agent === undefined ? type : `invoke_agent ${agent}`;
+    }
+    default:
+      return type;
+  }
+}