weflayr 0.20.5 → 0.21.0

package/src/instrumentation/openai/get_cache_and_reasoning_telemetry.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * Cached-prompt token enrichment complement for the non-streamed OpenAI chat path.
+ *
+ * `@traceloop/instrumentation-openai` records `gen_ai.usage.{input,output}_tokens`
+ * for non-streamed calls but never reads `usage.prompt_tokens_details.cached_tokens`,
+ * so spans for prompt-cache hits carry no cached-token count. The Python
+ * OpenLLMetry instrumentor sets `gen_ai.usage.cache_read_input_tokens` from that
+ * field, so this brings the Node SDK to parity.
+ *
+ * It wraps the instrumentor instance's `_endSpan({ span, type, result })`, which
+ * finalizes the span after the response resolves, letting us stamp the
+ * cached-token count off `result.usage` while the span is still open. OpenAI has
+ * no separate cache-write count, so only `cache_read_input_tokens` is set.
+ *
+ * The same hook surfaces the reasoning-token count: reasoning models report it as
+ * `usage.completion_tokens_details.reasoning_tokens` (a subset of output_tokens)
+ * which the Node instrumentor drops, so this stamps the flat `reasoning_tokens`
+ * attribute (the form the Python instrumentor emits and the normalizer reads).
+ */
+
+const CACHE_READ_INPUT_TOKENS_ATTR = 'gen_ai.usage.cache_read_input_tokens';
+const REASONING_TOKENS_ATTR = 'gen_ai.usage.reasoning_tokens';
+
+class OpenAIPromptCachingInstrumentor {
+  constructor() {
+    // [instrumentation, methodName, originalFunction] for uninstrument().
+    this._patched = [];
+  }
+
+  // No-op (and never throws) if the instrumentor's internals have changed shape —
+  // the worst case is a missing cached-token count, never a crash.
+  instrument(instrumentation) {
+    const original = instrumentation && instrumentation._endSpan;
+    if (typeof original !== 'function') return;
+
+    instrumentation._endSpan = function endSpanWithCache(args) {
+      try {
+        const span = args && args.span;
+        const usage = args && args.result && args.result.usage;
+        const recording = span && span.isRecording && span.isRecording();
+        const cachedTokens =
+          usage && usage.prompt_tokens_details && usage.prompt_tokens_details.cached_tokens;
+        if (cachedTokens && recording) {
+          span.setAttribute(CACHE_READ_INPUT_TOKENS_ATTR, cachedTokens);
+        }
+        const reasoningTokens =
+          usage &&
+          usage.completion_tokens_details &&
+          usage.completion_tokens_details.reasoning_tokens;
+        if (reasoningTokens && recording) {
+          span.setAttribute(REASONING_TOKENS_ATTR, reasoningTokens);
+        }
+      } catch {
+        // Never break span finalization over an enrichment failure.
+      }
+      return original.call(this, args);
+    };
+    this._patched.push([instrumentation, '_endSpan', original]);
+  }
+
+  uninstrument() {
+    for (const [owner, methodName, original] of this._patched) {
+      owner[methodName] = original;
+    }
+    this._patched = [];
+  }
+}
+
+module.exports = { OpenAIPromptCachingInstrumentor };

