@telemetry-dev/sdk 0.1.0

package/src/observe.ts

@@ -0,0 +1,64 @@
+import { reportError, withContext } from "@telemetry-dev/otel";
+
+import { currentClient } from "./client.ts";
+import { createSpanHandle, isThenable, type SpanHandle, type StartSpanOptions } from "./span.ts";
+
+export interface ObserveOptions extends StartSpanOptions {
+  /** Span name; defaults to fn.name or "anonymous". */
+  name?: string;
+}
+
+/**
+ * Wrap a function (sync or async) so every call becomes a span: args → input, return value →
+ * output, thrown/rejected errors captured and rethrown. Activates context so nested SDK calls
+ * parent to it. Resolves the client at call time, so wrapping at module load before init() works.
+ */
+export function observe<TArgs extends unknown[], TReturn>(
+  fn: (...args: TArgs) => TReturn,
+  options?: ObserveOptions,
+): (...args: TArgs) => TReturn {
+  const wrapped = function (this: unknown, ...args: TArgs): TReturn {
+    const core = currentClient().core;
+    if (!core) return fn.apply(this, args);
+
+    let handle: SpanHandle;
+    try {
+      const name = options?.name ?? (fn.name || "anonymous");
+      const input =
+        options?.input !== undefined
+          ? options.input
+          : args.length === 0
+            ? undefined
+            : args.length === 1
+              ? args[0]
+              : args;
+      handle = createSpanHandle(core, name, { ...options, input });
+    } catch (error) {
+      reportError(core.config.onError, error);
+      return fn.apply(this, args);
+    }
+
+    try {
+      const result = withContext(handle.context, () => fn.apply(this, args));
+      if (isThenable(result)) {
+        return (result as unknown as Promise<unknown>).then(
+          (value) => {
+            handle.end({ output: value });
+            return value;
+          },
+          (error: unknown) => {
+            handle.end({ error });
+            throw error;
+          },
+        ) as TReturn;
+      }
+      handle.end({ output: result });
+      return result;
+    } catch (error) {
+      handle.end({ error });
+      throw error;
+    }
+  };
+  Object.defineProperty(wrapped, "name", { value: fn.name || "anonymous", configurable: true });
+  return wrapped;
+}

package/src/span.ts

