weflayr 0.24.0 → 0.26.0

package/src/instrumentation/elevenlabs/full_instrumentation.js

@@ -1,236 +0,0 @@
-'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/instrumentation/google/get_audio_telemetry.js

@@ -1,30 +0,0 @@
-'use strict';
-
-/**
- * Per-modality audio token enrichment for the Google GenAI (Gemini) chat span.
- *
- * Neither instrumentor breaks usage down by modality, so for audio in/out (e.g.
- * Gemini TTS) we read the response's per-modality token details and set
- * `gen_ai.usage.{input,output}_tokens_details.audio_tokens`.
- */
-
-// Sum the token counts whose modality is AUDIO across a *TokensDetails array.
-function _audioTokens(details) {
-  if (!Array.isArray(details)) return 0;
-  return details.reduce(
-    (total, detail) => total + (detail && detail.modality === 'AUDIO' ? detail.tokenCount || 0 : 0),
-    0
-  );
-}
-
-function setAudioTelemetry(span, response) {
-  const usage = response && response.usageMetadata;
-  if (!usage) return;
-  const inputAudio = _audioTokens(usage.promptTokensDetails);
-  const outputAudio = _audioTokens(usage.candidatesTokensDetails);
-  if (inputAudio) span.setAttribute('gen_ai.usage.input_tokens_details.audio_tokens', inputAudio);
-  if (outputAudio)
-    span.setAttribute('gen_ai.usage.output_tokens_details.audio_tokens', outputAudio);
-}
-
-module.exports = { setAudioTelemetry, _audioTokens };

package/src/instrumentation/google/get_cache_operations_telemetry.js

