@telemetry-dev/otel 0.1.0

package/src/context.ts

@@ -0,0 +1,139 @@
+import {
+  type Attributes,
+  type Context,
+  context as apiContext,
+  type ContextManager,
+  createContextKey,
+  ROOT_CONTEXT,
+} from "@opentelemetry/api";
+import type { AsyncLocalStorage } from "node:async_hooks";
+
+import { jsonAttr } from "./attrs.ts";
+import { diag } from "./debug.ts";
+
+type AlsConstructor = new <T>() => AsyncLocalStorage<T>;
+type RuntimeGlobal = typeof globalThis & {
+  AsyncLocalStorage?: AlsConstructor;
+  process?: {
+    getBuiltinModule?: (id: string) => { AsyncLocalStorage?: AlsConstructor } | undefined;
+  };
+};
+
+// Synchronous, no `node:` static import, no top-level await — the dist must stay
+// require(esm)-compatible and runtime-neutral. Vercel Edge exposes AsyncLocalStorage as a global;
+// Node >= 20.19 and Workers with nodejs_compat expose process.getBuiltinModule.
+function loadAls(): AlsConstructor | undefined {
+  const g: RuntimeGlobal = globalThis;
+  if (g.AsyncLocalStorage) return g.AsyncLocalStorage;
+  try {
+    return g.process?.getBuiltinModule?.("node:async_hooks")?.AsyncLocalStorage;
+  } catch {}
+  return undefined;
+}
+
+const AlsCtor = loadAls();
+
+export const als: AsyncLocalStorage<Context> | undefined = AlsCtor
+  ? new AlsCtor<Context>()
+  : undefined;
+
+/**
+ * The active context: our AsyncLocalStorage when available, falling back to the OTel global
+ * context (which joins a host app's own OTel setup when one is registered).
+ */
+export function activeContext(): Context {
+  return als?.getStore() ?? apiContext.active();
+}
+
+/** Run `fn` with `ctx` active in both our ALS and the global OTel context manager. */
+export function withContext<T>(ctx: Context, fn: () => T): T {
+  const run = () => apiContext.with(ctx, fn);
+  return als ? als.run(ctx, run) : run();
+}
+
+export const PROPAGATED_KEY = createContextKey("telemetry.dev propagated attributes");
+
+export interface PropagatedAttributes {
+  /** Stamped as user.id on every span and log record in scope. */
+  userId?: string;
+  /** Stamped as gen_ai.conversation.id on every span and log record in scope. */
+  sessionId?: string;
+  /** Stamped as td.metadata.<key> on every span and log record in scope. */
+  metadata?: Record<string, unknown>;
+}
+
+const RESERVED_METADATA_KEYS = new Set(["userId", "sessionId", "user_id", "session_id"]);
+
+export function buildPropagatedAttributes(attrs: PropagatedAttributes): Attributes {
+  const out: Attributes = {};
+  if (attrs.userId !== undefined) out["user.id"] = attrs.userId;
+  if (attrs.sessionId !== undefined) out["gen_ai.conversation.id"] = attrs.sessionId;
+  if (attrs.metadata) {
+    for (const [key, value] of Object.entries(attrs.metadata)) {
+      if (RESERVED_METADATA_KEYS.has(key)) {
+        diag.debug(
+          `metadata key "${key}" is reserved; use the userId/sessionId fields of propagateAttributes`,
+        );
+        continue;
+      }
+      const attr = typeof value === "string" ? value : jsonAttr(value);
+      if (attr !== undefined) out[`td.metadata.${key}`] = attr;
+    }
+  }
+  return out;
+}
+
+export function propagatedFromContext(ctx: Context): Attributes | undefined {
+  return ctx.getValue(PROPAGATED_KEY) as Attributes | undefined;
+}
+
+/**
+ * Stamp correlation attributes (user, session/conversation, metadata) on every span and log
+ * record created inside `fn`. Inner scopes merge over outer ones per key. Works before init().
+ */
+export function propagateAttributes<T>(attributes: PropagatedAttributes, fn: () => T): T {
+  const base = activeContext();
+  const merged = { ...propagatedFromContext(base), ...buildPropagatedAttributes(attributes) };
+  return withContext(base.setValue(PROPAGATED_KEY, merged), fn);
+}
+
+/** Minimal ContextManager over our AsyncLocalStorage, registered only for registerGlobal. */
+export class AlsContextManager implements ContextManager {
+  constructor(private readonly storage: AsyncLocalStorage<Context>) {}
+
+  active(): Context {
+    return this.storage.getStore() ?? ROOT_CONTEXT;
+  }
+
+  with<A extends unknown[], F extends (...args: A) => ReturnType<F>>(
+    context: Context,
+    fn: F,
+    thisArg?: ThisParameterType<F>,
+    ...args: A
+  ): ReturnType<F> {
+    const cb = thisArg == null ? fn : fn.bind(thisArg);
+    return this.storage.run(context, cb as (...args: A) => ReturnType<F>, ...args);
+  }
+
+  bind<T>(context: Context, target: T): T {
+    if (typeof target === "function") {
+      const storage = this.storage;
+      const bound = function (this: unknown, ...args: unknown[]) {
+        return storage.run(context, () =>
+          (target as (...a: unknown[]) => unknown).apply(this, args),
+        );
+      };
+      return bound as T;
+    }
+    return target;
+  }
+
+  enable(): this {
+    return this;
+  }
+
+  disable(): this {
+    this.storage.disable();
+    return this;
+  }
+}

