@ontrails/observability 1.0.0-beta.42

package/src/dev/internal/dev-state.ts

@@ -0,0 +1,179 @@
+import type { Database } from 'bun:sqlite';
+
+import { ensureSubsystemSchema, openWriteTrailsDb } from '@ontrails/core';
+
+import type { DevStoreOptions } from '../store.js';
+
+export const DEFAULT_MAX_RECORDS = 10_000;
+export const DEFAULT_MAX_AGE = 7 * 24 * 60 * 60 * 1000;
+export const TRACK_SUBSYSTEM = 'track';
+export const TRACK_TABLE = 'track_records';
+
+const CREATE_TABLE_SQL = `CREATE TABLE IF NOT EXISTS ${TRACK_TABLE} (
+  id TEXT PRIMARY KEY,
+  trace_id TEXT NOT NULL,
+  root_id TEXT NOT NULL,
+  parent_id TEXT,
+  kind TEXT NOT NULL,
+  name TEXT NOT NULL,
+  trail_id TEXT,
+  surface TEXT,
+  intent TEXT,
+  started_at INTEGER NOT NULL,
+  ended_at INTEGER,
+  status TEXT NOT NULL,
+  error_category TEXT,
+  permit_id TEXT,
+  permit_tenant_id TEXT,
+  attrs TEXT
+)`;
+
+const CREATE_INDEXES_SQL = [
+  `CREATE INDEX IF NOT EXISTS idx_${TRACK_TABLE}_trail_id ON ${TRACK_TABLE}(trail_id)`,
+  `CREATE INDEX IF NOT EXISTS idx_${TRACK_TABLE}_trace_id ON ${TRACK_TABLE}(trace_id)`,
+  `CREATE INDEX IF NOT EXISTS idx_${TRACK_TABLE}_status ON ${TRACK_TABLE}(status)`,
+  `CREATE INDEX IF NOT EXISTS idx_${TRACK_TABLE}_started_at ON ${TRACK_TABLE}(started_at)`,
+];
+
+export interface TraceCleanupReport {
+  readonly removedByAge: number;
+  readonly removedByCount: number;
+  readonly removedTotal: number;
+  readonly remaining: number;
+}
+
+const traceTableExists = (db: Database): boolean => {
+  const row = db
+    .query<{ name: string }, [string]>(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?"
+    )
+    .get(TRACK_TABLE);
+  return row?.name === TRACK_TABLE;
+};
+
+export const ensureTraceSchema = (db: Database): void => {
+  ensureSubsystemSchema(db, {
+    migrate: (currentVersion) => {
+      if (currentVersion > 0) {
+        db.run(`DROP TABLE IF EXISTS ${TRACK_TABLE}`);
+      }
+      db.run(CREATE_TABLE_SQL);
+      for (const sql of CREATE_INDEXES_SQL) {
+        db.run(sql);
+      }
+    },
+    subsystem: TRACK_SUBSYSTEM,
+    version: 2,
+  });
+};
+
+export const countTraceRecords = (db: Database): number => {
+  if (!traceTableExists(db)) {
+    return 0;
+  }
+  const result = db
+    .query<{ count: number }, []>(
+      `SELECT COUNT(*) as count FROM ${TRACK_TABLE}`
+    )
+    .get();
+  return result?.count ?? 0;
+};
+
+const countOldTracks = (db: Database, maxAge: number): number => {
+  if (!traceTableExists(db)) {
+    return 0;
+  }
+  const threshold = Date.now() - maxAge;
+  const row = db
+    .query<{ count: number }, [number]>(
+      `SELECT COUNT(*) as count FROM ${TRACK_TABLE} WHERE started_at < ?`
+    )
+    .get(threshold);
+  return row?.count ?? 0;
+};
+
+const countOverflowTracks = (
+  db: Database,
+  maxRecords: number,
+  maxAge: number
+): number => {
+  const total = countTraceRecords(db);
+  const remainingAfterAge = total - countOldTracks(db, maxAge);
+  return Math.max(remainingAfterAge - maxRecords, 0);
+};
+
+const deleteOldTracks = (db: Database, maxAge: number): number => {
+  const threshold = Date.now() - maxAge;
+  const result = db.run(`DELETE FROM ${TRACK_TABLE} WHERE started_at < ?`, [
+    threshold,
+  ]);
+  return result.changes;
+};
+
+const deleteOverflowTracks = (db: Database, maxRecords: number): number => {
+  const excess = Math.max(countTraceRecords(db) - maxRecords, 0);
+  if (excess === 0) {
+    return 0;
+  }
+
+  const result = db.run(
+    `DELETE FROM ${TRACK_TABLE} WHERE id IN (
+      SELECT id FROM ${TRACK_TABLE} ORDER BY started_at ASC LIMIT ?
+    )`,
+    [excess]
+  );
+  return result.changes;
+};
+
+const toCleanupReport = (
+  db: Database,
+  removedByAge: number,
+  removedByCount: number
+): TraceCleanupReport => ({
+  remaining: countTraceRecords(db),
+  removedByAge,
+  removedByCount,
+  removedTotal: removedByAge + removedByCount,
+});
+
+export const previewTraceCleanup = (
+  db: Database,
+  options?: Pick<DevStoreOptions, 'maxAge' | 'maxRecords'>
+): TraceCleanupReport => {
+  const maxRecords = options?.maxRecords ?? DEFAULT_MAX_RECORDS;
+  const maxAge = options?.maxAge ?? DEFAULT_MAX_AGE;
+  const removedByAge = countOldTracks(db, maxAge);
+  const removedByCount = countOverflowTracks(db, maxRecords, maxAge);
+  return toCleanupReport(db, removedByAge, removedByCount);
+};
+
+export const applyTraceCleanup = (
+  db: Database,
+  options?: Pick<DevStoreOptions, 'maxAge' | 'maxRecords'>
+): TraceCleanupReport => {
+  if (!traceTableExists(db)) {
+    return toCleanupReport(db, 0, 0);
+  }
+  const maxRecords = options?.maxRecords ?? DEFAULT_MAX_RECORDS;
+  const maxAge = options?.maxAge ?? DEFAULT_MAX_AGE;
+  const removedByAge = deleteOldTracks(db, maxAge);
+  const removedByCount = deleteOverflowTracks(db, maxRecords);
+  return toCleanupReport(db, removedByAge, removedByCount);
+};
+
+export const withTraceStoreDb = <T>(
+  options: Pick<DevStoreOptions, 'path' | 'rootDir'> | undefined,
+  run: (db: Database) => T
+): T => {
+  const db = openWriteTrailsDb({
+    ...(options?.path === undefined ? {} : { path: options.path }),
+    ...(options?.rootDir === undefined ? {} : { rootDir: options.rootDir }),
+  });
+
+  try {
+    ensureTraceSchema(db);
+    return run(db);
+  } finally {
+    db.close();
+  }
+};