@@ -1,171 +0,0 @@
-'use strict';
-
-/**
- * Explicit-cache lifecycle telemetry for Google GenAI (Gemini).
- *
- * Explicit caching happens through API calls that are not LLM calls — the
- * caller uploads content once via `client.caches.create` (returning a
- * `cachedContents/{id}` name later referenced by `generateContent`), and may
- * extend its TTL (`caches.update`) or remove it (`caches.delete`). No
- * instrumentor covers these endpoints, so the cached content and its lifetime
- * were invisible to the telemetry.
- *
- * One span per lifecycle call, carrying:
- *   - `weflayr.cache.operation`          — create / update / delete
- *   - `weflayr.cache.cached_content_id`  — the cache's server-generated name
- *   - `weflayr.cache.expire_time`        — absolute expiry (create / update)
- *   - `gen_ai.usage.input_tokens`        — the cached content's token count
- *     (create only; billed at the standard input rate)
- *   - the cached content itself (`gen_ai.input.messages` /
- *     `gen_ai.system_instructions` / `gen_ai.tool.definitions`) — the content
- *     is sent only on the create call and never repeated in the calls that use
- *     the cache, so this is the one place it can be captured. The span
- *     processor strips these when message-content capture is disabled.
- */
-
-const { trace, SpanStatusCode } = require('@opentelemetry/api');
-
-const { getProviderName } = require('./get_provider_name');
-
-const TRACER_NAME = 'weflayr.instrumentation.google.cache_operations';
-
-const OPERATION_ATTR = 'weflayr.cache.operation';
-const CACHED_CONTENT_ID_ATTR = 'weflayr.cache.cached_content_id';
-const EXPIRE_TIME_ATTR = 'weflayr.cache.expire_time';
-
-const OPERATIONS = ['create', 'update', 'delete'];
-
-// The cached content mapped to the role+parts message shape the chat path uses.
-function _contentToMessage(content) {
-  if (typeof content === 'string') {
-    return { role: 'user', parts: [{ type: 'text', content }] };
-  }
-  const role = (content && content.role) || 'user';
-  const rawParts = (content && content.parts) || [];
-  const parts = [];
-  for (const rawPart of rawParts) {
-    if (typeof rawPart === 'string') {
-      parts.push({ type: 'text', content: rawPart });
-    } else if (rawPart && typeof rawPart.text === 'string') {
-      parts.push({ type: 'text', content: rawPart.text });
-    } else if (rawPart && rawPart.inlineData) {
-      // Non-text parts (e.g. audio) become a byte-less blob stub so span
-      // attributes never carry raw media payloads.
-      parts.push({ type: 'blob', mime_type: rawPart.inlineData.mimeType || '' });
-    }
-  }
-  return { role, parts };
-}
-
-function _setSystemInstruction(span, systemInstruction) {
-  if (systemInstruction == null) return;
-  const texts =
-    typeof systemInstruction === 'string'
-      ? [systemInstruction]
-      : (systemInstruction.parts || [])
-          .map((part) => part && part.text)
-          .filter((text) => typeof text === 'string');
-  if (texts.length) {
-    span.setAttribute(
-      'gen_ai.system_instructions',
-      JSON.stringify(texts.map((text) => ({ type: 'text', content: text })))
-    );
-  }
-}
-
-function _setToolDefinitions(span, config) {
-  const definitions = [];
-  for (const tool of (config && config.tools) || []) {
-    for (const declaration of (tool && tool.functionDeclarations) || []) {
-      definitions.push(declaration);
-    }
-  }
-  if (definitions.length) {
-    span.setAttribute('gen_ai.tool.definitions', JSON.stringify(definitions));
-  }
-}
-
-// Stamp the server-side facts of the cache from a create/update response.
-function _stampCachedContent(span, cachedContent, operation) {
-  if (!cachedContent) return;
-  if (cachedContent.name) {
-    span.setAttribute(CACHED_CONTENT_ID_ATTR, String(cachedContent.name));
-  }
-  if (cachedContent.expireTime) {
-    span.setAttribute(EXPIRE_TIME_ATTR, String(cachedContent.expireTime));
-  }
-  // Gemini bills the cached tokens once, at creation; an update (TTL extension)
-  // returns the same usageMetadata but bills nothing.
-  if (operation !== 'create') return;
-  const totalTokens = cachedContent.usageMetadata && cachedContent.usageMetadata.totalTokenCount;
-  if (totalTokens) {
-    span.setAttribute('gen_ai.usage.input_tokens', totalTokens);
-  }
-}
-
-function _startSpan(operation, params, system) {
-  const span = trace.getTracer(TRACER_NAME).startSpan(`cache_${operation}`);
-  span.setAttribute('gen_ai.system', system);
-  span.setAttribute('gen_ai.operation.name', `cache_${operation}`);
-  span.setAttribute(OPERATION_ATTR, operation);
-  if (params && params.model) {
-    // The chat path strips the leading "models/" prefix; mirror it.
-    span.setAttribute('gen_ai.request.model', params.model.replace(/^models\//, ''));
-  }
-  // update/delete address the cache by name; create gets it from the response.
-  if (params && params.name) {
-    span.setAttribute(CACHED_CONTENT_ID_ATTR, String(params.name));
-  }
-  if (operation === 'create') {
-    const config = (params && params.config) || {};
-    if (config.contents != null) {
-      const contentsList = Array.isArray(config.contents) ? config.contents : [config.contents];
-      span.setAttribute(
-        'gen_ai.input.messages',
-        JSON.stringify(contentsList.map(_contentToMessage))
-      );
-    }
-    _setSystemInstruction(span, config.systemInstruction);
-    _setToolDefinitions(span, config);
-  }
-  return span;
-}
-
-function _recordError(span, error) {
-  span.setStatus({ code: SpanStatusCode.ERROR, message: error?.message ?? String(error) });
-  span.recordException(error);
-}
-
-// Wrap `Caches.prototype.create/update/delete`, pushing the restore tuples onto
-// the shared `patched` array the orchestrator owns for uninstrument().
-function instrumentCacheOperations(Caches, patched) {
-  const owner = Caches.prototype;
-  for (const operation of OPERATIONS) {
-    const original = owner[operation];
-    if (typeof original !== 'function') continue;
-
-    const wrapper = function cacheOperationWrapper(params, ...rest) {
-      const span = _startSpan(operation, params, getProviderName(this));
-      return Promise.resolve(original.call(this, params, ...rest)).then(
-        (response) => {
-          try {
-            _stampCachedContent(span, response, operation);
-          } catch {
-            // Never break the caller over an enrichment failure.
-          }
-          span.end();
-          return response;
-        },
-        (error) => {
-          _recordError(span, error);
-          span.end();
-          throw error;
-        }
-      );
-    };
-    owner[operation] = wrapper;
-    patched.push([owner, operation, original]);
-  }
-}
-
-module.exports = { instrumentCacheOperations };

package/src/instrumentation/google/get_embeddings_telemetry.js

@@ -1,99 +0,0 @@
-'use strict';
-
-/**
- * Embeddings-endpoint telemetry for Google GenAI (Gemini).
- *
- * `@traceloop/instrumentation-google-generativeai` wraps generate_content but not
- * embeddings, so this covers it by starting its own span on the private
- * `Models.prototype.embedContentInternal` (which the public `embedContent`
- * delegates to). The Gemini Developer API returns NO token usage on embedContent
- * (only Vertex does), so the span records the billable unit weflayr can price:
- * the input character count under `gen_ai.usage.input_characters` (normalized to
- * num_input_chars).
- */
-
-const { trace, SpanStatusCode } = require('@opentelemetry/api');
-
-const { getProviderName } = require('./get_provider_name');
-
-const TRACER_NAME = 'weflayr.instrumentation.google.embeddings';
-const EMBEDDINGS_OPERATION = 'embeddings';
-
-// `contents` is a string, a Content/Part object, or an array of those; the
-// billable unit is the total number of characters of text across them.
-function _contentCharacters(contents) {
-  if (contents == null) return 0;
-  if (typeof contents === 'string') return contents.length;
-  if (Array.isArray(contents)) {
-    return contents.reduce((total, item) => total + _contentCharacters(item), 0);
-  }
-  if (typeof contents === 'object') {
-    if (typeof contents.text === 'string') return contents.text.length;
-    if (Array.isArray(contents.parts)) return _contentCharacters(contents.parts);
-  }
-  return 0;
-}
-
-// The embedded text mapped to the role+parts message shape the chat path uses:
-// a string (or {text} / {parts} object) becomes one user message per content.
-function _contentToMessage(content) {
-  if (typeof content === 'string') {
-    return { role: 'user', parts: [{ type: 'text', content }] };
-  }
-  if (content && typeof content.text === 'string') {
-    return { role: 'user', parts: [{ type: 'text', content: content.text }] };
-  }
-  return { role: 'user', parts: [] };
-}
-
-function _recordError(span, error) {
-  span.setStatus({ code: SpanStatusCode.ERROR, message: error?.message ?? String(error) });
-  span.recordException(error);
-}
-
-// Wrap `Models.prototype.embedContentInternal`, pushing the restore tuple onto
-// the shared `patched` array the orchestrator owns for uninstrument().
-function instrumentEmbeddings(Models, patched) {
-  const owner = Models.prototype;
-  const original = owner.embedContentInternal;
-  if (typeof original !== 'function') return;
-
-  function wrapper(params, ...rest) {
-    const span = trace.getTracer(TRACER_NAME).startSpan(EMBEDDINGS_OPERATION);
-    span.setAttribute('gen_ai.system', getProviderName(this));
-    span.setAttribute('gen_ai.operation.name', EMBEDDINGS_OPERATION);
-    if (params && params.model) {
-      // The chat path strips the leading "models/" prefix; mirror it.
-      span.setAttribute('gen_ai.request.model', params.model.replace(/^models\//, ''));
-    }
-    span.setAttribute(
-      'gen_ai.usage.input_characters',
-      _contentCharacters(params && params.contents)
-    );
-    // The embedded text is the prompt; stamp it like the chat path does. The
-    // span processor strips it when message-content capture is disabled.
-    if (params && params.contents != null) {
-      const contentsList = Array.isArray(params.contents) ? params.contents : [params.contents];
-      span.setAttribute(
-        'gen_ai.input.messages',
-        JSON.stringify(contentsList.map(_contentToMessage))
-      );
-    }
-    return Promise.resolve(original.call(this, params, ...rest)).then(
-      (response) => {
-        span.end();
-        return response;
-      },
-      (error) => {
-        _recordError(span, error);
-        span.end();
-        throw error;
-      }
-    );
-  }
-
-  owner.embedContentInternal = wrapper;
-  patched.push([owner, 'embedContentInternal', original]);
-}
-
-module.exports = { instrumentEmbeddings };

package/src/instrumentation/google/set_telemetry_attributes.js

@@ -1,104 +0,0 @@
-'use strict';
-
-/**
- * Google GenAI (Gemini) telemetry complement — the registered orchestrator.
- *
- * Wires every weflayr-supplied patch the traceloop Google instrumentor misses:
- *   - chat span enrichment (one wrap of generateContent{,Stream}Internal that
- *     stamps provider name + audio tokens + cache tokens — see the get_*_telemetry
- *     files), and
- *   - the embeddings endpoint it doesn't cover at all.
- *
- * The public arrows delegate to these private prototype methods while the
- * traceloop span is the active span, so enrichment lands on that span.
- */
-
-const { trace } = require('@opentelemetry/api');
-
-const { getProviderName } = require('./get_provider_name');
-const { setAudioTelemetry } = require('./get_audio_telemetry');
-const { setCacheTelemetry, setCacheConfigTelemetry } = require('./get_cache_telemetry');
-const { setReasoningTelemetry } = require('./get_reasoning_telemetry');
-const { instrumentEmbeddings } = require('./get_embeddings_telemetry');
-const { instrumentCacheOperations } = require('./get_cache_operations_telemetry');
-
-class GoogleTelemetryInstrumentor {
-  constructor() {
-    // [ownerPrototype, methodName, originalFunction] for uninstrument().
-    this._patched = [];
-  }
-
-  instrument() {
-    let Models;
-    let Caches;
-    try {
-      ({ Models, Caches } = require('@google/genai'));
-    } catch (err) {
-      throw new Error(
-        'weflayr.autoInstrument(GOOGLE_GENAI): the @google/genai client is not installed. ' +
-          'Install it with: npm install @google/genai\n' +
-          `Underlying error: ${err.message}`
-      );
-    }
-
-    // Non-streaming: stamp provider up front, audio + cache tokens off the response.
-    this._wrapChat(Models.prototype, 'generateContentInternal', { stream: false });
-    // Streaming: stamp provider, then cache tokens off the final chunk's usageMetadata.
-    this._wrapChat(Models.prototype, 'generateContentStreamInternal', { stream: true });
-    // Embeddings: an endpoint the traceloop instrumentor doesn't cover at all.
-    instrumentEmbeddings(Models, this._patched);
-    // Explicit-cache lifecycle (caches.create/update/delete): endpoints the
-    // traceloop instrumentor doesn't cover at all.
-    if (Caches) instrumentCacheOperations(Caches, this._patched);
-  }
-
-  _wrapChat(owner, methodName, { stream }) {
-    const original = owner[methodName];
-
-    function wrapper(...args) {
-      const span = trace.getActiveSpan();
-      if (!span || !span.isRecording || !span.isRecording()) {
-        return original.apply(this, args);
-      }
-      span.setAttribute('gen_ai.system', getProviderName(this));
-      setCacheConfigTelemetry(span, args[0] && args[0].config);
-      if (!stream) {
-        return Promise.resolve(original.apply(this, args)).then((response) => {
-          setAudioTelemetry(span, response);
-          setCacheTelemetry(span, response);
-          setReasoningTelemetry(span, response);
-          return response;
-        });
-      }
-      // Streamed: usage (incl. cachedContentTokenCount) lands on the final chunk;
-      // observe the chunks as they pass through. The instrumentor keeps the span
-      // open until the stream is exhausted.
-      return Promise.resolve(original.apply(this, args)).then((stream_) => {
-        if (!stream_ || typeof stream_[Symbol.asyncIterator] !== 'function') return stream_;
-        return (async function* observeCache() {
-          for await (const chunk of stream_) {
-            try {
-              setCacheTelemetry(span, chunk);
-              setReasoningTelemetry(span, chunk);
-            } catch {
-              // Never break the caller's stream over an enrichment failure.
-            }
-            yield chunk;
-          }
-        })();
-      });
-    }
-
-    owner[methodName] = wrapper;
-    this._patched.push([owner, methodName, original]);
-  }
-
-  uninstrument() {
-    for (const [owner, methodName, original] of this._patched) {
-      owner[methodName] = original;
-    }
-    this._patched = [];
-  }
-}
-
-module.exports = { GoogleTelemetryInstrumentor };