@graphorin/observability

Observability primitives for the Graphorin framework.

@graphorin/observability ships every cross-cutting tracing, redaction, replay, cost, and structured-logging primitive every other @graphorin/* package builds on. The package is intentionally opinionated: every exporter must be wrapped through withValidation(...) before it can ship a single span, the validator defaults to default-deny non-public, and the framework makes zero outbound network calls without an explicit user action.

Highlights

• Typed AISpan<T> tracer. createTracer({...}) returns a GraphorinTracer that emits AISpan<SpanType> records compatible with OpenTelemetry. Sampling rules + per-event sampling cover noisy span kinds (memory.embed, tool.execute.partial, …).
• Mandatory withValidation(...) wrapper. Every exporter passed to createTracer({ exporters }) is wrapped through the configured RedactionValidator. Registering a raw exporter while validation: 'off' triggers UnvalidatedExporterError at startup - there is no silent path.
• RedactionValidator with 14 built-in patterns. API key / JWT / PEM private key / GitHub PAT / AWS access key / Graphorin token / bearer header / basic-auth header / email / credit card / US SSN / E.164 phone / IBAN - all on by default. Three additional patterns (IPv4, IPv6, GCP service account) are opt-in.
• OpenTelemetry GenAI semantic-conventions conformance. emitGenAIAttributes(span, {...}), emitGenAIMessageEvents(span, [...]), and deriveGenAISystem(...) ship the canonical gen_ai.* attribute family alongside the existing graphorin.* attributes - additive, never replacing.
• OpenInference span-kind layer. emitOpenInferenceKind(span) emits the openinference.span.kind attribute via the canonical per-SpanType mapping (agent.* → AGENT, provider.* → LLM, tool.execute → TOOL, memory.* → RETRIEVER / EMBEDDING, workflow.* → CHAIN, agent.evaluator.iteration → EVALUATOR).
• ConsoleExporter, JSONLExporter, OTLPHttpExporter. The built-in exporters cover dev (console), replay (append-only JSONL with 0700 directories + 0600 files), and remote OTLP collectors (fetch-based reference implementation, swappable fetchImpl).
• Sanitized-by-default Replay. createReplay({...}) exposes a run(...) async iterator that yields replay.start / replay.event / replay.skipped / replay.end markers. Raw mode requires the canReadRaw callback to return true and emits an audit-bridge entry on every invocation.
• Hierarchical CostTracker. createCostTracker({...}) rolls up tokens + cost across parent-child spans and supports per-run / per-session / per-agent / per-user budgets with an onExceed callback.
• Structured logger. createLogger({...}) writes JSON or pretty records, automatically correlates with the current span via withCurrentSpan(...), and pipes every field through the validator.
• Zero-default telemetry. getTelemetryStatus() and announceTelemetryPosture() expose the v0.1 promise: the framework performs zero outbound network calls, no version pings, no crash reports, no auto-updates. The GRAPHORIN_TELEMETRY and GRAPHORIN_NO_PHONE_HOME environment variables are reserved for forward compatibility and are acknowledged at startup.

Installation

pnpm add @graphorin/observability
# Optional peer deps for OTLP export - install only when you need them:
pnpm add @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http

Quick start

import {
  createTracer,
  createConsoleExporter,
  createJSONLExporter,
  withValidation,
} from '@graphorin/observability';

const tracer = createTracer({
  serviceName: 'my-assistant',
  exporters: [
    // Auto-wrapped via the tracer-managed validator.
    createConsoleExporter({ pretty: true }),
    // Manually wrapped - useful when each exporter needs its own policy.
    withValidation(createJSONLExporter({ path: './traces' }), {
      minTier: 'internal',
    }),
  ],
  validation: { minTier: 'public', failOnUnredactedSensitive: false },
  sampling: {
    rate: 1.0,
    rules: [{ type: 'memory.embed', rate: 0.1 }],
  },
});

await tracer.span(
  { type: 'agent.run', attrs: { 'graphorin.agent.id': 'support-bot' } },
  async (span) => {
    span.setAttributes({ 'graphorin.session.id': 'session-123' });
    return runAgent();
  },
);

await tracer.shutdown();

License

MIT © 2026 Oleksiy Stepurenko.

Project Graphorin · v0.6.0 · MIT License · © 2026 Oleksiy Stepurenko · https://github.com/o-stepper/graphorin