@nightowlsdev/telemetry-core 0.1.2 → 2.0.0

package/dist/index.cjs

@@ -21,11 +21,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   KIND_MAP: () => KIND_MAP,
+  aisdkTelemetry: () => aisdkTelemetry,
   createSpanReplayer: () => createSpanReplayer,
   deriveRootSpanId: () => deriveRootSpanId,
   deriveTraceId: () => deriveTraceId,
   replayerExporter: () => replayerExporter,
-  toOtelAttributes: () => toOtelAttributes
+  toOtelAttributes: () => toOtelAttributes,
+  withEmbeddingSpan: () => withEmbeddingSpan
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -135,12 +137,48 @@ function replayerExporter(opts) {
   const replayer = createSpanReplayer(opts);
   return { export: (spans) => replayer.replay(spans) };
 }
+
+// src/aisdk.ts
+var import_api3 = require("@opentelemetry/api");
+var import_incubating2 = require("@opentelemetry/semantic-conventions/incubating");
+function aisdkTelemetry(opts) {
+  return {
+    isEnabled: true,
+    functionId: opts.functionId,
+    ...opts.metadata ? { metadata: opts.metadata } : {},
+    recordInputs: opts.recordInputs ?? false,
+    recordOutputs: opts.recordOutputs ?? false
+  };
+}
+async function withEmbeddingSpan(opts, fn) {
+  const tracer = opts.tracer ?? import_api3.trace.getTracer("nightowls");
+  return tracer.startActiveSpan(opts.functionId, async (span) => {
+    const attrs = { "nightowls.span.kind": "embedding", [import_incubating2.ATTR_GEN_AI_REQUEST_MODEL]: opts.model, "gen_ai.operation.name": "embeddings" };
+    if (typeof opts.count === "number") attrs["gen_ai.request.embedding.count"] = opts.count;
+    for (const [k, v] of Object.entries(opts.metadata ?? {})) attrs[k] = v;
+    span.setAttributes(attrs);
+    try {
+      const out = await fn();
+      const tokens = opts.tokens ?? out?.usage?.tokens;
+      if (typeof tokens === "number") span.setAttribute(import_incubating2.ATTR_GEN_AI_USAGE_INPUT_TOKENS, tokens);
+      span.setStatus({ code: import_api3.SpanStatusCode.OK });
+      return out;
+    } catch (err) {
+      span.setStatus({ code: import_api3.SpanStatusCode.ERROR, message: err instanceof Error ? err.message : String(err) });
+      throw err;
+    } finally {
+      span.end();
+    }
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   KIND_MAP,
+  aisdkTelemetry,
   createSpanReplayer,
   deriveRootSpanId,
   deriveTraceId,
   replayerExporter,
-  toOtelAttributes
+  toOtelAttributes,
+  withEmbeddingSpan
 });

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { SpanExporter, SpanProcessor } from '@opentelemetry/sdk-trace-base';
 import { SwarmSpan, TelemetryExporter } from '@nightowlsdev/core';
-import { SpanKind, Attributes } from '@opentelemetry/api';
+import { SpanKind, Attributes, Tracer } from '@opentelemetry/api';
 
 interface SpanReplayerOpts {
     /** Provide a SpanExporter (telemetry-otel: OTLP) OR a full SpanProcessor (telemetry-langfuse). */
@@ -27,4 +27,59 @@ declare const KIND_MAP: Record<SwarmSpan["kind"], SpanKind>;
 /** Map a SwarmSpan's attributes to OTel attributes, lifting generation usage/model/cost to gen_ai.* semconv. */
 declare function toOtelAttributes(span: SwarmSpan): Attributes;
 
-export { KIND_MAP, type SpanReplayer, type SpanReplayerOpts, createSpanReplayer, deriveRootSpanId, deriveTraceId, replayerExporter, toOtelAttributes };
+/** The subset of the AI SDK's `experimental_telemetry` settings we produce (typed locally so this package keeps
+ *  ZERO dependency on `ai`). Assignable to `generateText`/`streamText`'s `experimental_telemetry` field. */
+interface AiSdkTelemetrySettings {
+    isEnabled: boolean;
+    functionId?: string;
+    metadata?: Record<string, string | number | boolean>;
+    recordInputs?: boolean;
+    recordOutputs?: boolean;
+}
+interface AiSdkTelemetryOpts {
+    /** A stable name for this call (the Langfuse generation name / OTel span functionId), e.g. "entity_extraction". */
+    functionId: string;
+    /** Arbitrary key/values attached to the span (trace correlation: userId, tenantId, jobId, …). */
+    metadata?: Record<string, string | number | boolean>;
+    /** Record prompt/response bodies on the span. Default false (privacy-safe — only metadata + usage). */
+    recordInputs?: boolean;
+    recordOutputs?: boolean;
+}
+/**
+ * FR-008 — produce `experimental_telemetry` settings for ANY `generateText`/`streamText`, engine-independent, so a
+ * non-swarm call lands in Langfuse/OTel with `gen_ai.*` + tokens + cost via the host's existing exporter.
+ *
+ * @example
+ *   await generateText({ model, prompt, experimental_telemetry: aisdkTelemetry({ functionId: "summarize" }) });
+ */
+declare function aisdkTelemetry(opts: AiSdkTelemetryOpts): AiSdkTelemetrySettings;
+interface EmbeddingSpanOpts {
+    /** A stable name for this embedding call, e.g. "embedding" (the OTel span name). */
+    functionId: string;
+    /** The embedding model id (lands on `gen_ai.request.model`). */
+    model: string;
+    /** Number of inputs embedded (lands on `gen_ai.usage.input_tokens` is NOT it — this is the value count). */
+    count?: number;
+    /** Token usage, if the caller can supply it (the AI SDK's `embedMany` returns `.usage.tokens`). */
+    tokens?: number;
+    /** Extra correlation attributes (userId, tenantId, …). */
+    metadata?: Record<string, string | number | boolean>;
+    /** Override the tracer (defaults to the global `nightowls` tracer the host's provider registered). */
+    tracer?: Tracer;
+}
+/**
+ * FR-008/FR-012 — wrap an EMBEDDING call (`embed`/`embedMany`) in an OTel `gen_ai.*` span, since the AI SDK's
+ * `experimental_telemetry` callbacks do NOT fire for embeddings. Records model + value count (+ token usage if the
+ * result exposes it). Forwards through the host's existing SpanProcessor. Re-throws after recording on error.
+ *
+ * @example
+ *   const res = await withEmbeddingSpan({ functionId: "embedding", model: "text-embedding-3-small", count: values.length },
+ *                                       () => embedMany({ model, values }));
+ */
+declare function withEmbeddingSpan<T extends {
+    usage?: {
+        tokens?: number;
+    };
+}>(opts: EmbeddingSpanOpts, fn: () => Promise<T>): Promise<T>;
+
+export { type AiSdkTelemetryOpts, type AiSdkTelemetrySettings, type EmbeddingSpanOpts, KIND_MAP, type SpanReplayer, type SpanReplayerOpts, aisdkTelemetry, createSpanReplayer, deriveRootSpanId, deriveTraceId, replayerExporter, toOtelAttributes, withEmbeddingSpan };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { SpanExporter, SpanProcessor } from '@opentelemetry/sdk-trace-base';
 import { SwarmSpan, TelemetryExporter } from '@nightowlsdev/core';
-import { SpanKind, Attributes } from '@opentelemetry/api';
+import { SpanKind, Attributes, Tracer } from '@opentelemetry/api';
 
 interface SpanReplayerOpts {
     /** Provide a SpanExporter (telemetry-otel: OTLP) OR a full SpanProcessor (telemetry-langfuse). */
@@ -27,4 +27,59 @@ declare const KIND_MAP: Record<SwarmSpan["kind"], SpanKind>;
 /** Map a SwarmSpan's attributes to OTel attributes, lifting generation usage/model/cost to gen_ai.* semconv. */
 declare function toOtelAttributes(span: SwarmSpan): Attributes;
 
-export { KIND_MAP, type SpanReplayer, type SpanReplayerOpts, createSpanReplayer, deriveRootSpanId, deriveTraceId, replayerExporter, toOtelAttributes };
+/** The subset of the AI SDK's `experimental_telemetry` settings we produce (typed locally so this package keeps
+ *  ZERO dependency on `ai`). Assignable to `generateText`/`streamText`'s `experimental_telemetry` field. */
+interface AiSdkTelemetrySettings {
+    isEnabled: boolean;
+    functionId?: string;
+    metadata?: Record<string, string | number | boolean>;
+    recordInputs?: boolean;
+    recordOutputs?: boolean;
+}
+interface AiSdkTelemetryOpts {
+    /** A stable name for this call (the Langfuse generation name / OTel span functionId), e.g. "entity_extraction". */
+    functionId: string;
+    /** Arbitrary key/values attached to the span (trace correlation: userId, tenantId, jobId, …). */
+    metadata?: Record<string, string | number | boolean>;
+    /** Record prompt/response bodies on the span. Default false (privacy-safe — only metadata + usage). */
+    recordInputs?: boolean;
+    recordOutputs?: boolean;
+}
+/**
+ * FR-008 — produce `experimental_telemetry` settings for ANY `generateText`/`streamText`, engine-independent, so a
+ * non-swarm call lands in Langfuse/OTel with `gen_ai.*` + tokens + cost via the host's existing exporter.
+ *
+ * @example
+ *   await generateText({ model, prompt, experimental_telemetry: aisdkTelemetry({ functionId: "summarize" }) });
+ */
+declare function aisdkTelemetry(opts: AiSdkTelemetryOpts): AiSdkTelemetrySettings;
+interface EmbeddingSpanOpts {
+    /** A stable name for this embedding call, e.g. "embedding" (the OTel span name). */
+    functionId: string;
+    /** The embedding model id (lands on `gen_ai.request.model`). */
+    model: string;
+    /** Number of inputs embedded (lands on `gen_ai.usage.input_tokens` is NOT it — this is the value count). */
+    count?: number;
+    /** Token usage, if the caller can supply it (the AI SDK's `embedMany` returns `.usage.tokens`). */
+    tokens?: number;
+    /** Extra correlation attributes (userId, tenantId, …). */
+    metadata?: Record<string, string | number | boolean>;
+    /** Override the tracer (defaults to the global `nightowls` tracer the host's provider registered). */
+    tracer?: Tracer;
+}
+/**
+ * FR-008/FR-012 — wrap an EMBEDDING call (`embed`/`embedMany`) in an OTel `gen_ai.*` span, since the AI SDK's
+ * `experimental_telemetry` callbacks do NOT fire for embeddings. Records model + value count (+ token usage if the
+ * result exposes it). Forwards through the host's existing SpanProcessor. Re-throws after recording on error.
+ *
+ * @example
+ *   const res = await withEmbeddingSpan({ functionId: "embedding", model: "text-embedding-3-small", count: values.length },
+ *                                       () => embedMany({ model, values }));
+ */
+declare function withEmbeddingSpan<T extends {
+    usage?: {
+        tokens?: number;
+    };
+}>(opts: EmbeddingSpanOpts, fn: () => Promise<T>): Promise<T>;
+
+export { type AiSdkTelemetryOpts, type AiSdkTelemetrySettings, type EmbeddingSpanOpts, KIND_MAP, type SpanReplayer, type SpanReplayerOpts, aisdkTelemetry, createSpanReplayer, deriveRootSpanId, deriveTraceId, replayerExporter, toOtelAttributes, withEmbeddingSpan };

package/dist/index.js

@@ -111,11 +111,50 @@ function replayerExporter(opts) {
   const replayer = createSpanReplayer(opts);
   return { export: (spans) => replayer.replay(spans) };
 }
+
+// src/aisdk.ts
+import { trace as trace2, SpanStatusCode } from "@opentelemetry/api";
+import {
+  ATTR_GEN_AI_REQUEST_MODEL as ATTR_GEN_AI_REQUEST_MODEL2,
+  ATTR_GEN_AI_USAGE_INPUT_TOKENS as ATTR_GEN_AI_USAGE_INPUT_TOKENS2
+} from "@opentelemetry/semantic-conventions/incubating";
+function aisdkTelemetry(opts) {
+  return {
+    isEnabled: true,
+    functionId: opts.functionId,
+    ...opts.metadata ? { metadata: opts.metadata } : {},
+    recordInputs: opts.recordInputs ?? false,
+    recordOutputs: opts.recordOutputs ?? false
+  };
+}
+async function withEmbeddingSpan(opts, fn) {
+  const tracer = opts.tracer ?? trace2.getTracer("nightowls");
+  return tracer.startActiveSpan(opts.functionId, async (span) => {
+    const attrs = { "nightowls.span.kind": "embedding", [ATTR_GEN_AI_REQUEST_MODEL2]: opts.model, "gen_ai.operation.name": "embeddings" };
+    if (typeof opts.count === "number") attrs["gen_ai.request.embedding.count"] = opts.count;
+    for (const [k, v] of Object.entries(opts.metadata ?? {})) attrs[k] = v;
+    span.setAttributes(attrs);
+    try {
+      const out = await fn();
+      const tokens = opts.tokens ?? out?.usage?.tokens;
+      if (typeof tokens === "number") span.setAttribute(ATTR_GEN_AI_USAGE_INPUT_TOKENS2, tokens);
+      span.setStatus({ code: SpanStatusCode.OK });
+      return out;
+    } catch (err) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: err instanceof Error ? err.message : String(err) });
+      throw err;
+    } finally {
+      span.end();
+    }
+  });
+}
 export {
   KIND_MAP,
+  aisdkTelemetry,
   createSpanReplayer,
   deriveRootSpanId,
   deriveTraceId,
   replayerExporter,
-  toOtelAttributes
+  toOtelAttributes,
+  withEmbeddingSpan
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightowlsdev/telemetry-core",
-  "version": "0.1.2",
+  "version": "2.0.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -34,16 +34,16 @@
     "@opentelemetry/semantic-conventions": "^1.36.0"
   },
   "peerDependencies": {
-    "@nightowlsdev/core": "0.3.0"
+    "@nightowlsdev/core": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^24.12.4",
     "tsup": "8.5.1",
     "typescript": "6.0.3",
     "vitest": "^3.2.0",
-    "@nightowlsdev/core": "0.3.0",
-    "@nightowlsdev/tsconfig": "0.0.0",
-    "@nightowlsdev/eslint-config": "0.0.0"
+    "@nightowlsdev/core": "0.5.0",
+    "@nightowlsdev/eslint-config": "0.0.0",
+    "@nightowlsdev/tsconfig": "0.0.0"
   },
   "scripts": {
     "build": "tsup",