weflayr 0.20.6 → 0.22.0

package/src/instrumentation/bedrock/get_input_message_content_telemetry.js

@@ -0,0 +1,94 @@
+'use strict';
+
+/**
+ * Input message content for Bedrock invoke_model spans the instrumentor misses.
+ *
+ * `@traceloop/instrumentation-bedrock` parses the request body per model vendor,
+ * so a call whose model id has no recognizable vendor (e.g. an invalid model —
+ * exactly the error spans) gets no `gen_ai.input.messages`. Wrap the
+ * instrumentor's `_startSpan({ params })` to stamp the input messages from the
+ * request body whenever the instrumentor did not. The span processor strips the
+ * attribute when message-content capture is disabled.
+ */
+
+function _contentToParts(content) {
+  if (typeof content === 'string') {
+    return [{ type: 'text', content }];
+  }
+  if (Array.isArray(content)) {
+    return content
+      .filter((block) => block && typeof block.text === 'string')
+      .map((block) => ({ type: 'text', content: block.text }));
+  }
+  return [];
+}
+
+// Messages in the role+parts shape from an InvokeModel JSON body — the
+// `messages` schema (Nova, Anthropic-on-Bedrock) or the flat `inputText` /
+// `prompt` schemas (Titan, legacy).
+function _inputMessagesFromRequestBody(rawBody) {
+  if (typeof rawBody !== 'string') return [];
+  let body;
+  try {
+    body = JSON.parse(rawBody);
+  } catch {
+    return [];
+  }
+  if (!body || typeof body !== 'object') return [];
+  if (Array.isArray(body.messages)) {
+    return body.messages
+      .filter((message) => message && typeof message === 'object')
+      .map((message) => ({
+        role: String(message.role || ''),
+        parts: _contentToParts(message.content),
+      }));
+  }
+  const prompt = body.inputText || body.prompt;
+  if (typeof prompt === 'string') {
+    return [{ role: 'user', parts: [{ type: 'text', content: prompt }] }];
+  }
+  return [];
+}
+
+class BedrockInputMessageContentInstrumentor {
+  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 missing input messages, never a crash.
+  instrument(instrumentation) {
+    if (!instrumentation) return;
+    const original = instrumentation._startSpan;
+    if (typeof original !== 'function') return;
+
+    instrumentation._startSpan = function startSpanWithInputMessages(request) {
+      const span = original.call(this, request);
+      try {
+        const attributes = span && span.attributes;
+        if (attributes && attributes['gen_ai.input.messages'] == null) {
+          const body =
+            request && request.params && request.params.input && request.params.input.body;
+          const messages = _inputMessagesFromRequestBody(body);
+          if (messages.length) {
+            span.setAttribute('gen_ai.input.messages', JSON.stringify(messages));
+          }
+        }
+      } catch {
+        // Never break span creation over an enrichment failure.
+      }
+      return span;
+    };
+    this._patched.push([instrumentation, '_startSpan', original]);
+  }
+
+  uninstrument() {
+    for (const [owner, methodName, original] of this._patched) {
+      owner[methodName] = original;
+    }
+    this._patched = [];
+  }
+}
+
+module.exports = { BedrockInputMessageContentInstrumentor };