package/src/dev/sampling.ts

@@ -0,0 +1,30 @@
+/** Intent-based sampling rate configuration. */
+export interface SamplingConfig {
+  /** Sample rate for read operations (0.0 to 1.0). Default 0.05 (5%). */
+  readonly read: number;
+  /** Sample rate for write operations (0.0 to 1.0). Default 1.0 (100%). */
+  readonly write: number;
+  /** Sample rate for destroy operations (0.0 to 1.0). Default 1.0 (100%). */
+  readonly destroy: number;
+}
+
+/** Default sampling rates: 5% reads, 100% writes and destroys. */
+export const DEFAULT_SAMPLING: SamplingConfig = {
+  destroy: 1,
+  read: 0.05,
+  write: 1,
+};
+
+/**
+ * Decide whether to sample a trace based on intent.
+ *
+ * Undefined intent falls back to the write rate.
+ */
+export const shouldSample = (
+  intent: 'read' | 'write' | 'destroy' | undefined,
+  config?: Partial<SamplingConfig>
+): boolean => {
+  const merged = { ...DEFAULT_SAMPLING, ...config };
+  const rate = merged[intent ?? 'write'];
+  return Math.random() < rate;
+};

package/src/dev/store.ts

@@ -0,0 +1,260 @@
+import type { Database, SQLQueryBindings } from 'bun:sqlite';
+
+import { openWriteTrailsDb } from '@ontrails/core';
+
+import {
+  DEFAULT_MAX_AGE,
+  DEFAULT_MAX_RECORDS,
+  TRACK_TABLE,
+  applyTraceCleanup,
+  countTraceRecords,
+  ensureTraceSchema,
+} from './internal/dev-state.js';
+
+import type { TraceRecord, TraceSink } from '@ontrails/core';
+
+/** Configuration for the SQLite dev store. */
+export interface DevStoreOptions {
+  /** Environment used for state-store discovery. Defaults to `process.env`. */
+  readonly env?: Record<string, string | undefined>;
+  /** Path to the SQLite database file. Overrides state-store discovery. */
+  readonly path?: string;
+  /** Root directory used when deriving the default per-project state path. */
+  readonly rootDir?: string;
+  /** Maximum number of records to retain. Defaults to 10000. */
+  readonly maxRecords?: number;
+  /** Maximum age of records in milliseconds. Defaults to 7 days. */
+  readonly maxAge?: number;
+}
+
+/** Query options for filtering stored track records. */
+export interface DevStoreQueryOptions {
+  readonly trailId?: string;
+  readonly traceId?: string;
+  readonly errorsOnly?: boolean;
+  readonly limit?: number;
+}
+
+/** Read-only query surface over persisted track records. */
+export interface TraceStore {
+  /** Query recent traces with optional filters. */
+  readonly query: (options?: DevStoreQueryOptions) => readonly TraceRecord[];
+  /** Return the total number of stored records. */
+  readonly count: () => number;
+  /** Close the database connection. */
+  readonly close: () => void;
+}
+
+/** SQLite-backed dev store for persisting and querying track records. */
+export interface DevStore extends TraceStore, TraceSink {}
+
+/** Shape of a row returned from the tracing table. */
+interface TraceRow {
+  readonly id: string;
+  readonly trace_id: string;
+  readonly root_id: string;
+  readonly parent_id: string | null;
+  readonly kind: string;
+  readonly name: string;
+  readonly trail_id: string | null;
+  readonly surface: string | null;
+  readonly intent: string | null;
+  readonly started_at: number;
+  readonly ended_at: number | null;
+  readonly status: string;
+  readonly error_category: string | null;
+  readonly permit_id: string | null;
+  readonly permit_tenant_id: string | null;
+  readonly attrs: string | null;
+}
+
+/** Reconstruct the permit object from decomposed columns. */
+const buildPermit = (
+  permitId: string | null,
+  tenantId: string | null
+): TraceRecord['permit'] => {
+  if (permitId === null) {
+    return undefined;
+  }
+  return tenantId === null ? { id: permitId } : { id: permitId, tenantId };
+};
+
+/** Parse attrs JSON back into a record. */
+const parseAttrs = (raw: string | null): Readonly<Record<string, unknown>> =>
+  raw ? (JSON.parse(raw) as Record<string, unknown>) : {};
+
+/** Reconstruct a TraceRecord from a database row. */
+const rowToRecord = (row: TraceRow): TraceRecord => ({
+  attrs: parseAttrs(row.attrs),
+  endedAt: row.ended_at ?? undefined,
+  errorCategory: row.error_category ?? undefined,
+  id: row.id,
+  intent: (row.intent ?? undefined) as TraceRecord['intent'],
+  kind: row.kind as TraceRecord['kind'],
+  name: row.name,
+  parentId: row.parent_id ?? undefined,
+  permit: buildPermit(row.permit_id, row.permit_tenant_id),
+  rootId: row.root_id,
+  startedAt: row.started_at,
+  status: row.status as TraceRecord['status'],
+  surface: (row.surface ?? undefined) as TraceRecord['surface'],
+  traceId: row.trace_id,
+  trailId: row.trail_id ?? undefined,
+});
+
+/** Filter definition: column condition and optional bound value. */
+interface QueryFilter {
+  readonly condition: string;
+  readonly value?: SQLQueryBindings;
+}
+
+/** Derive active filters from query options. */
+const deriveFilters = (
+  options?: DevStoreQueryOptions
+): readonly QueryFilter[] => {
+  const filters: QueryFilter[] = [];
+
+  if (options?.trailId !== undefined) {
+    filters.push({ condition: 'trail_id = ?', value: options.trailId });
+  }
+  if (options?.traceId !== undefined) {
+    filters.push({ condition: 'trace_id = ?', value: options.traceId });
+  }
+  if (options?.errorsOnly === true) {
+    filters.push({ condition: "status = 'err'" });
+  }
+
+  return filters;
+};
+
+/** Build a parameterized SELECT query from query options. */
+const buildQuery = (
+  defaultLimit: number,
+  options?: DevStoreQueryOptions
+): { readonly sql: string; readonly params: SQLQueryBindings[] } => {
+  const filters = deriveFilters(options);
+  const where =
+    filters.length > 0
+      ? `WHERE ${filters.map((f) => f.condition).join(' AND ')}`
+      : '';
+  const params: SQLQueryBindings[] = [
+    ...filters.flatMap((f) => (f.value === undefined ? [] : [f.value])),
+    options?.limit ?? defaultLimit,
+  ];
+
+  return {
+    params,
+    sql: `SELECT * FROM ${TRACK_TABLE} ${where} ORDER BY started_at DESC LIMIT ?`,
+  };
+};
+
+/** Serialize attrs to JSON, returning null for empty objects. */
+const serializeAttrs = (
+  attrs: Readonly<Record<string, unknown>>
+): string | null =>
+  Object.keys(attrs).length > 0 ? JSON.stringify(attrs) : null;
+
+/** Serialize a TraceRecord into positional INSERT parameters. */
+const recordToParams = (record: TraceRecord): SQLQueryBindings[] => [
+  record.id,
+  record.traceId,
+  record.rootId,
+  record.parentId ?? null,
+  record.kind,
+  record.name,
+  record.trailId ?? null,
+  record.surface ?? null,
+  record.intent ?? null,
+  record.startedAt,
+  record.endedAt ?? null,
+  record.status,
+  record.errorCategory ?? null,
+  record.permit?.id ?? null,
+  record.permit?.tenantId ?? null,
+  serializeAttrs(record.attrs),
+];
+
+/** SQL for inserting a track record. */
+const UPSERT_SQL = `INSERT INTO ${TRACK_TABLE} (
+  id, trace_id, root_id, parent_id,
+  kind, name, trail_id, surface,
+  intent, started_at, ended_at, status,
+  error_category, permit_id, permit_tenant_id, attrs
+) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(id) DO UPDATE SET
+  trace_id = excluded.trace_id,
+  root_id = excluded.root_id,
+  parent_id = excluded.parent_id,
+  kind = excluded.kind,
+  name = excluded.name,
+  trail_id = excluded.trail_id,
+  surface = excluded.surface,
+  intent = excluded.intent,
+  started_at = excluded.started_at,
+  ended_at = excluded.ended_at,
+  status = excluded.status,
+  error_category = excluded.error_category,
+  permit_id = excluded.permit_id,
+  permit_tenant_id = excluded.permit_tenant_id,
+  attrs = excluded.attrs`;
+
+/** Create a transactional writer that keeps retention pruning atomic. */
+const createWriter = (
+  db: Database,
+  insertStmt: ReturnType<Database['prepare']>,
+  maxRecords: number,
+  maxAge: number | undefined
+): ((record: TraceRecord) => void) =>
+  db.transaction((record: TraceRecord) => {
+    insertStmt.run(...recordToParams(record));
+    applyTraceCleanup(db, {
+      maxRecords,
+      ...(maxAge === undefined ? {} : { maxAge }),
+    });
+  });
+
+const createReadApi = (db: Database, defaultLimit: number): TraceStore => ({
+  close: () => {
+    db.close();
+  },
+  count: () => countTraceRecords(db),
+  query: (queryOptions?: DevStoreQueryOptions): readonly TraceRecord[] => {
+    const { sql, params } = buildQuery(defaultLimit, queryOptions);
+    const rows = db.query<TraceRow, SQLQueryBindings[]>(sql).all(...params);
+    return rows.map(rowToRecord);
+  },
+});
+
+/**
+ * Create a SQLite-backed dev store for persisting track records.
+ *
+ * Uses WAL mode and normal synchronous for good write performance.
+ * Automatically prunes records exceeding `maxRecords` on each write.
+ */
+export const createDevStore = (options?: DevStoreOptions): DevStore => {
+  const maxRecords = options?.maxRecords ?? DEFAULT_MAX_RECORDS;
+  const maxAge = options?.maxAge ?? DEFAULT_MAX_AGE;
+  const db = openWriteTrailsDb({
+    ...(options?.env === undefined ? {} : { env: options.env }),
+    ...(options?.path === undefined ? {} : { path: options.path }),
+    ...(options?.rootDir === undefined ? {} : { rootDir: options.rootDir }),
+  });
+  ensureTraceSchema(db);
+  const insertStmt = db.prepare(UPSERT_SQL);
+  const write = createWriter(db, insertStmt, maxRecords, maxAge);
+  return { ...createReadApi(db, maxRecords), write };
+};
+
+/**
+ * Read-only view of a TraceStore.
+ *
+ * `close()` is a no-op — consumers of this view (e.g. the tracing resource)
+ * must not close the underlying connection they don't own.
+ */
+export const toTraceStore = (store: TraceStore): TraceStore => ({
+  close: () => {
+    // Intentional no-op: read-only view must not close the underlying DB.
+  },
+  count: () => store.count(),
+  query: (options?: DevStoreQueryOptions) => store.query(options),
+});