package/src/instrumentation/openai/get_embeddings_telemetry.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Hand-written OTel instrumentor for the OpenAI embeddings endpoint.
+ *
+ * `@traceloop/instrumentation-openai` (the package weflayr uses for OpenAI on
+ * Node) does not wrap the embeddings endpoint, so this ships inside weflayr to
+ * cover it. The Python SDK gets embeddings for free from OpenLLMetry's
+ * instrumentor, so there is no Python counterpart to this file — but the span it
+ * emits is shaped to normalize identically. It is registered alongside the
+ * traceloop instrumentor whenever `autoInstrument({ aiSdks: 'openai' })` runs.
+ *
+ * Embeddings are billed per input token, so the span records the prompt tokens
+ * read off the response under `gen_ai.usage.input_tokens`; there is no completion.
+ */
+
+const { trace, SpanStatusCode } = require('@opentelemetry/api');
+
+const TRACER_NAME = 'weflayr.instrumentation.openai_embeddings';
+const EMBEDDINGS_OPERATION = 'embeddings';
+
+// Return the gen_ai.system for this call, matching how the OpenAI chat
+// instrumentor attributes the vendor: Azure clients (reached via the same openai
+// SDK) report `azure.ai.openai`, everything else `openai`.
+function _detectSystem(instance) {
+  const baseURL = (instance && instance._client && instance._client.baseURL) || '';
+  return baseURL.toLowerCase().includes('openai.azure.com') ? 'azure.ai.openai' : 'openai';
+}
+
+function _recordError(span, error) {
+  span.setStatus({ code: SpanStatusCode.ERROR, message: error?.message ?? String(error) });
+  span.recordException(error);
+}
+
+class OpenAIEmbeddingsInstrumentor {
+  constructor() {
+    // [ownerPrototype, methodName, originalFunction] for uninstrument().
+    this._patched = [];
+  }
+
+  instrument() {
+    let Embeddings;
+    try {
+      ({ Embeddings } = require('openai/resources/embeddings'));
+    } catch (err) {
+      throw new Error(
+        'weflayr.autoInstrument(OPENAI): the openai client is not installed. ' +
+          'Install it with: npm install openai\n' +
+          `Underlying error: ${err.message}`
+      );
+    }
+
+    const owner = Embeddings.prototype;
+    const original = owner.create;
+
+    function wrapper(body, ...rest) {
+      const span = trace.getTracer(TRACER_NAME).startSpan(EMBEDDINGS_OPERATION);
+      span.setAttribute('gen_ai.system', _detectSystem(this));
+      span.setAttribute('gen_ai.operation.name', EMBEDDINGS_OPERATION);
+      if (body && body.model) {
+        span.setAttribute('gen_ai.request.model', body.model);
+      }
+      return Promise.resolve(original.call(this, body, ...rest)).then(
+        (response) => {
+          if (response && response.model) {
+            span.setAttribute('gen_ai.response.model', response.model);
+          }
+          const promptTokens = response && response.usage && response.usage.prompt_tokens;
+          if (promptTokens != null) {
+            span.setAttribute('gen_ai.usage.input_tokens', promptTokens);
+          }
+          span.end();
+          return response;
+        },
+        (error) => {
+          _recordError(span, error);
+          span.end();
+          throw error;
+        }
+      );
+    }
+
+    owner.create = wrapper;
+    this._patched.push([owner, 'create', original]);
+  }
+
+  uninstrument() {
+    for (const [owner, methodName, original] of this._patched) {
+      owner[methodName] = original;
+    }
+    this._patched = [];
+  }
+}
+
+module.exports = { OpenAIEmbeddingsInstrumentor };