package/src/instrumentation/bedrock/get_streaming_output_message_telemetry.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * Streamed-output message content for the Bedrock invoke_model stream span.
+ *
+ * `@traceloop/instrumentation-bedrock` accumulates the streamed text but formats
+ * the final `gen_ai.output.messages` by passing that string through its chat
+ * block mapper, which only accepts block arrays — so streamed Nova spans end up
+ * with an assistant message whose `parts` is empty. This complement wraps the
+ * instrumentor's per-chunk `_handleNovaStreamingMetadata(span, parsedResponse)`
+ * hook: it accumulates the `contentBlockDelta` text and the `messageStop` stop
+ * reason itself, and re-stamps a correct output message when the trailing
+ * `metadata` chunk (always last in a Nova stream) arrives — after the
+ * instrumentor has written its empty-parts message. The span processor strips
+ * the attribute when message-content capture is disabled.
+ */
+
+// Nova stop reasons mapped to the OTel finish_reason values the instrumentor
+// uses on non-streamed spans, so streamed and non-streamed rows normalize alike.
+const FINISH_REASON_BY_STOP_REASON = {
+  end_turn: 'stop',
+  stop_sequence: 'stop',
+  max_tokens: 'length',
+  tool_use: 'tool_call',
+};
+
+class BedrockStreamingOutputMessageInstrumentor {
+  constructor() {
+    // [instrumentation, methodName, originalFunction] for uninstrument().
+    this._patched = [];
+    // span -> {text, stopReason} accumulated across the stream's chunks.
+    this._streamStateBySpan = new WeakMap();
+  }
+
+  // No-op (and never throws) if the instrumentor's internals have changed shape —
+  // the worst case is an empty streamed output message, never a crash.
+  instrument(instrumentation) {
+    if (!instrumentation) return;
+    const original = instrumentation._handleNovaStreamingMetadata;
+    if (typeof original !== 'function') return;
+
+    const streamStateBySpan = this._streamStateBySpan;
+    instrumentation._handleNovaStreamingMetadata = function handleWithOutputMessage(
+      span,
+      parsedResponse
+    ) {
+      try {
+        const state = streamStateBySpan.get(span) || { text: '', stopReason: null };
+        const delta =
+          parsedResponse &&
+          parsedResponse.contentBlockDelta &&
+          parsedResponse.contentBlockDelta.delta &&
+          parsedResponse.contentBlockDelta.delta.text;
+        if (typeof delta === 'string') state.text += delta;
+        const stopReason =
+          parsedResponse && parsedResponse.messageStop && parsedResponse.messageStop.stopReason;
+        if (stopReason != null) state.stopReason = stopReason;
+        streamStateBySpan.set(span, state);
+
+        if (parsedResponse && parsedResponse.metadata && state.text) {
+          const message = {
+            role: 'assistant',
+            parts: [{ type: 'text', content: state.text }],
+          };
+          if (state.stopReason != null) {
+            message.finish_reason =
+              FINISH_REASON_BY_STOP_REASON[state.stopReason] || state.stopReason;
+          }
+          span.setAttribute('gen_ai.output.messages', JSON.stringify([message]));
+        }
+      } catch {
+        // Never break the caller's stream over an enrichment failure.
+      }
+      return original.call(this, span, parsedResponse);
+    };
+    this._patched.push([instrumentation, '_handleNovaStreamingMetadata', original]);
+  }
+
+  uninstrument() {
+    for (const [owner, methodName, original] of this._patched) {
+      owner[methodName] = original;
+    }
+    this._patched = [];
+  }
+}
+
+module.exports = { BedrockStreamingOutputMessageInstrumentor };

package/src/instrumentation/bedrock/set_telemetry_attributes.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * Bedrock telemetry complement — the registered orchestrator.
+ *
+ * Wires the weflayr-supplied patches the traceloop Bedrock instrumentor misses:
+ * cached-prompt token counts on the invoke_model span (Nova returns them in the
+ * response body but traceloop never reads them) and the streamed output message
+ * content (its stream path formats an empty-parts message).
+ */
+
+const { BedrockPromptCachingInstrumentor } = require('./get_cache_telemetry');
+const { BedrockInputMessageContentInstrumentor } = require('./get_input_message_content_telemetry');
+const {
+  BedrockStreamingOutputMessageInstrumentor,
+} = require('./get_streaming_output_message_telemetry');
+
+class BedrockTelemetryInstrumentor {
+  constructor() {
+    this._subInstrumentors = [
+      new BedrockPromptCachingInstrumentor(),
+      new BedrockInputMessageContentInstrumentor(),
+      new BedrockStreamingOutputMessageInstrumentor(),
+    ];
+  }
+
+  instrument(instrumentation) {
+    for (const sub of this._subInstrumentors) sub.instrument(instrumentation);
+  }
+
+  uninstrument() {
+    for (const sub of this._subInstrumentors) sub.uninstrument();
+  }
+}
+
+module.exports = { BedrockTelemetryInstrumentor };

package/src/instrumentation/cohere/get_chat_telemetry.js

