Observability entegrasyonları (OTLP preset'leri)

GNL'de gerçeğin kaynağı journal'dır. @gnldev/otel bir run'ı journal'dan post-hoc olarak gerçek bir OpenTelemetry trace'ine çevirir: deterministik trace/span id'leri → idempotent (aynı run iki kez export edilince aynı trace), çökme sonrası bile tam, replay'ler arası tutarlı. Bu exactly-once / crash-proof observability'dir — canlı-instrument eden framework'ler bunu veremez. OTLP export'u yalnızca bir "fiş"tir: sağlayıcıya bir kopya gönderir, ama sistemin doğruluğu ona bağlı değildir.

Her preset, sağlayıcının belgelenmiş OTLP/HTTP ucunu + kimlik header'larını hazır bir ExportRunToOtlpOptions'a çevirir. Mevcut preset'ler: langfuse (eu/us cloud ya da self-hosted, Basic auth), apiKeyOtlp (x-api-key + proje, any endpoint), braintrust (Bearer + x-bt-parent), honeycomb (x-honeycomb-team), datadogAgent (yerel Agent OTLP alıcısı) ve generic collector (Jaeger/Tempo/OTel Collector). Her preset'te endpoint override'ı vardır.

import { otlpPresets, exportRunToOtlp } from '@gnldev/otel';

// one line: preset → a ready export configuration (pure, no network call)
const cfg = otlpPresets.langfuse({
  publicKey: process.env.LF_PUBLIC!,
  secretKey: process.env.LF_SECRET!,
  region: 'eu',
});

// "plug" a run from the journal into the provider
const res = await exportRunToOtlp(reader, 'r1', cfg);
// res => { traceId, spans, ok, status }

otlpPresets.apiKeyOtlp({ endpoint: 'https://otel.example.com/v1/traces', apiKey, project: 'gnl-prod' });
otlpPresets.braintrust({ apiKey, project: 'gnl' });
otlpPresets.honeycomb({ apiKey, dataset: 'gnl' });
otlpPresets.datadogAgent({ host: 'localhost', port: 4318 });
otlpPresets.collector({ baseUrl: 'http://tempo:4318' });

Post-hoc export'a ek olarak @gnldev/otel/live gerçek-zamanlı izleme sunar: model/tool çağrıları gerçekten çalışırken canlı OTEL span'leri + maliyet yayınlar. Sarmalayıcılar durable'ın altına kompoze olur → replay'de (journal cache hit) hiç çalışmaz → canlı katman journal'a dokunmaz, determinizmi bozmaz. Gerçek wall-clock latency (non-det) taşıdığından yalnız exporter'a gider, journal'a değil.

import { liveObservability } from '@gnldev/otel/live';

const live = liveObservability({
  endpoint: 'http://localhost:4318/v1/traces',
  onCost: (c) => { if (c.costUsd > 1) alertBudget(c); }, // live budget alarm
});

await runDurable(live.instrument({ runId: 'r1', model, tools, prompt }));
await live.flush();
const total = live.cost(); // { inputTokens, ..., costUsd }