package/src/instrumentation/openai/get_streaming_usage.js

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+ * Streamed token-usage enrichment complement for the OpenAI chat path.
+ *
+ * `@traceloop/instrumentation-openai` does not record token usage for streamed
+ * calls: its stream handler accumulates `choices[].delta` but never reads the
+ * final usage chunk OpenAI sends when the request sets
+ * `stream_options: { include_usage: true }`. Non-streaming calls work because
+ * OpenAI returns `usage` in the response body, which the instrumentor reads
+ * directly. The Python OpenLLMetry instrumentor reads the streamed usage, so
+ * this gap is Node-only.
+ *
+ * It wraps the instrumentor instance's `_streamingWrapPromise`: that handler
+ * hands us the span and ends it only after its chunk loop, so when the usage
+ * chunk arrives the span is still open and we set the same `gen_ai.usage.*`
+ * attributes the instrumentor sets for non-streaming calls.
+ */
+
+const USAGE_INPUT_TOKENS_ATTR = 'gen_ai.usage.input_tokens';
+const USAGE_OUTPUT_TOKENS_ATTR = 'gen_ai.usage.output_tokens';
+const USAGE_TOTAL_TOKENS_ATTR = 'gen_ai.usage.total_tokens';
+const CACHE_READ_INPUT_TOKENS_ATTR = 'gen_ai.usage.cache_read_input_tokens';
+
+function _setUsageAttributes(span, usage) {
+  if (typeof usage.prompt_tokens === 'number') {
+    span.setAttribute(USAGE_INPUT_TOKENS_ATTR, usage.prompt_tokens);
+  }
+  if (typeof usage.completion_tokens === 'number') {
+    span.setAttribute(USAGE_OUTPUT_TOKENS_ATTR, usage.completion_tokens);
+  }
+  if (typeof usage.total_tokens === 'number') {
+    span.setAttribute(USAGE_TOTAL_TOKENS_ATTR, usage.total_tokens);
+  }
+  // Cached-prompt tokens ride in the same streamed usage chunk; mirror the
+  // non-streamed cache backfill in get_cache_and_reasoning_telemetry.js.
+  const cachedTokens = usage.prompt_tokens_details && usage.prompt_tokens_details.cached_tokens;
+  if (cachedTokens) {
+    span.setAttribute(CACHE_READ_INPUT_TOKENS_ATTR, cachedTokens);
+  }
+}
+
+class OpenAIStreamingUsageInstrumentor {
+  constructor() {
+    // [instrumentation, methodName, originalFunction] for uninstrument().
+    this._patched = [];
+  }
+
+  // No-op if the instrumentor's internals have changed shape — the worst case is
+  // streamed spans without token counts, never a crash.
+  instrument(instrumentation) {
+    const original = instrumentation && instrumentation._streamingWrapPromise;
+    if (typeof original !== 'function') return;
+
+    instrumentation._streamingWrapPromise = function streamingWrapWithUsage(streamArgs) {
+      const span = streamArgs && streamArgs.span;
+      const wrappedStream = original.call(this, streamArgs);
+      if (!span) return wrappedStream;
+
+      return (async function* backfillUsage() {
+        for await (const chunk of wrappedStream) {
+          const usage = chunk && chunk.usage;
+          if (usage && span.isRecording()) {
+            _setUsageAttributes(span, usage);
+          }
+          yield chunk;
+        }
+      })();
+    };
+    this._patched.push([instrumentation, '_streamingWrapPromise', original]);
+  }
+
+  uninstrument() {
+    for (const [owner, methodName, original] of this._patched) {
+      owner[methodName] = original;
+    }
+    this._patched = [];
+  }
+}
+
+module.exports = { OpenAIStreamingUsageInstrumentor };

package/src/instrumentation/openai/set_telemetry_attributes.js

@@ -0,0 +1,39 @@
+'use strict';
+
+/**
+ * OpenAI telemetry complement — the registered orchestrator.
+ *
+ * Wires every weflayr-supplied patch the traceloop OpenAI instrumentor misses:
+ *   - the audio (TTS/STT) and embeddings endpoints it doesn't cover, and
+ *   - usage it drops on the chat endpoint it does cover: streamed token usage and
+ *     non-streamed cached-prompt tokens (these enrich the traceloop instrumentor
+ *     instance, hence the `instrumentation` argument).
+ */
+
+const { OpenAIAudioInstrumentor } = require('./get_audio_telemetry');
+const { OpenAIEmbeddingsInstrumentor } = require('./get_embeddings_telemetry');
+const { OpenAIStreamingUsageInstrumentor } = require('./get_streaming_usage');
+const { OpenAIPromptCachingInstrumentor } = require('./get_cache_and_reasoning_telemetry');
+
+class OpenAITelemetryInstrumentor {
+  constructor() {
+    this._subInstrumentors = [
+      new OpenAIAudioInstrumentor(),
+      new OpenAIEmbeddingsInstrumentor(),
+      new OpenAIStreamingUsageInstrumentor(),
+      new OpenAIPromptCachingInstrumentor(),
+    ];
+  }
+
+  // The endpoint complements ignore `instrumentation`; the streaming/cache ones
+  // patch its internal handlers.
+  instrument(instrumentation) {
+    for (const sub of this._subInstrumentors) sub.instrument(instrumentation);
+  }
+
+  uninstrument() {
+    for (const sub of this._subInstrumentors) sub.uninstrument();
+  }
+}
+
+module.exports = { OpenAITelemetryInstrumentor };

package/src/otel/propagation.js