@@ -0,0 +1,272 @@
+import {
+  type Context,
+  defaultTextMapSetter,
+  type Span,
+  type SpanContext,
+  SpanKind,
+  SpanStatusCode,
+  trace,
+} from "@opentelemetry/api";
+import { parseTraceParent, W3CTraceContextPropagator } from "@opentelemetry/core";
+
+import {
+  activeContext,
+  omitUndefined,
+  PROPAGATED_KEY,
+  propagatedFromContext,
+  reportError,
+  withContext,
+} from "@telemetry-dev/otel";
+
+import {
+  type FieldCaptureConfig,
+  fieldsToAttributes,
+  SPAN_TYPE_OPERATIONS,
+  type SpanFields,
+  type SpanType,
+} from "./attrs.ts";
+import { type ClientCore, currentClient } from "./client.ts";
+import { NOOP_SPAN_HANDLE } from "./noop.ts";
+
+export type ParentRef = string /* W3C traceparent */ | SpanHandle | SpanContext | Context;
+
+export interface StartSpanOptions extends SpanFields {
+  /** Default "span" → operation "function". */
+  type?: SpanType;
+  /** Parent override; defaults to the active context. */
+  parent?: ParentRef;
+  startTime?: Date | number;
+  /** Per-call override of the global captureInput. */
+  captureInput?: boolean;
+  /** Per-call override of the global captureOutput. */
+  captureOutput?: boolean;
+}
+
+export interface SpanHandle {
+  /** Raw OTel span (interop escape hatch). */
+  readonly span: Span;
+  /** Context with this span active, for manual parenting. */
+  readonly context: Context;
+  readonly traceId: string;
+  readonly spanId: string;
+  /** W3C traceparent for this span; null for the no-op handle. */
+  readonly traceparent: string | null;
+  readonly isRecording: boolean;
+  update(fields: SpanFields): SpanHandle;
+  end(fields?: SpanFields & { endTime?: Date | number }): void;
+}
+
+interface SpanMeta {
+  type: SpanType;
+  capture: FieldCaptureConfig;
+  onError?: (error: unknown) => void;
+}
+
+// Remembers each span's type + capture flags so update()/end()/updateActiveSpan map
+// input/output to the right gen_ai.* keys.
+const SPAN_META = new WeakMap<Span, SpanMeta>();
+
+const SEVERITY_ERROR = 17;
+
+export function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value != null &&
+    (typeof value === "object" || typeof value === "function") &&
+    "then" in value &&
+    typeof value.then === "function"
+  );
+}
+
+function isContext(value: object): value is Context {
+  return "getValue" in value && typeof value.getValue === "function";
+}
+
+function isSpanHandle(value: object): value is SpanHandle {
+  return "span" in value && "context" in value && "update" in value;
+}
+
+// Ambient propagated correlation attrs survive explicit parent overrides: contexts that lack
+// PROPAGATED_KEY inherit it from the active context.
+function withAmbientPropagated(ctx: Context): Context {
+  if (propagatedFromContext(ctx)) return ctx;
+  const ambient = propagatedFromContext(activeContext());
+  return ambient ? ctx.setValue(PROPAGATED_KEY, ambient) : ctx;
+}
+
+function resolveParent(parent: ParentRef | undefined): Context {
+  const base = activeContext();
+  if (parent === undefined) return base;
+  if (typeof parent === "string") {
+    const parsed = parseTraceParent(parent);
+    if (!parsed) return base;
+    return trace.setSpanContext(base, { ...parsed, isRemote: true });
+  }
+  if (isSpanHandle(parent)) return withAmbientPropagated(parent.context);
+  if (isContext(parent)) return withAmbientPropagated(parent);
+  return trace.setSpanContext(base, parent);
+}
+
+function applyError(span: Span, error: unknown): void {
+  const err = error instanceof Error ? error : undefined;
+  const errorType = err?.name ?? "Error";
+  const message = err?.message ?? String(error);
+  span.setStatus({ code: SpanStatusCode.ERROR });
+  span.setAttribute("error.type", errorType);
+  span.addEvent(
+    "exception",
+    omitUndefined({
+      "exception.type": errorType,
+      "exception.message": message,
+      "exception.stacktrace": err?.stack,
+      "log.severity_number": SEVERITY_ERROR,
+    }),
+  );
+}
+
+function applyFields(span: Span, meta: SpanMeta, fields: SpanFields): void {
+  if (fields.name) span.updateName(fields.name);
+  const attrs = fieldsToAttributes(fields, meta.type, meta.capture);
+  if (Object.keys(attrs).length > 0) span.setAttributes(attrs);
+  if (fields.error !== undefined) applyError(span, fields.error);
+}
+
+function metaFor(core: ClientCore, options?: StartSpanOptions): SpanMeta {
+  const cfg = core.config;
+  return {
+    type: options?.type ?? "span",
+    capture: {
+      mask: cfg.mask,
+      maxAttributeLength: cfg.maxAttributeLength,
+      onError: cfg.onError,
+      captureInput: options?.captureInput ?? cfg.captureInput,
+      captureOutput: options?.captureOutput ?? cfg.captureOutput,
+    },
+    onError: cfg.onError,
+  };
+}
+
+export function createSpanHandle(
+  core: ClientCore,
+  name: string,
+  options: StartSpanOptions = {},
+): SpanHandle {
+  const meta = metaFor(core, options);
+  const parentCtx = resolveParent(options.parent);
+  const span = core.tracer.startSpan(
+    name,
+    {
+      kind: SpanKind.INTERNAL,
+      startTime: options.startTime,
+      attributes: { "gen_ai.operation.name": SPAN_TYPE_OPERATIONS[meta.type] },
+    },
+    parentCtx,
+  );
+  SPAN_META.set(span, meta);
+  applyFields(span, meta, options);
+
+  const spanContext = span.spanContext();
+  const flags = (spanContext.traceFlags & 0xff).toString(16).padStart(2, "0");
+  const handle: SpanHandle = {
+    span,
+    context: trace.setSpan(parentCtx, span),
+    traceId: spanContext.traceId,
+    spanId: spanContext.spanId,
+    traceparent: `00-${spanContext.traceId}-${spanContext.spanId}-${flags}`,
+    get isRecording() {
+      return span.isRecording();
+    },
+    update(fields) {
+      try {
+        applyFields(span, meta, fields);
+      } catch (error) {
+        reportError(meta.onError, error);
+      }
+      return handle;
+    },
+    end(fields) {
+      try {
+        if (fields) applyFields(span, meta, fields);
+      } catch (error) {
+        reportError(meta.onError, error);
+      }
+      span.end(fields?.endTime);
+    },
+  };
+  return handle;
+}
+
+/** Start a span WITHOUT activating context; the caller must call .end(). */
+export function startSpan(name: string, options?: StartSpanOptions): SpanHandle {
+  const core = currentClient().core;
+  if (!core) return NOOP_SPAN_HANDLE;
+  try {
+    return createSpanHandle(core, name, options);
+  } catch (error) {
+    reportError(core.config.onError, error);
+    return NOOP_SPAN_HANDLE;
+  }
+}
+
+export function runWithHandle<T>(handle: SpanHandle, fn: (span: SpanHandle) => T): T {
+  try {
+    const result = withContext(handle.context, () => fn(handle));
+    if (isThenable(result)) {
+      return (result as unknown as Promise<unknown>).then(
+        (value) => {
+          handle.end();
+          return value;
+        },
+        (error: unknown) => {
+          handle.end({ error });
+          throw error;
+        },
+      ) as T;
+    }
+    handle.end();
+    return result;
+  } catch (error) {
+    handle.end({ error });
+    throw error;
+  }
+}
+
+export function startActiveSpan<T>(name: string, fn: (span: SpanHandle) => T): T;
+export function startActiveSpan<T>(
+  name: string,
+  options: StartSpanOptions,
+  fn: (span: SpanHandle) => T,
+): T;
+export function startActiveSpan<T>(
+  name: string,
+  optionsOrFn: StartSpanOptions | ((span: SpanHandle) => T),
+  maybeFn?: (span: SpanHandle) => T,
+): T {
+  const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn!;
+  const options = typeof optionsOrFn === "function" ? undefined : optionsOrFn;
+  const handle = startSpan(name, options);
+  if (!handle.isRecording) return fn(handle);
+  return runWithHandle(handle, fn);
+}
+
+/** Update the innermost active span; no-op when none is recording. */
+export function updateActiveSpan(fields: SpanFields): void {
+  const core = currentClient().core;
+  if (!core) return;
+  try {
+    const span = trace.getSpan(activeContext());
+    if (!span?.isRecording()) return;
+    const meta = SPAN_META.get(span) ?? metaFor(core);
+    applyFields(span, meta, fields);
+  } catch (error) {
+    reportError(core.config.onError, error);
+  }
+}
+
+const PROPAGATOR = new W3CTraceContextPropagator();
+
+/** Serialize the active span context as a W3C traceparent; null when there is none. */
+export function getTraceparent(): string | null {
+  const carrier: { traceparent?: string } = {};
+  PROPAGATOR.inject(activeContext(), carrier, defaultTextMapSetter);
+  return carrier.traceparent ?? null;
+}