Observabilité

Surveillez vos applications IA avec letracing, le logging et leshooks personnalisés dans Orka JS.

Observabilité Native & LLMOps

Ne naviguez plus à vue. Orka JS offre une introspection profonde de chaque appel LLM, exécution d'outil et récupération RAG. Surveillez la latence, la consommation de tokens et les erreurs via des hooks simples et puissants.

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

Suivi des Tokens : Consommation détaillée par trace pour une gestion précise des coûts.

Profilage de Latence : Identifiez instantanément les goulots d'étranglement dans vos chaînes RAG.

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.
      },
    }],
  },
});

Niveaux de Log

Niveau	Description
debug	Opérations internes détaillées
info	Opérations normales (défaut)
warn	Problèmes potentiels
error	Échecs uniquement

Tracing Manuel

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`);

💡 Conseil Production

En production, définissez logLevel: 'warn' pour réduire le bruit, et utilisez les hooks pour le monitoring structuré avec Datadog, Sentry, ou des tableaux de bord personnalisés.

OpenTelemetry — @orka-js/otel

Pour le tracing distribué avec des backends compatibles OpenTelemetry (Jaeger, Grafana Tempo, Honeycomb...), utilisez le package standalone @orka-js/otel. Il exporte les spans au format OTLP v1 JSON et supporte la propagation W3C traceparent. Compatible Edge — aucune dépendance Node.js.

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();

Propagation W3C TraceContext

Injectez et extrayez les headers traceparent pour propager les traces entre 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	Classe exporteur OTLP v1 JSON avec batching et retry
createOtelExporter()	Factory — crée et démarre un exporteur
W3CTraceContextPropagator	W3C traceparent inject / extract / generate
traceContextPropagator	Instance singleton de W3CTraceContextPropagator
SpanData	Interface d'entrée pour addSpan()