package/src/debug.ts

@@ -0,0 +1,32 @@
+import type { LogLevel, SdkLogLevel } from "./config.ts";
+
+const ORDER: Record<SdkLogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
+
+let currentLevel: SdkLogLevel = "warn";
+
+export function setLogLevel(level: SdkLogLevel): void {
+  currentLevel = level;
+}
+
+function emit(level: LogLevel, args: unknown[]): void {
+  if (ORDER[level] < ORDER[currentLevel]) return;
+  // eslint-disable-next-line no-console
+  console[level]("[telemetry.dev]", ...args);
+}
+
+export const diag = {
+  debug: (...args: unknown[]) => emit("debug", args),
+  info: (...args: unknown[]) => emit("info", args),
+  warn: (...args: unknown[]) => emit("warn", args),
+  error: (...args: unknown[]) => emit("error", args),
+};
+
+/** Fail-open guard: SDK internals report through onError + diagnostics, never into user code. */
+export function reportError(onError: ((error: unknown) => void) | undefined, error: unknown): void {
+  try {
+    onError?.(error);
+  } catch {
+    // onError itself must never propagate
+  }
+  diag.error(error);
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+export { jsonAttr, omitUndefined, SCOPE_NAME, SCOPE_VERSION } from "./attrs.ts";
+export {
+  type BatchOptions,
+  DEFAULT_BASE_URL,
+  DEFAULT_BATCH,
+  type ExportMode,
+  type LogLevel,
+  resolveEnv,
+  type SdkLogLevel,
+} from "./config.ts";
+export {
+  activeContext,
+  als,
+  AlsContextManager,
+  buildPropagatedAttributes,
+  propagateAttributes,
+  type PropagatedAttributes,
+  PROPAGATED_KEY,
+  propagatedFromContext,
+  withContext,
+} from "./context.ts";
+export { diag, reportError, setLogLevel } from "./debug.ts";
+export {
+  BATCHED_METRIC_INTERVAL_MS,
+  createMetricsPipeline,
+  DORMANT_INTERVAL_MS,
+  DURATION_BUCKETS,
+  type MetricsPipeline,
+  TOKEN_BUCKETS,
+} from "./metrics.ts";
+export {
+  createTelemetrySpanExporter,
+  TelemetrySpanProcessor,
+  type TelemetrySpanProcessorOptions,
+} from "./otel.ts";
+export { StampingSpanProcessor, type StampingProcessorOptions } from "./processor.ts";
+export {
+  createLogExporter,
+  createMetricExporter,
+  createTraceExporter,
+  maybeGzip,
+  otlpHeaders,
+  type OtlpTarget,
+  postOtlp,
+  type Transport,
+} from "./transport.ts";

package/src/metrics.ts

@@ -0,0 +1,91 @@
+import type { Attributes } from "@opentelemetry/api";
+import type { Resource } from "@opentelemetry/resources";
+import {
+  MeterProvider,
+  PeriodicExportingMetricReader,
+  type PushMetricExporter,
+} from "@opentelemetry/sdk-metrics";
+import type { ReadableSpan } from "@opentelemetry/sdk-trace-base";
+
+import { omitUndefined, SCOPE_NAME, SCOPE_VERSION } from "./attrs.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}).
+export 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,
+];
+export const TOKEN_BUCKETS = [
+  1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864,
+];
+
+const DURATION_OPERATIONS = new Set(["chat", "invoke_agent", "embeddings", "execute_tool"]);
+const TOKEN_OPERATIONS = new Set(["chat", "invoke_agent", "embeddings"]);
+
+// Dormant interval for immediate mode, where flush()/shutdown() drive the only exports.
+export const DORMANT_INTERVAL_MS = 2 ** 31 - 1;
+export const BATCHED_METRIC_INTERVAL_MS = 60_000;
+
+export interface MetricsPipeline {
+  record(span: ReadableSpan): void;
+  forceFlush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+function stringAttr(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+export function createMetricsPipeline({
+  resource,
+  exporter,
+  exportIntervalMillis,
+}: {
+  resource: Resource;
+  exporter: PushMetricExporter;
+  exportIntervalMillis: number;
+}): MetricsPipeline {
+  const reader = new PeriodicExportingMetricReader({ exporter, exportIntervalMillis });
+  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 },
+  });
+
+  const record = (span: ReadableSpan): void => {
+    const operation = span.attributes["gen_ai.operation.name"];
+    if (typeof operation !== "string" || !DURATION_OPERATIONS.has(operation)) return;
+    const attrs: Attributes = omitUndefined({
+      "gen_ai.operation.name": operation,
+      "gen_ai.provider.name": stringAttr(span.attributes["gen_ai.provider.name"]),
+      "gen_ai.request.model": stringAttr(span.attributes["gen_ai.request.model"]),
+      "gen_ai.response.model": stringAttr(span.attributes["gen_ai.response.model"]),
+    });
+    const durationSec = span.duration[0] + span.duration[1] / 1e9;
+    const errorType = stringAttr(span.attributes["error.type"]);
+    durationHistogram.record(
+      durationSec,
+      errorType !== undefined ? { ...attrs, "error.type": errorType } : attrs,
+    );
+    if (!TOKEN_OPERATIONS.has(operation)) return;
+    const inputTokens = span.attributes["gen_ai.usage.input_tokens"];
+    if (typeof inputTokens === "number") {
+      tokenHistogram.record(inputTokens, { ...attrs, "gen_ai.token.type": "input" });
+    }
+    const outputTokens = span.attributes["gen_ai.usage.output_tokens"];
+    if (typeof outputTokens === "number") {
+      tokenHistogram.record(outputTokens, { ...attrs, "gen_ai.token.type": "output" });
+    }
+  };
+
+  return {
+    record,
+    forceFlush: () => reader.forceFlush(),
+    shutdown: () => meterProvider.shutdown(),
+  };
+}