package/src/dev/tracing-resource.ts

@@ -0,0 +1,35 @@
+import { Result, resource } from '@ontrails/core';
+
+import type { TracingState } from './tracing-state.js';
+import { getTracingState } from './tracing-state.js';
+import { DEFAULT_SAMPLING } from './sampling.js';
+import { toTraceStore } from './store.js';
+
+/** Default state when no explicit state has been registered. */
+const defaultState: TracingState = {
+  active: true,
+  sampling: DEFAULT_SAMPLING,
+  store: undefined,
+};
+
+/**
+ * Telemetry query resource.
+ *
+ * Exposes the current tracing store, sampling config, and active flag as a
+ * single `TracingState` accessible to trails via `tracingResource.from(ctx)`.
+ *
+ * Unlike config, tracing gracefully defaults when no state is registered —
+ * telemetry should never fail to start.
+ */
+export const tracingResource = resource<TracingState>('tracing', {
+  create: () => {
+    const state = getTracingState() ?? defaultState;
+    return Result.ok({
+      ...state,
+      store: state.store ? toTraceStore(state.store) : undefined,
+    });
+  },
+  description: 'Telemetry query resource',
+  meta: { category: 'infrastructure' },
+  mock: (): TracingState => ({ ...defaultState }),
+});

package/src/dev/tracing-state.ts