@@ -0,0 +1,88 @@
+'use strict';
+
+/**
+ * Chat token-usage enrichment complement for the Cohere v1 chat path.
+ *
+ * `@traceloop/instrumentation-cohere` creates the `cohere.chat` span but reads
+ * token usage from the obsolete `result.token_count.{prompt,response}_tokens`
+ * shape; modern cohere-ai returns usage under `meta.billedUnits` instead, so the
+ * traceloop span ends up with zero chat tokens. This thin complement backfills
+ * `gen_ai.usage.{input,output}_tokens` from `meta.billedUnits`, the same source
+ * traceloop already uses for the `generate` endpoint — bringing Node chat tokens
+ * to parity with the Python SDK (OpenLLMetry captures them natively, so there is
+ * no Python counterpart).
+ *
+ * It hooks the internal `CohereClient.prototype.__chat` (which the public `chat`
+ * delegates to synchronously) rather than the public `chat`: traceloop wraps
+ * `chat` and opens the span around it, so `__chat` runs while that span is the
+ * active span — letting this complement enrich it regardless of patch order.
+ */
+
+const { trace } = require('@opentelemetry/api');
+
+function _billedUnits(result) {
+  // Public `chat` resolves to the response body, but `__chat` resolves to the
+  // Fern wrapper `{ data, rawResponse }`; read billedUnits off either shape.
+  const response = result && result.data ? result.data : result;
+  return response && response.meta ? response.meta.billedUnits : undefined;
+}
+
+function _setChatTokenUsage(span, result) {
+  const billedUnits = _billedUnits(result);
+  if (!billedUnits) return;
+  if (typeof billedUnits.inputTokens === 'number') {
+    span.setAttribute('gen_ai.usage.input_tokens', billedUnits.inputTokens);
+  }
+  if (typeof billedUnits.outputTokens === 'number') {
+    span.setAttribute('gen_ai.usage.output_tokens', billedUnits.outputTokens);
+  }
+}
+
+class CohereChatTokenUsageInstrumentor {
+  constructor() {
+    // [ownerPrototype, methodName, originalFunction] for uninstrument().
+    this._patched = [];
+  }
+
+  instrument() {
+    let CohereClient;
+    try {
+      ({ CohereClient } = require('cohere-ai/Client'));
+    } catch (err) {
+      throw new Error(
+        'weflayr.autoInstrument(COHERE): the cohere-ai client is not installed. ' +
+          'Install it with: npm install cohere-ai\n' +
+          `Underlying error: ${err.message}`
+      );
+    }
+
+    this._wrap(CohereClient.prototype, '__chat');
+  }
+
+  uninstrument() {
+    for (const [owner, methodName, original] of this._patched) {
+      owner[methodName] = original;
+    }
+    this._patched = [];
+  }
+
+  _wrap(owner, methodName) {
+    const original = owner[methodName];
+
+    function wrapper(...args) {
+      // Captured synchronously, while traceloop's chat span is still active.
+      const span = trace.getActiveSpan();
+      const result = original.apply(this, args);
+      if (!span || !span.isRecording || !span.isRecording()) return result;
+      return Promise.resolve(result).then((response) => {
+        _setChatTokenUsage(span, response);
+        return response;
+      });
+    }
+
+    owner[methodName] = wrapper;
+    this._patched.push([owner, methodName, original]);
+  }
+}
+
+module.exports = { CohereChatTokenUsageInstrumentor };

