@telemetry-dev/tanstack-ai 0.1.0

package/src/otel.ts

@@ -0,0 +1,247 @@
+import { type Attributes, type Histogram, type Span, type Tracer } from "@opentelemetry/api";
+import {
+  ProtobufMetricsSerializer,
+  ProtobufTraceSerializer,
+} from "@opentelemetry/otlp-transformer";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import {
+  AggregationTemporality,
+  MeterProvider,
+  PeriodicExportingMetricReader,
+  type PushMetricExporter,
+  type ResourceMetrics,
+} from "@opentelemetry/sdk-metrics";
+import { BasicTracerProvider, type ReadableSpan } from "@opentelemetry/sdk-trace-base";
+
+import type { ResolvedConfig } from "./config.ts";
+
+// Histogram bucket boundaries from the OTel GenAI semantic-convention recommendations for
+// gen_ai.client.operation.duration (seconds) and gen_ai.client.token.usage ({token}).
+const DURATION_BUCKETS = [
+  0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92,
+];
+const TOKEN_BUCKETS = [
+  1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864,
+];
+
+const SCOPE_NAME = "@telemetry-dev/tanstack-ai";
+const SCOPE_VERSION = "0.0.0";
+
+// Spans created by the SDK tracer are concrete `Span`s that, once `.end()`ed, also satisfy
+// ReadableSpan (the serializer's input). The integration only holds the api `Span` type, so the
+// emitter surface accepts `Span[]` and casts at the single serialize site.
+export interface Emitter {
+  tracer: Tracer;
+  recordDuration(seconds: number, attributes: Attributes): void;
+  recordTokens(tokenType: "input" | "output", count: number, attributes: Attributes): void;
+  flush(spans: Span[]): Promise<void>;
+}
+
+export interface EmitterOverrides {
+  // Test seam: capture serialized spans / recorded metric points instead of POSTing them.
+  sendSpans?: (spans: ReadableSpan[]) => Promise<void>;
+  recordDuration?: (seconds: number, attributes: Attributes) => void;
+  recordTokens?: (tokenType: "input" | "output", count: number, attributes: Attributes) => void;
+}
+
+type Transport = { fetchImpl: typeof fetch; onError?: (error: unknown) => void };
+
+const RETRY_DELAYS_MS = [100, 500] as const;
+
+const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
+
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+const cancelBody = async (res: Response) => {
+  try {
+    await res.body?.cancel();
+  } catch {}
+};
+
+const postOtlp = async ({
+  fetchImpl,
+  url,
+  headers,
+  body,
+}: {
+  fetchImpl: typeof fetch;
+  url: string;
+  headers: Record<string, string>;
+  body: Uint8Array;
+}) => {
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      const res = await fetchImpl(url, { method: "POST", headers, body });
+      if (res.ok || !RETRYABLE_STATUSES.has(res.status) || attempt === RETRY_DELAYS_MS.length) {
+        await cancelBody(res);
+        return res;
+      }
+      await cancelBody(res);
+    } catch (error) {
+      if (attempt === RETRY_DELAYS_MS.length) throw error;
+    }
+
+    await delay(RETRY_DELAYS_MS[attempt]!);
+  }
+};
+
+interface MetricsPipeline {
+  durationHistogram: Histogram;
+  tokenHistogram: Histogram;
+  shutdown: () => Promise<void>;
+}
+
+interface EmitterCore {
+  tracer: Tracer;
+  sendSpans: (spans: ReadableSpan[], transport: Transport) => Promise<void>;
+  buildMetrics: (transport: Transport) => MetricsPipeline;
+}
+
+const cache = new Map<string, EmitterCore>();
+
+const buildCore = (config: ResolvedConfig): EmitterCore => {
+  const { apiKey, baseUrl, environment, serviceName } = config;
+  const resource = resourceFromAttributes({
+    "service.name": serviceName,
+    "deployment.environment.name": environment,
+  });
+  const headers = {
+    "content-type": "application/x-protobuf",
+    authorization: `Bearer ${apiKey}`,
+  };
+
+  const provider = new BasicTracerProvider({ resource });
+  const tracer = provider.getTracer(SCOPE_NAME, SCOPE_VERSION);
+
+  const sendSpans = async (spans: ReadableSpan[], transport: Transport): Promise<void> => {
+    const body = ProtobufTraceSerializer.serializeRequest(spans);
+    if (!body || body.byteLength === 0) return;
+    const { fetchImpl, onError } = transport;
+    const res = await postOtlp({ fetchImpl, url: `${baseUrl}/v1/traces`, headers, body });
+    if (!res.ok) {
+      onError?.(new Error(`telemetry.dev trace ingest failed: ${res.status}`));
+    }
+  };
+
+  // Each emitter builds its OWN metrics pipeline bound to its OWN transport: the exporter closes
+  // over this call's fetch/onError, so concurrent same-identity emitters never flush metrics
+  // through one another's context. The pipeline is torn down on flush (which clears the reader's
+  // interval timer) and lazily rebuilt, so a reused globally-registered emitter gets a fresh meter
+  // per generation without leaking timers.
+  const buildMetrics = (transport: Transport): MetricsPipeline => {
+    const { fetchImpl, onError } = transport;
+    const metricsExporter: PushMetricExporter = {
+      export(resourceMetrics: ResourceMetrics, resultCallback) {
+        const body = ProtobufMetricsSerializer.serializeRequest(resourceMetrics);
+        if (!body || body.byteLength === 0) {
+          resultCallback({ code: 0 });
+          return;
+        }
+        // DELTA metric batches are not idempotent; a retry after an already-ingested response would double-count.
+        fetchImpl(`${baseUrl}/v1/metrics`, { method: "POST", headers, body })
+          .then((res) => {
+            if (!res.ok) {
+              const error = new Error(`telemetry.dev metric ingest failed: ${res.status}`);
+              onError?.(error);
+              resultCallback({ code: 1, error });
+              return;
+            }
+            resultCallback({ code: 0 });
+          })
+          .catch((error: unknown) => {
+            onError?.(error);
+            resultCallback({ code: 1, error: error instanceof Error ? error : undefined });
+          });
+      },
+      selectAggregationTemporality: () => AggregationTemporality.DELTA,
+      forceFlush: () => Promise.resolve(),
+      shutdown: () => Promise.resolve(),
+    };
+
+    // A long interval keeps the periodic timer dormant; the single flush is driven by shutdown().
+    const reader = new PeriodicExportingMetricReader({
+      exporter: metricsExporter,
+      exportIntervalMillis: 2 ** 31 - 1,
+    });
+    const meterProvider = new MeterProvider({ resource, readers: [reader] });
+    const meter = meterProvider.getMeter(SCOPE_NAME, SCOPE_VERSION);
+
+    const durationHistogram = meter.createHistogram("gen_ai.client.operation.duration", {
+      unit: "s",
+      advice: { explicitBucketBoundaries: DURATION_BUCKETS },
+    });
+    const tokenHistogram = meter.createHistogram("gen_ai.client.token.usage", {
+      unit: "{token}",
+      advice: { explicitBucketBoundaries: TOKEN_BUCKETS },
+    });
+
+    // shutdown() flushes the collected deltas through the exporter AND clears the interval timer.
+    return { durationHistogram, tokenHistogram, shutdown: () => meterProvider.shutdown() };
+  };
+
+  return { tracer, sendSpans, buildMetrics };
+};
+
+const coreFor = (config: ResolvedConfig): EmitterCore => {
+  const key = `${config.apiKey}|${config.baseUrl}|${config.environment}|${config.serviceName}`;
+  const cached = cache.get(key);
+  if (cached) return cached;
+  const core = buildCore(config);
+  cache.set(key, core);
+  return core;
+};
+
+export const createEmitter = (config: ResolvedConfig, overrides?: EmitterOverrides): Emitter => {
+  const core = coreFor(config);
+  const transport: Transport = { fetchImpl: config.fetchImpl, onError: config.onError };
+  const onError = config.onError;
+
+  // Spans are request-scoped: each emitter sends through its OWN transport, so concurrent
+  // same-identity emitters never cross-talk.
+  const sendSpans =
+    overrides?.sendSpans ?? ((spans: ReadableSpan[]) => core.sendSpans(spans, transport));
+
+  // Metrics are also per-emitter and bound to this call's transport. The pipeline is built lazily on
+  // first record and detached on flush, so a reused emitter rebuilds a fresh one each generation.
+  let metrics: MetricsPipeline | undefined;
+  const ensureMetrics = (): MetricsPipeline => (metrics ??= core.buildMetrics(transport));
+
+  const recordDuration =
+    overrides?.recordDuration ??
+    ((seconds: number, attributes: Attributes) =>
+      ensureMetrics().durationHistogram.record(seconds, attributes));
+  const recordTokens =
+    overrides?.recordTokens ??
+    ((tokenType: "input" | "output", count: number, attributes: Attributes) =>
+      ensureMetrics().tokenHistogram.record(count, {
+        ...attributes,
+        "gen_ai.token.type": tokenType,
+      }));
+
+  // Default: await the flush so serverless runtimes don't tear down before spans/metrics leave.
+  // When a waitUntil extender is supplied, hand off the combined promise and return immediately.
+  const flush = (spans: Span[]): Promise<void> => {
+    // Detach this generation's metrics pipeline synchronously so the next generation builds its own.
+    const pipeline = metrics;
+    metrics = undefined;
+    const p = (async () => {
+      try {
+        await sendSpans(spans as unknown as ReadableSpan[]);
+      } catch (e) {
+        onError?.(e);
+      }
+      try {
+        if (pipeline) await pipeline.shutdown();
+      } catch (e) {
+        onError?.(e);
+      }
+    })();
+    if (config.waitUntil) {
+      config.waitUntil(p);
+      return Promise.resolve();
+    }
+    return p;
+  };
+
+  return { tracer: core.tracer, recordDuration, recordTokens, flush };
+};