@aaac/observability

aaac-native, in-process observability recording for the AaaC toolchain. Records agent / process / promotion events into a local SQLite store and emits them to a generic OTEL backend. See docs/observability-spec/ for the full design.

Install

npm install @aaac/observability

Requires Node.js >= 22.5 (uses the built-in node:sqlite).

What it does

• In-process recording: @aaac/runtime emits agent-axis spans via observer.emit(); external processes (git / Cursor hooks, CI) register events via registerExternalEvent().
• Pipeline: EventCollector → Normalizer → Correlator (span lifecycle pairing, duration, traceId) → Enricher (TypeScript correlation completion) → SqliteSink
  • OtelEmitter.
• CanonicalEvent internal model with cross-axis links; OTEL is the export representation (Span / SpanLink).
• Generic OTEL aggregation: OtelEmitter batches CanonicalEvents to an OTLP-compatible backend (fail-open — local SQLite always records).
• Query (read path): QueryAdapter over the SQLite store — span / trace / link traversal, independent of the write path.

Library usage

import { createPipeline, EventCollector } from "@aaac/observability";

CLI: aaac-observ

A thin entrypoint for external event registration and querying (interface defined via cli-contracts).

aaac-observ record --event-type process.edit --lifecycle instant --attr edit.path=src/x.ts
aaac-observ query trace --trace-id <id>

E2E Test Helpers (observability stack)

The __tests__/e2e/stack/ directory contains a full E2E harness for the aaac observability stack (ClickHouse / Tempo / Grafana). Follow-up issues (#163+) can import the shared helpers:

import {
  seedAndBackfill,
  queryClickHouse,
  assertViewRow,
  applyAnalysisViews,
  waitForSeedData,
} from '@aaac/observability/__tests__/e2e/stack/helpers.js';
import { SEED_SESSION_ID } from
  '@aaac/observability/__tests__/e2e/stack/__fixtures__/observability-stack-seed.js';
import { loadStackConfig } from '@aaac/observability/src/e2e/load-stack-config.js';

// Example usage in a follow-up E2E test:
const config = loadStackConfig();
const seed = await seedAndBackfill(config, { flushTimeoutMs: 30_000 });
await waitForSeedData(config, SEED_SESSION_ID);
const rows = await queryClickHouse<{ session_id: string }>(
  config,
  'SELECT session_id FROM aaac_agent_sessions LIMIT 1',
);
assertViewRow(rows, 'session_id', SEED_SESSION_ID);
await seed.cleanup();

See docs/observability-setup.md for full E2E run instructions.

Documentation

• Event format and catalog: docs/observability-spec/event-catalog.md
• Architecture: docs/observability-spec/architecture.md
• 3-axis model: docs/observability-spec/shift-left-guidline-v2.md
• E2E setup and run: docs/observability-setup.md

License

MIT