@@ -0,0 +1,47 @@
+import { DEFAULT_SAMPLING } from './sampling.js';
+import type { SamplingConfig } from './sampling.js';
+import type { TraceStore } from './store.js';
+
+/** Full telemetry subsystem state carried by tracingResource. */
+export interface TracingState {
+  readonly active: boolean;
+  readonly sampling: SamplingConfig;
+  readonly store: TraceStore | undefined;
+}
+
+// oxlint-disable-next-line eslint-plugin-jest/require-hook -- module-level state registry, not test setup
+let state: TracingState | undefined;
+
+/** Register telemetry state at bootstrap. */
+export const registerTracingState = (s: TracingState): void => {
+  state = s;
+};
+
+/** Read the registered telemetry state. Returns `undefined` before registration. */
+export const getTracingState = (): TracingState | undefined => state;
+
+/** Clear registered state. Primarily useful in tests. */
+export const clearTracingState = (): void => {
+  state = undefined;
+};
+
+// --- Convenience wrappers for store-only registration ---
+
+/** Register a trace store instance for use by the tracing.query trail. */
+export const registerTraceStore = (s: TraceStore): void => {
+  state = {
+    active: state?.active ?? true,
+    sampling: state?.sampling ?? DEFAULT_SAMPLING,
+    store: s,
+  };
+};
+
+/** Retrieve the currently registered trace store, if any. */
+export const getTraceStore = (): TraceStore | undefined => state?.store;
+
+/** Clear the registered store. Useful for testing teardown. */
+export const clearTraceStore = (): void => {
+  if (state) {
+    state = { ...state, store: undefined };
+  }
+};

