Observability

Monitor your AI applications withtracing, logging, andcustom hooks in Orka JS.

Native Observability & LLMOps

Don't fly blind. Orka JS provides deep introspection into every LLM call, tool execution, and RAG retrieval. Monitor latencies, token usage, and errors with simple, powerful hooks.

observability: {
  logLevel: 'info',
  hooks: [{
    onTraceEnd: (trace) => {
      // Direct integration with Datadog/Sentry
      reportMetrics(trace.totalLatencyMs, trace.totalTokens);
    },
    onError: (err, ctx) => alertDevTeam(err)
  }],
}

Token Tracking: Detailed usage per trace for precise cost management.

Latency Profiling: Identify bottlenecks in your RAG or tool chains instantly.

Configuration

observability-config.ts

const orka = createOrka({
  llm: new OpenAIAdapter({ apiKey: '...' }),
  vectorDB: new MemoryVectorAdapter(),
  observability: {
    logLevel: 'info', // 'debug' | 'info' | 'warn' | 'error'
    hooks: [{
      onTraceStart: (trace) => {
        console.log(`🔍 Trace started: ${trace.name}`);
      },
      onTraceEnd: (trace) => {
        console.log(`✅ Done: ${trace.totalLatencyMs}ms, ${trace.totalTokens} tokens`);
      },
      onError: (error, context) => {
        console.error(`❌ Error: ${error.message}`, context);
        // Send to Sentry, Datadog, etc.
      },
    }],
  },
});

Log Levels

Level	Description
debug	Detailed internal operations
info	Normal operations (default)
warn	Potential issues
error	Failures only

Manual Tracing

tracing.ts

// Start a trace
const trace = orka.tracer.startTrace('my-pipeline', {
  userId: 'user-123',
});
 
// Add events
orka.tracer.addEvent(trace.id, {
  type: 'custom',
  name: 'preprocessing',
  startTime: Date.now(),
  endTime: Date.now() + 50,
});
 
// End the trace
const completed = orka.tracer.endTrace(trace.id);
console.log(`Total: ${completed?.totalLatencyMs}ms`);

💡 Production Tip

In production, set logLevel: 'warn' to reduce noise, and use hooks for structured monitoring with Datadog, Sentry, or custom dashboards.

OpenTelemetry — @orka-js/otel

For distributed tracing with OpenTelemetry-compatible backends (Jaeger, Grafana Tempo, Honeycomb...), use the standalone @orka-js/otel package. It exports spans in OTLP v1 JSON format and supports W3C traceparent propagation. Edge-compatible — no Node.js dependencies.

otel-exporter.ts

import { createOtelExporter } from '@orka-js/otel';
 
// Create and start the exporter (auto-flushes every 5s)
const exporter = createOtelExporter({
  endpoint: 'http://localhost:4318',   // OTLP collector endpoint
  serviceName: 'my-orka-app',
  headers: { Authorization: `Bearer ${process.env.OTEL_TOKEN}` }, // optional
  batchSize: 50,          // flush when 50 spans accumulated
  flushIntervalMs: 5000,  // or every 5 seconds
});
 
// Add a span
exporter.addSpan({
  traceId: 'a'.repeat(32),
  spanId:  'b'.repeat(16),
  name: 'llm/generate',
  startTimeMs: Date.now(),
  endTimeMs: Date.now() + 320,
  kind: 3, // CLIENT
  status: 'ok',
  attributes: {
    'llm.model': 'gpt-4o',
    'llm.tokens': 540,
    'llm.cached': false,
  },
});
 
// Manual flush
await exporter.flush();
 
// Graceful shutdown
await exporter.stop();

W3C TraceContext Propagation

Inject and extract traceparent headers to propagate traces across services.

propagator.ts

import { traceContextPropagator } from '@orka-js/otel';
 
// Generate a new trace context
const ctx = traceContextPropagator.generate();
// { traceId: 'a3f...', spanId: 'b7c...' }
 
// Inject into outgoing HTTP headers
const headers = traceContextPropagator.inject(ctx);
// { traceparent: '00-a3f...-b7c...-01' }
 
// Extract from incoming HTTP request headers
const incoming = { traceparent: '00-abc123...32chars-def456...16chars-01' };
const parent = traceContextPropagator.extract(incoming);
if (parent) {
  // Create a child span linked to the parent trace
  const child = traceContextPropagator.child(parent);
  console.log(child.traceId); // same as parent.traceId
  console.log(child.spanId);  // new spanId
}

Export	Description
OtelExporter	OTLP v1 JSON exporter class with batching and retry
createOtelExporter()	Factory — creates and starts an exporter
W3CTraceContextPropagator	W3C traceparent inject / extract / generate
traceContextPropagator	Singleton instance of W3CTraceContextPropagator
SpanData	Input interface for addSpan()