weflayr 0.20.5 → 0.20.6

package/index.d.ts

@@ -38,6 +38,7 @@ export const AiSdk: {
   readonly TOGETHER: 'together';
   readonly GOOGLE_VERTEX: 'google-vertex';
   readonly GOOGLE_GENAI: 'google-genai';
+  readonly ELEVENLABS: 'elevenlabs';
 };
 export type AiSdk = (typeof AiSdk)[keyof typeof AiSdk];
 
@@ -55,6 +56,7 @@ export const AIProviderName: {
   readonly TOGETHER: 'together';
   readonly GOOGLE_VERTEX: 'google-vertex';
   readonly GOOGLE_GENAI: 'google-genai';
+  readonly ELEVENLABS: 'elevenlabs';
   readonly VERCEL_AI_GATEWAY: 'vercel_ai_gateway';
 };
 export type AIProviderName = (typeof AIProviderName)[keyof typeof AIProviderName];

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "weflayr",
-  "version": "0.20.5",
+  "version": "0.20.6",
   "description": "Weflayr Node.js SDK — instrument any LLM client via JS Proxy",
   "main": "src/index.js",
   "types": "index.d.ts",
   "scripts": {
-    "test": "node --test tests/index.test.js",
+    "test": "node --test tests/index.test.js tests/instrumentation/elevenlabs.test.js",
     "lint": "eslint src tests",
     "lint:fix": "eslint src tests --fix",
     "format": "prettier --write src tests",

package/src/auto-instrument.js

@@ -15,6 +15,7 @@ const AiSdk = Object.freeze({
   TOGETHER: 'together',
   GOOGLE_VERTEX: 'google-vertex',
   GOOGLE_GENAI: 'google-genai',
+  ELEVENLABS: 'elevenlabs',
 });
 
 // Allowed values for `propagateMetadata({ providerName })`: every SDK the
@@ -35,6 +36,7 @@ const REGISTRY = {
   [AiSdk.TOGETHER]: '@traceloop/instrumentation-together',
   [AiSdk.GOOGLE_VERTEX]: '@traceloop/instrumentation-vertexai',
   [AiSdk.GOOGLE_GENAI]: '@traceloop/instrumentation-google-generativeai',
+  [AiSdk.ELEVENLABS]: '@elevenlabs/elevenlabs-js',
 };
 
 const SETUP_OPTION_KEYS = [
@@ -65,6 +67,15 @@ async function _instrumentAiSdk(aiSdk) {
   }
   const pkg = REGISTRY[aiSdk];
 
+  if (aiSdk === AiSdk.ELEVENLABS) {
+    // ElevenLabs has no OTel/traceloop instrumentor, so
+    // use the hand-written one bundled with weflayr.
+    const { ElevenLabsInstrumentor } = require('./instrumentation/elevenlabs');
+    new ElevenLabsInstrumentor().instrument();
+    debug('autoInstrument: registered aiSdk=%s package=%s', aiSdk, pkg);
+    return;
+  }
+
   let instrumentationPkg;
   try {
     instrumentationPkg = require(pkg);

package/src/instrumentation/elevenlabs.js

@@ -0,0 +1,236 @@
+'use strict';
+
+/**
+ * Hand-written OTel instrumentor for the ElevenLabs audio clients.
+ *
+ * No official OpenTelemetry instrumentor exists for the ElevenLabs SDK (it's
+ * audio, not an LLM), so this ships inside weflayr. It wraps the Text-to-Speech
+ * and Speech-to-Text entrypoints to emit one `gen_ai.*` span per call, which
+ * flows through the standard span processor -> exporter with no new transport code.
+ *
+ * The billable unit differs by API, so each span records the one ElevenLabs bills:
+ *   - Text-to-Speech is billed per input character -> `gen_ai.usage.input_characters`.
+ *   - Speech-to-Text is billed per second of audio  -> `gen_ai.usage.input_seconds`.
+ *
+ * Entrypoints come in three result shapes, independent of which API they belong to:
+ *   - *byte stream* methods resolve to a `ReadableStream` of audio chunks;
+ *   - *object stream* methods resolve to an async-iterable of chunk objects;
+ *   - *unary* methods resolve to the full response.
+ * The HTTP request -- plus any error -- only happens while a stream is awaited
+ * and consumed, so the span is started eagerly (to capture the
+ * `propagateMetadata` context active at the call site) and ended once the result
+ * is exhausted (streams) or returned (unary), giving an `elapsed_ms` that covers
+ * the whole call. The per-second billable unit is read off the STT response.
+ */
+
+const { trace, SpanStatusCode } = require('@opentelemetry/api');
+
+const TRACER_NAME = 'weflayr.instrumentation.elevenlabs';
+const SYSTEM = 'elevenlabs';
+const TTS_OPERATION = 'text_to_speech';
+const STT_OPERATION = 'speech_to_text';
+
+function _startSpan(operation, request) {
+  const span = trace.getTracer(TRACER_NAME).startSpan(operation);
+  span.setAttribute('gen_ai.system', SYSTEM);
+  span.setAttribute('gen_ai.operation.name', operation);
+  // `modelId` lives on the request body passed to every audio entrypoint.
+  const modelId = request && request.modelId;
+  if (modelId) {
+    span.setAttribute('gen_ai.request.model', modelId);
+  }
+  return span;
+}
+
+function _setInputCharacters(span, request) {
+  // `text` lives on the request body of every TTS entrypoint; the billable unit
+  // is its length.
+  span.setAttribute('gen_ai.usage.input_characters', ((request && request.text) || '').length);
+}
+
+function _setAudioDuration(span, response) {
+  // The transcription response exposes the transcribed audio length in seconds.
+  const durationSecs = response && response.audioDurationSecs;
+  if (durationSecs != null) {
+    span.setAttribute('gen_ai.usage.input_seconds', durationSecs);
+  }
+}
+
+function _recordError(span, error) {
+  span.setStatus({ code: SpanStatusCode.ERROR, message: error?.message ?? String(error) });
+  span.recordException(error);
+}
+
+// Proxy a `ReadableStream` of audio bytes so the span ends -- and any error is
+// recorded -- once the whole stream has been consumed (or the consumer cancels).
+// The span ends exactly once across every exit path.
+function _consumeByteStream(span, responsePromise) {
+  let ended = false;
+  const end = () => {
+    if (ended) return;
+    ended = true;
+    span.end();
+  };
+
+  return responsePromise.then(
+    (audioStream) => {
+      const reader = audioStream.getReader();
+      return new ReadableStream({
+        async pull(controller) {
+          try {
+            const { done, value } = await reader.read();
+            if (done) {
+              end();
+              controller.close();
+              return;
+            }
+            controller.enqueue(value);
+          } catch (error) {
+            _recordError(span, error);
+            end();
+            controller.error(error);
+          }
+        },
+        cancel(reason) {
+          end();
+          return reader.cancel(reason);
+        },
+      });
+    },
+    (error) => {
+      _recordError(span, error);
+      end();
+      throw error;
+    }
+  );
+}
+
+// Proxy an async-iterable of chunk objects (the streaming "with timestamps"
+// variant) so the span ends once iteration completes.
+function _consumeObjectStream(span, responsePromise) {
+  async function* iterate(stream) {
+    try {
+      for await (const chunk of stream) {
+        yield chunk;
+      }
+    } catch (error) {
+      _recordError(span, error);
+      throw error;
+    } finally {
+      span.end();
+    }
+  }
+
+  return responsePromise.then(
+    (stream) => iterate(stream),
+    (error) => {
+      _recordError(span, error);
+      span.end();
+      throw error;
+    }
+  );
+}
+
+// Wrap a request/response entrypoint: the span spans the single call, and any
+// response-derived billable unit is read off the result.
+function _consumeUnary(span, responsePromise, setResponseAttributes) {
+  return responsePromise.then(
+    (response) => {
+      if (setResponseAttributes) {
+        setResponseAttributes(span, response);
+      }
+      span.end();
+      return response;
+    },
+    (error) => {
+      _recordError(span, error);
+      span.end();
+      throw error;
+    }
+  );
+}
+
+class ElevenLabsInstrumentor {
+  constructor() {
+    // [ownerPrototype, methodName, originalFunction] for uninstrument().
+    this._patched = [];
+  }
+
+  instrument() {
+    let TextToSpeechClient;
+    let SpeechToTextClient;
+    try {
+      ({
+        TextToSpeechClient,
+      } = require('@elevenlabs/elevenlabs-js/api/resources/textToSpeech/client/Client'));
+      ({
+        SpeechToTextClient,
+      } = require('@elevenlabs/elevenlabs-js/api/resources/speechToText/client/Client'));
+    } catch (err) {
+      throw new Error(
+        'weflayr.autoInstrument(ELEVENLABS): the @elevenlabs/elevenlabs-js client is not ' +
+          'installed. Install it with: npm install @elevenlabs/elevenlabs-js\n' +
+          `Underlying error: ${err.message}`
+      );
+    }
+
+    // TTS — request body is the 2nd arg (after voice_id); billed per character.
+    this._wrap(TextToSpeechClient.prototype, 'convert', {
+      operation: TTS_OPERATION,
+      requestArgIndex: 1,
+      setRequestAttributes: _setInputCharacters,
+      consume: _consumeByteStream,
+    });
+    this._wrap(TextToSpeechClient.prototype, 'stream', {
+      operation: TTS_OPERATION,
+      requestArgIndex: 1,
+      setRequestAttributes: _setInputCharacters,
+      consume: _consumeByteStream,
+    });
+    this._wrap(TextToSpeechClient.prototype, 'streamWithTimestamps', {
+      operation: TTS_OPERATION,
+      requestArgIndex: 1,
+      setRequestAttributes: _setInputCharacters,
+      consume: _consumeObjectStream,
+    });
+    this._wrap(TextToSpeechClient.prototype, 'convertWithTimestamps', {
+      operation: TTS_OPERATION,
+      requestArgIndex: 1,
+      setRequestAttributes: _setInputCharacters,
+      consume: (span, responsePromise) => _consumeUnary(span, responsePromise, null),
+    });
+
+    // STT — request body is the 1st arg; billed per second of audio.
+    this._wrap(SpeechToTextClient.prototype, 'convert', {
+      operation: STT_OPERATION,
+      requestArgIndex: 0,
+      setRequestAttributes: null,
+      consume: (span, responsePromise) => _consumeUnary(span, responsePromise, _setAudioDuration),
+    });
+  }
+
+  uninstrument() {
+    for (const [owner, methodName, original] of this._patched) {
+      owner[methodName] = original;
+    }
+    this._patched = [];
+  }
+
+  _wrap(owner, methodName, { operation, requestArgIndex, setRequestAttributes, consume }) {
+    const original = owner[methodName];
+
+    function wrapper(...args) {
+      const request = args[requestArgIndex];
+      const span = _startSpan(operation, request);
+      if (setRequestAttributes) {
+        setRequestAttributes(span, request);
+      }
+      return consume(span, original.apply(this, args));
+    }
+
+    owner[methodName] = wrapper;
+    this._patched.push([owner, methodName, original]);
+  }
+}
+
+module.exports = { ElevenLabsInstrumentor };

package/src/otel/span-filter.js

@@ -29,6 +29,7 @@ const KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES = [
   'opentelemetry.instrumentation.openai_v2',
   'opentelemetry.instrumentation.vertex_ai',
   'opentelemetry.instrumentation.vertexai',
+  'weflayr.instrumentation.elevenlabs',
   'strands-agents',
   'vllm',
   '@traceloop/instrumentation-openai',

package/tests/instrumentation/elevenlabs.test.js

@@ -0,0 +1,242 @@
+'use strict';
+
+// Tests for the bundled ElevenLabs audio instrumentor.
+//
+// The real `@elevenlabs/elevenlabs-js` clients are stubbed with methods that
+// mirror the SDK's shapes — the streaming TTS entrypoints (`convert` / `stream`)
+// resolve to a ReadableStream, `streamWithTimestamps` to an async-iterable, and
+// the unary `convertWithTimestamps` and Speech-to-Text `convert` to a response
+// object — so the instrumentor can be exercised without network access or the
+// dependency installed.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const Module = require('node:module');
+
+const { trace, SpanStatusCode } = require('@opentelemetry/api');
+const {
+  BasicTracerProvider,
+  InMemorySpanExporter,
+  SimpleSpanProcessor,
+} = require('@opentelemetry/sdk-trace-base');
+
+const { ElevenLabsInstrumentor } = require('../../src/instrumentation/elevenlabs');
+
+const TTS_CLIENT_MODULE = '@elevenlabs/elevenlabs-js/api/resources/textToSpeech/client/Client';
+const STT_CLIENT_MODULE = '@elevenlabs/elevenlabs-js/api/resources/speechToText/client/Client';
+
+// The instrumentor emits via the global tracer provider. node's test runner
+// isolates each test file in its own process, so registering one provider +
+// in-memory exporter for the whole file is safe.
+const exporter = new InMemorySpanExporter();
+trace.setGlobalTracerProvider(
+  new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] })
+);
+
+function readableOf(chunks) {
+  let index = 0;
+  return new ReadableStream({
+    pull(controller) {
+      if (index < chunks.length) controller.enqueue(chunks[index++]);
+      else controller.close();
+    },
+  });
+}
+
+function failingReadable(error) {
+  return new ReadableStream({
+    pull() {
+      throw error;
+    },
+  });
+}
+
+function asyncIterableOf(chunks) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (const chunk of chunks) yield chunk;
+    },
+  };
+}
+
+class StubTextToSpeechClient {
+  convert(_voiceId, request = {}) {
+    if (request.text === 'boom') return Promise.resolve(failingReadable(new Error('api error')));
+    return Promise.resolve(readableOf([Buffer.from('a'), Buffer.from('b')]));
+  }
+
+  stream(_voiceId, _request = {}) {
+    return Promise.resolve(readableOf([Buffer.from('x')]));
+  }
+
+  streamWithTimestamps(_voiceId, _request = {}) {
+    return Promise.resolve(asyncIterableOf([{ audioBase64: 'eA==' }]));
+  }
+
+  convertWithTimestamps(_voiceId, _request = {}) {
+    return Promise.resolve({ audioBase64: 'YQ==' });
+  }
+}
+
+class StubSpeechToTextClient {
+  convert(request = {}) {
+    if (request.modelId === 'boom') return Promise.reject(new Error('api error'));
+    return Promise.resolve({ audioDurationSecs: 12.4, text: 'hello' });
+  }
+}
+
+async function drain(stream) {
+  const reader = stream.getReader();
+  const chunks = [];
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+  }
+  return chunks;
+}
+
+async function drainIterable(iterable) {
+  const chunks = [];
+  for await (const chunk of iterable) chunks.push(chunk);
+  return chunks;
+}
+
+// Stub the elevenlabs client modules, install the instrumentor + the in-memory
+// exporter, and return a teardown that restores everything.
+function instrumented() {
+  const stubs = {
+    [TTS_CLIENT_MODULE]: { TextToSpeechClient: StubTextToSpeechClient },
+    [STT_CLIENT_MODULE]: { SpeechToTextClient: StubSpeechToTextClient },
+  };
+  const origResolve = Module._resolveFilename;
+  Module._resolveFilename = function patched(request, ...rest) {
+    if (request in stubs) return request;
+    return origResolve.call(this, request, ...rest);
+  };
+  for (const [moduleId, exports] of Object.entries(stubs)) {
+    require.cache[moduleId] = { id: moduleId, filename: moduleId, loaded: true, exports };
+  }
+
+  const instrumentor = new ElevenLabsInstrumentor();
+  instrumentor.instrument();
+
+  return () => {
+    instrumentor.uninstrument();
+    Module._resolveFilename = origResolve;
+    for (const moduleId of Object.keys(stubs)) delete require.cache[moduleId];
+    exporter.reset();
+  };
+}
+
+test('convert emits genai span with char count', async () => {
+  const teardown = instrumented();
+  try {
+    const client = new StubTextToSpeechClient();
+    const stream = await client.convert('voice', { text: 'hello world', modelId: 'eleven_v2' });
+    assert.deepEqual(await drain(stream), [Buffer.from('a'), Buffer.from('b')]);
+
+    const [span] = exporter.getFinishedSpans();
+    assert.equal(span.name, 'text_to_speech');
+    assert.equal(span.attributes['gen_ai.system'], 'elevenlabs');
+    assert.equal(span.attributes['gen_ai.operation.name'], 'text_to_speech');
+    assert.equal(span.attributes['gen_ai.request.model'], 'eleven_v2');
+    assert.equal(span.attributes['gen_ai.usage.input_characters'], 'hello world'.length);
+    assert.equal(span.status.code, SpanStatusCode.UNSET);
+  } finally {
+    teardown();
+  }
+});
+
+test('convert records error status on failure', async () => {
+  const teardown = instrumented();
+  try {
+    const client = new StubTextToSpeechClient();
+    const stream = await client.convert('voice', { text: 'boom', modelId: 'm' });
+    await assert.rejects(() => drain(stream), /api error/);
+
+    const [span] = exporter.getFinishedSpans();
+    assert.equal(span.status.code, SpanStatusCode.ERROR);
+  } finally {
+    teardown();
+  }
+});
+
+test('convert with timestamps emits span with char count', async () => {
+  const teardown = instrumented();
+  try {
+    const client = new StubTextToSpeechClient();
+    // The unary timestamp variant resolves to a single response, not a stream.
+    const result = await client.convertWithTimestamps('voice', { text: 'hello', modelId: 'm' });
+    assert.equal(result.audioBase64, 'YQ==');
+
+    const [span] = exporter.getFinishedSpans();
+    assert.equal(span.name, 'text_to_speech');
+    assert.equal(span.attributes['gen_ai.usage.input_characters'], 'hello'.length);
+    assert.equal(span.attributes['gen_ai.usage.input_seconds'], undefined);
+  } finally {
+    teardown();
+  }
+});
+
+test('stream with timestamps emits span with char count', async () => {
+  const teardown = instrumented();
+  try {
+    const client = new StubTextToSpeechClient();
+    const stream = await client.streamWithTimestamps('voice', { text: 'hello', modelId: 'm' });
+    assert.deepEqual(await drainIterable(stream), [{ audioBase64: 'eA==' }]);
+
+    const [span] = exporter.getFinishedSpans();
+    assert.equal(span.name, 'text_to_speech');
+    assert.equal(span.attributes['gen_ai.usage.input_characters'], 'hello'.length);
+  } finally {
+    teardown();
+  }
+});
+
+test('uninstrument restores original methods', async () => {
+  const teardown = instrumented();
+  try {
+    const client = new StubTextToSpeechClient();
+    assert.deepEqual(await drain(await client.stream('voice', { text: 'x' })), [Buffer.from('x')]);
+    assert.equal(exporter.getFinishedSpans().length, 1);
+  } finally {
+    teardown();
+  }
+});
+
+test('speech to text emits span with audio duration', async () => {
+  const teardown = instrumented();
+  try {
+    const client = new StubSpeechToTextClient();
+    const result = await client.convert({ modelId: 'scribe_v1', file: Buffer.from('audio') });
+    assert.equal(result.audioDurationSecs, 12.4);
+
+    const [span] = exporter.getFinishedSpans();
+    assert.equal(span.name, 'speech_to_text');
+    assert.equal(span.attributes['gen_ai.system'], 'elevenlabs');
+    assert.equal(span.attributes['gen_ai.operation.name'], 'speech_to_text');
+    assert.equal(span.attributes['gen_ai.request.model'], 'scribe_v1');
+    assert.equal(span.attributes['gen_ai.usage.input_seconds'], 12.4);
+    assert.equal(span.attributes['gen_ai.usage.input_characters'], undefined);
+    assert.equal(span.status.code, SpanStatusCode.UNSET);
+  } finally {
+    teardown();
+  }
+});
+
+test('speech to text records error status on failure', async () => {
+  const teardown = instrumented();
+  try {
+    const client = new StubSpeechToTextClient();
+    await assert.rejects(
+      () => client.convert({ modelId: 'boom', file: Buffer.from('audio') }),
+      /api error/
+    );
+
+    const [span] = exporter.getFinishedSpans();
+    assert.equal(span.status.code, SpanStatusCode.ERROR);
+  } finally {
+    teardown();
+  }
+});