package/src/otel.ts

@@ -0,0 +1,166 @@
+import type { Context } from "@opentelemetry/api";
+import { ExportResultCode } from "@opentelemetry/core";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import type {
+  ReadableSpan,
+  Span,
+  SpanExporter,
+  SpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+
+import {
+  type BatchOptions,
+  DEFAULT_BASE_URL,
+  DEFAULT_BATCH,
+  type ExportMode,
+  resolveEnv,
+} from "./config.ts";
+import { diag } from "./debug.ts";
+import {
+  BATCHED_METRIC_INTERVAL_MS,
+  createMetricsPipeline,
+  DORMANT_INTERVAL_MS,
+  type MetricsPipeline,
+} from "./metrics.ts";
+import { StampingSpanProcessor } from "./processor.ts";
+import {
+  createMetricExporter,
+  createTraceExporter,
+  otlpHeaders,
+  type Transport,
+} from "./transport.ts";
+
+export interface TelemetrySpanProcessorOptions {
+  /** telemetry.dev ingest key. Falls back to `TELEMETRY_DEV_API_KEY`; absent ⇒ no-op processor. */
+  apiKey?: string;
+  /** Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  baseUrl?: string;
+  /** "batched" (default) or "immediate". */
+  exportMode?: ExportMode;
+  batch?: BatchOptions;
+  /** Default for BYO providers: export EVERY span (the user deliberately attached the processor). */
+  spanFilter?: (span: ReadableSpan) => boolean;
+  /** Record GenAI duration/token histograms for exported chat/agent/embedding/tool spans. Default true. */
+  metrics?: boolean;
+  /** service.name on the metrics resource. Falls back to `OTEL_SERVICE_NAME`. */
+  serviceName?: string;
+  /** deployment.environment.name on the metrics resource. Falls back to `TELEMETRY_DEV_ENVIRONMENT`. */
+  environment?: string;
+  fetch?: typeof fetch;
+  onError?: (error: unknown) => void;
+  /** Advanced/test seam: replaces the OTLP fetch exporter. */
+  spanExporter?: SpanExporter;
+}
+
+/**
+ * BYO-OpenTelemetry surface: add this processor to your own TracerProvider (NodeSDK,
+ * registerOTel, …) to ship its spans to telemetry.dev. Also stamps propagateAttributes
+ * correlation attributes onto every span it sees.
+ */
+export class TelemetrySpanProcessor implements SpanProcessor {
+  private readonly inner?: StampingSpanProcessor;
+  private readonly metrics?: MetricsPipeline;
+
+  constructor(options: TelemetrySpanProcessorOptions = {}) {
+    const env = resolveEnv();
+    const apiKey = options.apiKey ?? env.TELEMETRY_DEV_API_KEY;
+    const baseUrl = (options.baseUrl ?? env.TELEMETRY_DEV_BASE_URL ?? DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      "",
+    );
+    const transport: Transport = {
+      fetchImpl: options.fetch ?? globalThis.fetch,
+      onError: options.onError,
+    };
+
+    const exporter =
+      options.spanExporter ??
+      (apiKey
+        ? createTraceExporter(
+            { url: `${baseUrl}/v1/traces`, headers: otlpHeaders(apiKey) },
+            transport,
+          )
+        : undefined);
+    if (!exporter) {
+      diag.debug(
+        "no api key (apiKey option or TELEMETRY_DEV_API_KEY); TelemetrySpanProcessor is a no-op",
+      );
+      return;
+    }
+
+    const exportMode = options.exportMode ?? "batched";
+    if (options.metrics !== false && apiKey) {
+      const resource = resourceFromAttributes({
+        "service.name": options.serviceName ?? env.OTEL_SERVICE_NAME ?? "unknown_service",
+        "deployment.environment.name":
+          options.environment ?? env.TELEMETRY_DEV_ENVIRONMENT ?? "production",
+      });
+      this.metrics = createMetricsPipeline({
+        resource,
+        exporter: createMetricExporter(
+          { url: `${baseUrl}/v1/metrics`, headers: otlpHeaders(apiKey) },
+          transport,
+        ),
+        exportIntervalMillis:
+          exportMode === "batched" ? BATCHED_METRIC_INTERVAL_MS : DORMANT_INTERVAL_MS,
+      });
+    }
+
+    const metrics = this.metrics;
+    this.inner = new StampingSpanProcessor({
+      exporter,
+      exportMode,
+      batch: { ...DEFAULT_BATCH, ...options.batch },
+      spanFilter: options.spanFilter,
+      recordMetrics: metrics ? (span) => metrics.record(span) : undefined,
+      onError: options.onError,
+    });
+  }
+
+  onStart(span: Span, parentContext: Context): void {
+    this.inner?.onStart(span, parentContext);
+  }
+
+  onEnd(span: ReadableSpan): void {
+    this.inner?.onEnd(span);
+  }
+
+  forceFlush(): Promise<void> {
+    return Promise.all([this.inner?.forceFlush(), this.metrics?.forceFlush()]).then(
+      () => undefined,
+    );
+  }
+
+  shutdown(): Promise<void> {
+    return Promise.all([this.inner?.shutdown(), this.metrics?.shutdown()]).then(() => undefined);
+  }
+}
+
+/** Raw OTLP/protobuf fetch exporter for users wiring their own BatchSpanProcessor. */
+export function createTelemetrySpanExporter(
+  options: {
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    onError?: (error: unknown) => void;
+  } = {},
+): SpanExporter {
+  const env = resolveEnv();
+  const apiKey = options.apiKey ?? env.TELEMETRY_DEV_API_KEY;
+  const baseUrl = (options.baseUrl ?? env.TELEMETRY_DEV_BASE_URL ?? DEFAULT_BASE_URL).replace(
+    /\/+$/,
+    "",
+  );
+  if (!apiKey) {
+    diag.debug("no api key (apiKey option or TELEMETRY_DEV_API_KEY); exporter is a no-op");
+    return {
+      export: (_spans, resultCallback) => resultCallback({ code: ExportResultCode.SUCCESS }),
+      forceFlush: () => Promise.resolve(),
+      shutdown: () => Promise.resolve(),
+    };
+  }
+  return createTraceExporter(
+    { url: `${baseUrl}/v1/traces`, headers: otlpHeaders(apiKey) },
+    { fetchImpl: options.fetch ?? globalThis.fetch, onError: options.onError },
+  );
+}

package/src/processor.ts

@@ -0,0 +1,72 @@
+import type { Attributes, Context } from "@opentelemetry/api";
+import {
+  BatchSpanProcessor,
+  type ReadableSpan,
+  SimpleSpanProcessor,
+  type Span,
+  type SpanExporter,
+  type SpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+
+import type { BatchOptions, ExportMode } from "./config.ts";
+import { activeContext, PROPAGATED_KEY, propagatedFromContext } from "./context.ts";
+import { reportError } from "./debug.ts";
+
+export interface StampingProcessorOptions {
+  exporter: SpanExporter;
+  exportMode: ExportMode;
+  batch: Required<BatchOptions>;
+  spanFilter?: (span: ReadableSpan) => boolean;
+  recordMetrics?: (span: ReadableSpan) => void;
+  onError?: (error: unknown) => void;
+}
+
+/**
+ * The vendor span processor: stamps propagated correlation attributes onto every span at start,
+ * then filters, records auto-metrics, and delegates to a Batch/SimpleSpanProcessor at end.
+ */
+export class StampingSpanProcessor implements SpanProcessor {
+  private readonly inner: SpanProcessor;
+
+  constructor(private readonly options: StampingProcessorOptions) {
+    this.inner =
+      options.exportMode === "immediate"
+        ? new SimpleSpanProcessor(options.exporter)
+        : new BatchSpanProcessor(options.exporter, options.batch);
+  }
+
+  onStart(span: Span, parentContext: Context): void {
+    try {
+      const propagated =
+        (parentContext.getValue(PROPAGATED_KEY) as Attributes | undefined) ??
+        propagatedFromContext(activeContext());
+      if (propagated) span.setAttributes(propagated);
+    } catch (error) {
+      reportError(this.options.onError, error);
+    }
+    this.inner.onStart(span, parentContext);
+  }
+
+  onEnd(span: ReadableSpan): void {
+    try {
+      if (this.options.spanFilter && !this.options.spanFilter(span)) return;
+    } catch (error) {
+      // A throwing filter must not drop spans; fall through and export.
+      reportError(this.options.onError, error);
+    }
+    try {
+      this.options.recordMetrics?.(span);
+    } catch (error) {
+      reportError(this.options.onError, error);
+    }
+    this.inner.onEnd(span);
+  }
+
+  forceFlush(): Promise<void> {
+    return this.inner.forceFlush();
+  }
+
+  shutdown(): Promise<void> {
+    return this.inner.shutdown();
+  }
+}