package/src/dev/trails/tracing-query.ts

@@ -0,0 +1,108 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import type { DevStoreQueryOptions } from '../store.js';
+import { tracingResource } from '../tracing-resource.js';
+
+/** Output schema for individual trace records. */
+const traceRecordOutput = z.object({
+  attrs: z.record(z.string(), z.unknown()),
+  endedAt: z.number().optional(),
+  errorCategory: z.string().optional(),
+  id: z.string(),
+  intent: z.string().optional(),
+  kind: z.enum(['activation', 'signal', 'span', 'trail']),
+  name: z.string(),
+  parentId: z.string().optional(),
+  rootId: z.string(),
+  startedAt: z.number(),
+  status: z.enum(['ok', 'err', 'cancelled']),
+  surface: z.string().optional(),
+  traceId: z.string(),
+  trailId: z.string().optional(),
+});
+
+/** Output schema for the tracing.query trail. */
+const tracingQueryOutput = z.object({
+  count: z.number(),
+  records: z.array(traceRecordOutput),
+});
+
+/** Map a TraceRecord to the output shape, dropping internal fields. */
+const mapRecord = (r: {
+  readonly attrs: Readonly<Record<string, unknown>>;
+  readonly endedAt?: number | undefined;
+  readonly errorCategory?: string | undefined;
+  readonly id: string;
+  readonly intent?: string | undefined;
+  readonly kind: 'activation' | 'signal' | 'span' | 'trail';
+  readonly name: string;
+  readonly parentId?: string | undefined;
+  readonly rootId: string;
+  readonly startedAt: number;
+  readonly status: 'ok' | 'err' | 'cancelled';
+  readonly surface?: string | undefined;
+  readonly traceId: string;
+  readonly trailId?: string | undefined;
+}) => ({
+  attrs: r.attrs,
+  endedAt: r.endedAt,
+  errorCategory: r.errorCategory,
+  id: r.id,
+  intent: r.intent,
+  kind: r.kind,
+  name: r.name,
+  parentId: r.parentId,
+  rootId: r.rootId,
+  startedAt: r.startedAt,
+  status: r.status,
+  surface: r.surface,
+  traceId: r.traceId,
+  trailId: r.trailId,
+});
+
+/** Build DevStoreQueryOptions, omitting undefined fields for exactOptionalPropertyTypes. */
+const buildQueryOptions = (input: {
+  readonly errorsOnly: boolean;
+  readonly limit: number;
+  readonly traceId?: string | undefined;
+  readonly trailId?: string | undefined;
+}): DevStoreQueryOptions => ({
+  errorsOnly: input.errorsOnly,
+  limit: input.limit,
+  ...(input.trailId === undefined ? {} : { trailId: input.trailId }),
+  ...(input.traceId === undefined ? {} : { traceId: input.traceId }),
+});
+
+/**
+ * Query execution history from the tracing dev store.
+ *
+ * Reads the store from the `tracingResource` state. Returns an empty
+ * result set when no store has been configured.
+ */
+export const tracingQuery = trail('tracing.query', {
+  examples: [
+    { input: {}, name: 'Recent traces' },
+    { input: { trailId: 'user.create' }, name: 'Filter by trail' },
+    { input: { errorsOnly: true }, name: 'Errors only' },
+  ],
+  implementation: (input, ctx) => {
+    const state = tracingResource.from(ctx);
+    if (!state.store) {
+      return Result.ok({ count: 0, records: [] });
+    }
+    const records = state.store.query(buildQueryOptions(input));
+    const mapped = records.map(mapRecord);
+    return Result.ok({ count: mapped.length, records: mapped });
+  },
+  input: z.object({
+    errorsOnly: z.boolean().describe('Show only failed traces').default(false),
+    limit: z.number().describe('Max results').default(20),
+    traceId: z.string().describe('Show full trace tree').optional(),
+    trailId: z.string().describe('Filter by trail ID').optional(),
+  }),
+  intent: 'read',
+  meta: { category: 'infrastructure' },
+  output: tracingQueryOutput,
+  resources: [tracingResource],
+});

package/src/dev/trails/tracing-status.ts

@@ -0,0 +1,44 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { tracingResource } from '../tracing-resource.js';
+
+/** Output schema for the tracing.status trail. */
+const tracingStatusOutput = z.object({
+  active: z.boolean(),
+  recordCount: z.number(),
+  samplingConfig: z.object({
+    destroy: z.number(),
+    read: z.number(),
+    write: z.number(),
+  }),
+});
+
+/**
+ * Reports the current status of the tracing telemetry subsystem.
+ *
+ * Returns whether tracing is active, the current record count, and
+ * the sampling configuration for each intent. Reads all values from
+ * the `tracingResource` state.
+ */
+export const tracingStatus = trail('tracing.status', {
+  examples: [
+    {
+      input: {},
+      name: 'Check tracing status',
+    },
+  ],
+  implementation: (_input, ctx) => {
+    const state = tracingResource.from(ctx);
+    return Result.ok({
+      active: state.active,
+      recordCount: state.store?.count() ?? 0,
+      samplingConfig: { ...state.sampling },
+    });
+  },
+  input: z.object({}),
+  intent: 'read',
+  meta: { category: 'infrastructure' },
+  output: tracingStatusOutput,
+  resources: [tracingResource],
+});