@@ -62,6 +62,11 @@ function _buildAttributes({ featureName, customerId, providerName, extraTags, sp
  * propagateMetadata call" contract.
  */
 function propagateMetadata(options, fn) {
+  const { featureName, customerId } = options ?? {};
+  if (featureName == null || customerId == null) {
+    throw new Error('propagateMetadata: `featureName` and `customerId` are required');
+  }
+
   if (typeof fn === 'function') {
     return _runWithMetadata(options, fn);
   }

package/src/otel/span-filter.js

@@ -27,17 +27,13 @@ const KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES = [
   'opentelemetry.instrumentation.google_generativeai',
   'opentelemetry.instrumentation.openai',
   'opentelemetry.instrumentation.openai_v2',
-  'opentelemetry.instrumentation.vertex_ai',
-  'opentelemetry.instrumentation.vertexai',
+  'weflayr.instrumentation.elevenlabs',
   'strands-agents',
   'vllm',
   '@traceloop/instrumentation-openai',
   '@traceloop/instrumentation-anthropic',
   '@traceloop/instrumentation-bedrock',
-  '@traceloop/instrumentation-azure',
   '@traceloop/instrumentation-cohere',
-  '@traceloop/instrumentation-together',
-  '@traceloop/instrumentation-vertexai',
   '@traceloop/instrumentation-google-generativeai',
   '@traceloop/instrumentation-langchain',
   '@traceloop/instrumentation-llamaindex',

package/tests/index.test.js

@@ -14,7 +14,6 @@ const { _state } = require('../src/setup');
 const { isDefaultExportSpan } = require('../src/otel/span-filter');
 const { WeflayrSpanProcessor } = require('../src/otel/span-processor');
 const { buildExporter, _exportWithRetry } = require('../src/otel/exporter');
-const { patchOpenAIStreamingUsage } = require('../src/otel/openai-streaming-usage');
 
 const contextManager = new AsyncHooksContextManager();
 contextManager.enable();
@@ -478,12 +477,48 @@ test('propagateMetadata providerName writes attribute', async () => {
   await provider.shutdown();
 });
 
+test('propagateMetadata requires featureName and customerId', () => {
+  assert.throws(() => weflayr.propagateMetadata({}), /featureName.*customerId.*required/);
+  assert.throws(() => weflayr.propagateMetadata({ featureName: 'f' }), /required/);
+  assert.throws(() => weflayr.propagateMetadata({ customerId: 'c' }), /required/);
+});
+
 // ── autoInstrument ────────────────────────────────────────────────────────────
 
 function _ensureSetupDone() {
   if (!_state.processor) weflayr.setup({ apiKey: 'test-key' });
 }
 
+// Instrumenting OPENAI also runs the bundled audio + embeddings instrumentors,
+// which eagerly require the openai resource modules. Stub them so autoInstrument
+// tests don't need the real `openai` dependency installed.
+const OPENAI_RESOURCE_STUBS = {
+  'openai/resources/audio/speech': {
+    Speech: class {
+      create() {}
+    },
+  },
+  'openai/resources/audio/transcriptions': {
+    Transcriptions: class {
+      create() {}
+    },
+  },
+  'openai/resources/embeddings': {
+    Embeddings: class {
+      create() {}
+    },
+  },
+};
+
+function _stubOpenAIResources() {
+  for (const [id, exports] of Object.entries(OPENAI_RESOURCE_STUBS)) {
+    require.cache[id] = { id, filename: id, loaded: true, exports };
+  }
+  return () => {
+    for (const id of Object.keys(OPENAI_RESOURCE_STUBS)) delete require.cache[id];
+  };
+}
+
 test('autoInstrument throws "install package X" when the dep is missing', async () => {
   _ensureSetupDone();
   await assert.rejects(
@@ -517,7 +552,7 @@ test('autoInstrument loads a stubbed Traceloop package', async () => {
   }
   const origResolve = Module._resolveFilename;
   Module._resolveFilename = function patched(req, ...rest) {
-    if (req === '@traceloop/instrumentation-openai') return req;
+    if (req === '@traceloop/instrumentation-openai' || req in OPENAI_RESOURCE_STUBS) return req;
     return origResolve.call(this, req, ...rest);
   };
   require.cache['@traceloop/instrumentation-openai'] = {
@@ -526,12 +561,14 @@ test('autoInstrument loads a stubbed Traceloop package', async () => {
     loaded: true,
     exports: { OpenAIInstrumentation: FakeOpenAIInstrumentation },
   };
+  const cleanupOpenAI = _stubOpenAIResources();
   try {
     await weflayr.autoInstrument({ aiSdks: weflayr.AiSdk.OPENAI });
     assert.equal(constructed, true);
   } finally {
     Module._resolveFilename = origResolve;
     delete require.cache['@traceloop/instrumentation-openai'];
+    cleanupOpenAI();
   }
 });
 
@@ -564,7 +601,7 @@ test('autoInstrument runs setup when apiKey passed', async () => {
   }
   const origResolve = Module._resolveFilename;
   Module._resolveFilename = function patched(req, ...rest) {
-    if (req === '@traceloop/instrumentation-openai') return req;
+    if (req === '@traceloop/instrumentation-openai' || req in OPENAI_RESOURCE_STUBS) return req;
     return origResolve.call(this, req, ...rest);
   };
   require.cache['@traceloop/instrumentation-openai'] = {
@@ -573,6 +610,7 @@ test('autoInstrument runs setup when apiKey passed', async () => {
     loaded: true,
     exports: { OpenAIInstrumentation: FakeOpenAIInstrumentation },
   };
+  const cleanupOpenAI = _stubOpenAIResources();
   try {
     await weflayr.autoInstrument({
       aiSdks: weflayr.AiSdk.OPENAI,
@@ -582,6 +620,7 @@ test('autoInstrument runs setup when apiKey passed', async () => {
   } finally {
     Module._resolveFilename = origResolve;
     delete require.cache['@traceloop/instrumentation-openai'];
+    cleanupOpenAI();
   }
 });
 
@@ -641,47 +680,6 @@ test('exporter gives up after maxRetries on persistent 503', async () => {
   assert.equal(calls, 3);
 });
 
-// ── OpenAI streaming usage backfill ─────────────────────────────────────────────
-
-// Build a fake OpenAI instrumentor whose streaming handler mimics traceloop's:
-// it yields content chunks, then a final usage chunk (as OpenAI sends when
-// `stream_options.include_usage` is set) without recording usage itself. The
-// patch should read the usage chunk and set the token attributes on the span.
-function makeFakeOpenAIInstrumentation() {
-  return {
-    _streamingWrapPromise() {
-      return (async function* originalStream() {
-        yield { id: 'chatcmpl-1', model: 'gpt-4o-mini', choices: [{ delta: { content: 'Hi' } }] };
-        yield {
-          id: 'chatcmpl-1',
-          model: 'gpt-4o-mini',
-          choices: [],
-          usage: { prompt_tokens: 13, completion_tokens: 2, total_tokens: 15 },
-        };
-      })();
-    },
-  };
-}
-
-test('patchOpenAIStreamingUsage sets token attributes from the streamed usage chunk', async () => {
-  const span = makeFakeSpan();
-  const instrumentation = makeFakeOpenAIInstrumentation();
-  patchOpenAIStreamingUsage(instrumentation);
-
-  const stream = instrumentation._streamingWrapPromise({ span });
-  for await (const chunk of stream) void chunk;
-
-  assert.equal(span.attributes['gen_ai.usage.input_tokens'], 13);
-  assert.equal(span.attributes['gen_ai.usage.output_tokens'], 2);
-  assert.equal(span.attributes['gen_ai.usage.total_tokens'], 15);
-});
-
-test('patchOpenAIStreamingUsage is a no-op when the streaming handler is absent', () => {
-  const instrumentation = {};
-  patchOpenAIStreamingUsage(instrumentation);
-  assert.equal(instrumentation._streamingWrapPromise, undefined);
-});
-
 // ── flush ─────────────────────────────────────────────────────────────────────
 
 test('flush does not throw', async () => {

package/tests/instrumentation/anthropic/get_cache_and_reasoning_telemetry.test.js

@@ -0,0 +1,125 @@
+'use strict';
+
+// Tests for the Anthropic cached-prompt token complement. It wraps the primary
+// instrumentor's `_endSpan({ span, type, result })` to stamp
+// gen_ai.usage.cache_read_input_tokens / cache_creation_input_tokens from the
+// response's `usage.cache_read_input_tokens` / `cache_creation_input_tokens`.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  AnthropicPromptCachingInstrumentor,
+} = require('../../../src/instrumentation/anthropic/get_cache_and_reasoning_telemetry');
+
+function fakeSpan() {
+  const attrs = {};
+  return {
+    attrs,
+    isRecording: () => true,
+    setAttribute(key, value) {
+      attrs[key] = value;
+    },
+  };
+}
+
+test('stamps cache write and still calls the original _endSpan', () => {
+  const calls = [];
+  const instrumentation = {
+    _endSpan(args) {
+      calls.push(args);
+    },
+  };
+  new AnthropicPromptCachingInstrumentor().instrument(instrumentation);
+
+  const span = fakeSpan();
+  instrumentation._endSpan({
+    span,
+    type: 'completion',
+    result: {
+      usage: { input_tokens: 10, cache_creation_input_tokens: 5269, cache_read_input_tokens: 0 },
+    },
+  });
+
+  assert.equal(span.attrs['gen_ai.usage.cache_creation_input_tokens'], 5269);
+  assert.equal(span.attrs['gen_ai.usage.cache_read_input_tokens'], undefined);
+  assert.equal(calls.length, 1);
+});
+
+test('stamps cache read on a warm call', () => {
+  const instrumentation = { _endSpan() {} };
+  new AnthropicPromptCachingInstrumentor().instrument(instrumentation);
+
+  const span = fakeSpan();
+  instrumentation._endSpan({
+    span,
+    type: 'completion',
+    result: {
+      usage: { input_tokens: 10, cache_creation_input_tokens: 0, cache_read_input_tokens: 5271 },
+    },
+  });
+
+  assert.equal(span.attrs['gen_ai.usage.cache_read_input_tokens'], 5271);
+  assert.equal(span.attrs['gen_ai.usage.cache_creation_input_tokens'], undefined);
+});
+
+test('sets nothing for an uncached call', () => {
+  const instrumentation = { _endSpan() {} };
+  new AnthropicPromptCachingInstrumentor().instrument(instrumentation);
+
+  const span = fakeSpan();
+  instrumentation._endSpan({ span, type: 'completion', result: { usage: { input_tokens: 13 } } });
+
+  assert.equal(span.attrs['gen_ai.usage.cache_read_input_tokens'], undefined);
+  assert.equal(span.attrs['gen_ai.usage.cache_creation_input_tokens'], undefined);
+});
+
+test('stamps extended thinking tokens from output_tokens_details', () => {
+  const instrumentation = { _endSpan() {} };
+  new AnthropicPromptCachingInstrumentor().instrument(instrumentation);
+
+  const span = fakeSpan();
+  instrumentation._endSpan({
+    span,
+    type: 'completion',
+    result: { usage: { input_tokens: 10, output_tokens_details: { thinking_tokens: 150 } } },
+  });
+
+  assert.equal(span.attrs['gen_ai.usage.output_tokens_details.thinking_tokens'], 150);
+});
+
+test('stamps cache + raw input from the streamed message_start usage', async () => {
+  const instrumentation = {
+    _endSpan() {},
+    _streamingWrapPromise() {
+      return (async function* () {
+        yield {
+          type: 'message_start',
+          message: {
+            usage: {
+              input_tokens: 10,
+              cache_read_input_tokens: 5270,
+              cache_creation_input_tokens: 0,
+            },
+          },
+        };
+        yield { type: 'content_block_delta', delta: { text: 'OK' } };
+      })();
+    },
+  };
+  new AnthropicPromptCachingInstrumentor().instrument(instrumentation);
+
+  const span = fakeSpan();
+  for await (const _chunk of instrumentation._streamingWrapPromise('client', 'mod', { span })) {
+    void _chunk;
+  }
+
+  assert.equal(span.attrs['gen_ai.usage.cache_read_input_tokens'], 5270);
+  assert.equal(span.attrs['gen_ai.usage.input_tokens'], 10);
+});
+
+test('is a no-op when the instrumentor has no _endSpan', () => {
+  const instrumentation = {};
+  new AnthropicPromptCachingInstrumentor().instrument(instrumentation);
+  assert.equal(instrumentation._endSpan, undefined);
+});