package/src/instrumentation/cohere/get_embeddings_telemetry.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * Hand-written OTel instrumentor for the Cohere embeddings endpoint.
+ *
+ * `@traceloop/instrumentation-cohere` (the package weflayr uses for Cohere on
+ * Node) wraps chat/generate/rerank but not `embed`, so this ships inside weflayr
+ * to cover it. OpenLLMetry's cohere instrumentor doesn't cover `embed` either, so
+ * the Python SDK has a mirror complement (`cohere_embeddings.py`) shaped to
+ * normalize identically. It is registered alongside the traceloop instrumentor
+ * whenever `autoInstrument({ aiSdks: 'cohere' })` runs.
+ *
+ * Embeddings are billed per input token, so the span records the input tokens
+ * Cohere returns under `gen_ai.usage.input_tokens`; there is no completion.
+ */
+
+const { trace, SpanStatusCode } = require('@opentelemetry/api');
+
+const TRACER_NAME = 'weflayr.instrumentation.cohere_embeddings';
+// Matches the gen_ai.system the cohere chat instrumentors set (Python + Node).
+const SYSTEM = 'Cohere';
+const EMBEDDINGS_OPERATION = 'embeddings';
+
+function _recordError(span, error) {
+  span.setStatus({ code: SpanStatusCode.ERROR, message: error?.message ?? String(error) });
+  span.recordException(error);
+}
+
+function _wrapEmbed(owner, patched) {
+  const original = owner.embed;
+
+  function wrapper(request, ...rest) {
+    const span = trace.getTracer(TRACER_NAME).startSpan(EMBEDDINGS_OPERATION);
+    span.setAttribute('gen_ai.system', SYSTEM);
+    span.setAttribute('gen_ai.operation.name', EMBEDDINGS_OPERATION);
+    if (request && request.model) {
+      span.setAttribute('gen_ai.request.model', request.model);
+    }
+    // The embedded texts are the prompt; stamp one user message per text, like
+    // the chat path. The span processor strips it when content capture is off.
+    if (request && Array.isArray(request.texts) && request.texts.length) {
+      span.setAttribute(
+        'gen_ai.input.messages',
+        JSON.stringify(
+          request.texts.map((text) => ({ role: 'user', parts: [{ type: 'text', content: text }] }))
+        )
+      );
+    }
+    return Promise.resolve(original.call(this, request, ...rest)).then(
+      (response) => {
+        // Node SDK reports the billed input tokens under camelCase keys.
+        const inputTokens =
+          response?.meta?.billedUnits?.inputTokens ?? response?.meta?.tokens?.inputTokens;
+        if (inputTokens != null) {
+          span.setAttribute('gen_ai.usage.input_tokens', inputTokens);
+        }
+        span.end();
+        return response;
+      },
+      (error) => {
+        _recordError(span, error);
+        span.end();
+        throw error;
+      }
+    );
+  }
+
+  owner.embed = wrapper;
+  patched.push([owner, 'embed', original]);
+}
+
+class CohereEmbeddingsInstrumentor {
+  constructor() {
+    // [ownerPrototype, methodName, originalFunction] for uninstrument().
+    this._patched = [];
+  }
+
+  instrument() {
+    let CohereClient;
+    let V2Client;
+    try {
+      // v1 `embed` is a prototype method on CohereClient; v2 `embed` lives on
+      // V2Client.prototype (CohereClientV2 binds it as an instance property, so
+      // it must be patched on the underlying V2Client class instead).
+      ({ CohereClient } = require('cohere-ai/Client'));
+      ({ V2Client } = require('cohere-ai/api/resources/v2/client/Client'));
+    } catch (err) {
+      throw new Error(
+        'weflayr.autoInstrument(COHERE): the cohere-ai client is not installed. ' +
+          'Install it with: npm install cohere-ai\n' +
+          `Underlying error: ${err.message}`
+      );
+    }
+
+    _wrapEmbed(CohereClient.prototype, this._patched);
+    _wrapEmbed(V2Client.prototype, this._patched);
+  }
+
+  uninstrument() {
+    for (const [owner, methodName, original] of this._patched) {
+      owner[methodName] = original;
+    }
+    this._patched = [];
+  }
+}
+
+module.exports = { CohereEmbeddingsInstrumentor };

package/src/instrumentation/cohere/set_telemetry_attributes.js

@@ -0,0 +1,32 @@
+'use strict';
+
+/**
+ * Cohere telemetry complement — the registered orchestrator.
+ *
+ * Wires the weflayr-supplied patches the traceloop Cohere instrumentor misses:
+ *   - chat token usage (traceloop reads the obsolete usage shape and records
+ *     zero chat tokens), and
+ *   - the embeddings endpoint it doesn't cover.
+ */
+
+const { CohereChatTokenUsageInstrumentor } = require('./get_chat_telemetry');
+const { CohereEmbeddingsInstrumentor } = require('./get_embeddings_telemetry');
+
+class CohereTelemetryInstrumentor {
+  constructor() {
+    this._subInstrumentors = [
+      new CohereChatTokenUsageInstrumentor(),
+      new CohereEmbeddingsInstrumentor(),
+    ];
+  }
+
+  instrument(instrumentation) {
+    for (const sub of this._subInstrumentors) sub.instrument(instrumentation);
+  }
+
+  uninstrument() {
+    for (const sub of this._subInstrumentors) sub.uninstrument();
+  }
+}
+
+module.exports = { CohereTelemetryInstrumentor };

package/src/instrumentation/google/get_audio_telemetry.js

@@ -0,0 +1,30 @@
+'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_telemetry.js

@@ -0,0 +1,25 @@
+'use strict';
+
+/**
+ * Context-caching token enrichment for the Google GenAI (Gemini) chat span.
+ *
+ * Neither instrumentor records cached-content tokens, so we read
+ * `usageMetadata.cachedContentTokenCount` (explicit or implicit caching) and
+ * split it by modality: audio cached tokens go to
+ * `gen_ai.usage.input_tokens_details.cached_audio_tokens`and the remainder to `gen_ai.usage.cache_read_input_tokens`
+ */
+
+const { _audioTokens } = require('./get_audio_telemetry');
+
+function setCacheTelemetry(span, response) {
+  const usage = response && response.usageMetadata;
+  const cachedTokens = (usage && usage.cachedContentTokenCount) || 0;
+  if (!cachedTokens) return;
+  const cachedAudio = _audioTokens(usage.cacheTokensDetails);
+  if (cachedAudio)
+    span.setAttribute('gen_ai.usage.input_tokens_details.cached_audio_tokens', cachedAudio);
+  const cacheRead = Math.max(0, cachedTokens - cachedAudio);
+  if (cacheRead) span.setAttribute('gen_ai.usage.cache_read_input_tokens', cacheRead);
+}
+
+module.exports = { setCacheTelemetry };

package/src/instrumentation/google/get_embeddings_telemetry.js

@@ -0,0 +1,99 @@
+'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/get_provider_name.js

@@ -0,0 +1,25 @@
+'use strict';
+
+/**
+ * Provider-name enrichment for the Google GenAI (Gemini) chat span.
+ *
+ * `@traceloop/instrumentation-google-generativeai` hardcodes
+ * `gen_ai.provider.name = "gcp.gen_ai"` and can't tell Vertex from the Gemini
+ * Developer API. We read the client's Vertex flag and return the value to set as
+ * `gen_ai.system` (which the normalizer prefers): `vertex_ai` / `gemini`,
+ * matching what the Python google-genai instrumentor reports natively. Node-only.
+ */
+
+// Read the Vertex-vs-Dev backend off the Models instance's api client.
+function getProviderName(instance) {
+  try {
+    if (instance && instance.apiClient && typeof instance.apiClient.isVertexAI === 'function') {
+      return instance.apiClient.isVertexAI() ? 'vertex_ai' : 'gemini';
+    }
+  } catch {
+    // fall through to default
+  }
+  return 'gemini';
+}
+
+module.exports = { getProviderName };

package/src/instrumentation/google/get_reasoning_telemetry.js

@@ -0,0 +1,21 @@
+'use strict';
+
+/**
+ * Reasoning (thinking) token enrichment for the Google GenAI (Gemini) chat span.
+ *
+ * Neither instrumentor surfaces the thinking budget. Gemini reports thinking
+ * under `usageMetadata.thoughtsTokenCount`, which is SEPARATE from
+ * `candidatesTokenCount` (the visible output) and excluded from the totals, so
+ * without this the thinking tokens are lost. Stamp them as
+ * `gen_ai.usage.thoughts_token_count` so the normalizer can fold them into the
+ * completion count.
+ */
+
+function setReasoningTelemetry(span, response) {
+  const usage = response && response.usageMetadata;
+  if (!usage) return;
+  const thoughts = usage.thoughtsTokenCount || 0;
+  if (thoughts) span.setAttribute('gen_ai.usage.thoughts_token_count', thoughts);
+}
+
+module.exports = { setReasoningTelemetry };