weflayr 0.24.0 → 0.26.1

package/dist/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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setReasoningTelemetry = setReasoningTelemetry;
+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);
+}

package/dist/src/instrumentation/google/get_structured_output_schema_telemetry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Structured-output schema capture for the Google GenAI (Gemini) chat span.
+ *
+ * Gemini pins an answer to a JSON schema with `config.responseJsonSchema` (a
+ * plain JSON schema) or `config.responseSchema` (the SDK's own `Schema` object).
+ * The instrumentor records only that the output is JSON, never the schema.
+ *
+ * Google is wrapped at its own call site rather than through a traceloop
+ * `startSpan`, so this stamps directly instead of supplying a reader.
+ */
+import type { Span } from '@opentelemetry/api';
+export declare function setInputStructuredOutputSchemaTelemetry(span: Span, config: any): void;

package/dist/src/instrumentation/google/get_structured_output_schema_telemetry.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Structured-output schema capture for the Google GenAI (Gemini) chat span.
+ *
+ * Gemini pins an answer to a JSON schema with `config.responseJsonSchema` (a
+ * plain JSON schema) or `config.responseSchema` (the SDK's own `Schema` object).
+ * The instrumentor records only that the output is JSON, never the schema.
+ *
+ * Google is wrapped at its own call site rather than through a traceloop
+ * `startSpan`, so this stamps directly instead of supplying a reader.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setInputStructuredOutputSchemaTelemetry = setInputStructuredOutputSchemaTelemetry;
+const get_structured_output_schema_telemetry_1 = require("../shared/get_structured_output_schema_telemetry");
+function setInputStructuredOutputSchemaTelemetry(span, config) {
+    if (!config)
+        return;
+    (0, get_structured_output_schema_telemetry_1.setStructuredOutputSchemaTelemetry)(span, config.responseJsonSchema || config.responseSchema);
+}

package/dist/src/instrumentation/google/set_telemetry_attributes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+export declare class GoogleTelemetryInstrumentor {
+    private _patched;
+    instrument(): void;
+    private _wrapChat;
+    uninstrument(): void;
+}

package/dist/src/instrumentation/google/set_telemetry_attributes.js

@@ -0,0 +1,98 @@
+"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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoogleTelemetryInstrumentor = void 0;
+const api_1 = require("@opentelemetry/api");
+const get_provider_name_1 = require("./get_provider_name");
+const get_audio_telemetry_1 = require("./get_audio_telemetry");
+const get_cache_telemetry_1 = require("./get_cache_telemetry");
+const get_reasoning_telemetry_1 = require("./get_reasoning_telemetry");
+const get_structured_output_schema_telemetry_1 = require("./get_structured_output_schema_telemetry");
+const get_embeddings_telemetry_1 = require("./get_embeddings_telemetry");
+const get_cache_operations_telemetry_1 = require("./get_cache_operations_telemetry");
+class GoogleTelemetryInstrumentor {
+    // [ownerPrototype, methodName, originalFunction] for uninstrument().
+    _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.
+        (0, get_embeddings_telemetry_1.instrumentEmbeddings)(Models, this._patched);
+        // Explicit-cache lifecycle (caches.create/update/delete): endpoints the
+        // traceloop instrumentor doesn't cover at all.
+        if (Caches)
+            (0, get_cache_operations_telemetry_1.instrumentCacheOperations)(Caches, this._patched);
+    }
+    _wrapChat(owner, methodName, { stream }) {
+        const original = owner[methodName];
+        function wrapper(...args) {
+            const span = api_1.trace.getActiveSpan();
+            if (!span || !span.isRecording || !span.isRecording()) {
+                return original.apply(this, args);
+            }
+            span.setAttribute('gen_ai.system', (0, get_provider_name_1.getProviderName)(this));
+            const requestConfig = args[0] && args[0].config;
+            (0, get_cache_telemetry_1.setCacheConfigTelemetry)(span, requestConfig);
+            (0, get_structured_output_schema_telemetry_1.setInputStructuredOutputSchemaTelemetry)(span, requestConfig);
+            if (!stream) {
+                return Promise.resolve(original.apply(this, args)).then((response) => {
+                    (0, get_audio_telemetry_1.setAudioTelemetry)(span, response);
+                    (0, get_cache_telemetry_1.setCacheTelemetry)(span, response);
+                    (0, get_reasoning_telemetry_1.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 {
+                            (0, get_cache_telemetry_1.setCacheTelemetry)(span, chunk);
+                            (0, get_reasoning_telemetry_1.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 = [];
+    }
+}
+exports.GoogleTelemetryInstrumentor = GoogleTelemetryInstrumentor;

package/dist/src/instrumentation/openai/get_audio_telemetry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Hand-written OTel instrumentor for the OpenAI audio endpoints.
+ *
+ * The `@traceloop/instrumentation-openai` package wraps OpenAI's chat,
+ * completions, responses and image endpoints, but not the audio ones, so this
+ * ships inside weflayr to cover them. 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. It
+ * is registered alongside the traceloop instrumentor whenever
+ * `autoInstrument({ aiSdks: 'openai' })` runs.
+ *
+ * The billable unit differs by API, so each span records the one OpenAI 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`.
+ *
+ * Both endpoints are request/response (unary): `audio.speech.create` resolves to
+ * the full audio and `audio.transcriptions.create` to the transcription. The STT
+ * audio length is only present when the call requests `response_format: 'verbose_json'`.
+ */
+export declare class OpenAIAudioInstrumentor {
+    private _patched;
+    instrument(): void;
+    uninstrument(): void;
+    private _wrap;
+}

package/dist/src/instrumentation/openai/get_audio_telemetry.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Hand-written OTel instrumentor for the OpenAI audio endpoints.
+ *
+ * The `@traceloop/instrumentation-openai` package wraps OpenAI's chat,
+ * completions, responses and image endpoints, but not the audio ones, so this
+ * ships inside weflayr to cover them. 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. It
+ * is registered alongside the traceloop instrumentor whenever
+ * `autoInstrument({ aiSdks: 'openai' })` runs.
+ *
+ * The billable unit differs by API, so each span records the one OpenAI 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`.
+ *
+ * Both endpoints are request/response (unary): `audio.speech.create` resolves to
+ * the full audio and `audio.transcriptions.create` to the transcription. The STT
+ * audio length is only present when the call requests `response_format: 'verbose_json'`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIAudioInstrumentor = void 0;
+const api_1 = require("@opentelemetry/api");
+const TRACER_NAME = 'weflayr.instrumentation.openai_audio';
+const TTS_OPERATION = 'text_to_speech';
+const STT_OPERATION = 'speech_to_text';
+// 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 _startSpan(operation, body, system) {
+    const span = api_1.trace.getTracer(TRACER_NAME).startSpan(operation);
+    span.setAttribute('gen_ai.system', system);
+    span.setAttribute('gen_ai.operation.name', operation);
+    // `model` lives on the request body passed to both audio entrypoints.
+    const model = body && body.model;
+    if (model) {
+        span.setAttribute('gen_ai.request.model', model);
+    }
+    return span;
+}
+function _setInputCharacters(span, body) {
+    // `input` is the text passed to text_to_speech; the billable unit is its length.
+    span.setAttribute('gen_ai.usage.input_characters', ((body && body.input) || '').length);
+}
+function _setAudioDuration(span, response) {
+    // `duration` (seconds) is only present on a verbose transcription response;
+    // it is the billable unit for speech-to-text.
+    const durationSecs = response && response.duration;
+    if (durationSecs != null) {
+        span.setAttribute('gen_ai.usage.input_seconds', durationSecs);
+    }
+}
+function _recordError(span, error) {
+    span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error?.message ?? String(error) });
+    span.recordException(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 OpenAIAudioInstrumentor {
+    // [ownerPrototype, methodName, originalFunction] for uninstrument().
+    _patched = [];
+    instrument() {
+        let Speech;
+        let Transcriptions;
+        try {
+            ({ Speech } = require('openai/resources/audio/speech'));
+            ({ Transcriptions } = require('openai/resources/audio/transcriptions'));
+        }
+        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}`);
+        }
+        // TTS — request body is the 1st arg; billed per character.
+        this._wrap(Speech.prototype, {
+            operation: TTS_OPERATION,
+            setRequestAttributes: _setInputCharacters,
+            setResponseAttributes: null,
+        });
+        // STT — request body is the 1st arg; billed per second of audio.
+        this._wrap(Transcriptions.prototype, {
+            operation: STT_OPERATION,
+            setRequestAttributes: null,
+            setResponseAttributes: _setAudioDuration,
+        });
+    }
+    uninstrument() {
+        for (const [owner, methodName, original] of this._patched) {
+            owner[methodName] = original;
+        }
+        this._patched = [];
+    }
+    _wrap(owner, { operation, setRequestAttributes, setResponseAttributes, }) {
+        const original = owner.create;
+        function wrapper(body, ...rest) {
+            const span = _startSpan(operation, body, _detectSystem(this));
+            if (setRequestAttributes) {
+                setRequestAttributes(span, body);
+            }
+            return _consumeUnary(span, Promise.resolve(original.call(this, body, ...rest)), setResponseAttributes);
+        }
+        owner.create = wrapper;
+        this._patched.push([owner, 'create', original]);
+    }
+}
+exports.OpenAIAudioInstrumentor = OpenAIAudioInstrumentor;

package/dist/src/instrumentation/openai/get_bedrock_mantle_telemetry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Bedrock Mantle fixes for the OpenAI chat path.
+ *
+ * Amazon Bedrock Mantle serves Bedrock models over an OpenAI-compatible API, so it
+ * is reached with the stock `openai` SDK pointed at
+ * `https://bedrock-mantle.<region>.api.aws/v1`. Two things come out wrong there:
+ *
+ *   - **The call is attributed to OpenAI.** The instrumentor derives the provider
+ *     from the client base URL, but its chat patch hands `_detectVendorFromURL`
+ *     the *resource* (`this` inside `Chat.Completions.create`) instead of the
+ *     client, so `baseURL` is always undefined and every call falls back to
+ *     `openai`. Resolving the resource's `_client` before delegating restores the
+ *     detection the instrumentor already implements — for Mantle that is
+ *     `aws.bedrock`, which the normalizer prices as Bedrock. The Python
+ *     OpenLLMetry instrumentor passes the client correctly, so this gap is
+ *     Node-only.
+ *
+ *   - **The chain of thought is dropped.** Mantle's open-weight models (gpt-oss,
+ *     qwen, ...) return their reasoning under `reasoning`, which neither the
+ *     output-message builder nor the stream accumulator knows about. Without it a
+ *     call that spends its whole budget reasoning records an empty output message.
+ *     The reasoning part is inserted ahead of the tool calls, matching the order
+ *     the Python SDK emits.
+ */
+export declare class OpenAIBedrockMantleInstrumentor {
+    private _patched;
+    instrument(instrumentation: any): void;
+    /** Hand the vendor detection the real client, not the resource it is called with. */
+    private _patchVendorDetection;
+    /** Accumulate `delta.reasoning` across the streamed chunks. */
+    private _patchStreamedReasoning;
+    /** Add the reasoning part as the output message is written. */
+    private _patchOutputMessages;
+    uninstrument(): void;
+}

package/dist/src/instrumentation/openai/get_bedrock_mantle_telemetry.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Bedrock Mantle fixes for the OpenAI chat path.
+ *
+ * Amazon Bedrock Mantle serves Bedrock models over an OpenAI-compatible API, so it
+ * is reached with the stock `openai` SDK pointed at
+ * `https://bedrock-mantle.<region>.api.aws/v1`. Two things come out wrong there:
+ *
+ *   - **The call is attributed to OpenAI.** The instrumentor derives the provider
+ *     from the client base URL, but its chat patch hands `_detectVendorFromURL`
+ *     the *resource* (`this` inside `Chat.Completions.create`) instead of the
+ *     client, so `baseURL` is always undefined and every call falls back to
+ *     `openai`. Resolving the resource's `_client` before delegating restores the
+ *     detection the instrumentor already implements — for Mantle that is
+ *     `aws.bedrock`, which the normalizer prices as Bedrock. The Python
+ *     OpenLLMetry instrumentor passes the client correctly, so this gap is
+ *     Node-only.
+ *
+ *   - **The chain of thought is dropped.** Mantle's open-weight models (gpt-oss,
+ *     qwen, ...) return their reasoning under `reasoning`, which neither the
+ *     output-message builder nor the stream accumulator knows about. Without it a
+ *     call that spends its whole budget reasoning records an empty output message.
+ *     The reasoning part is inserted ahead of the tool calls, matching the order
+ *     the Python SDK emits.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIBedrockMantleInstrumentor = void 0;
+const OUTPUT_MESSAGES_ATTR = 'gen_ai.output.messages';
+// Reasoning streamed so far, per open span. Streamed deltas arrive while the
+// stream is consumed, but the output message is only built when the span ends,
+// so the two hooks below meet here.
+const _streamedReasoningBySpan = new WeakMap();
+function _completeResponseReasoning(result) {
+    const reasoning = result?.choices?.[0]?.message?.reasoning;
+    return typeof reasoning === 'string' && reasoning ? reasoning : undefined;
+}
+/** The parts array with the reasoning inserted ahead of the first non-text part
+ * (tool calls, audio, ...), so text and refusal keep leading it. */
+function _withReasoningPart(parts, reasoning) {
+    const reasoningPart = { type: 'reasoning', content: reasoning };
+    const firstNonTextIndex = parts.findIndex((part) => part?.type !== 'text' && part?.type !== 'refusal');
+    if (firstNonTextIndex === -1)
+        return [...parts, reasoningPart];
+    return [...parts.slice(0, firstNonTextIndex), reasoningPart, ...parts.slice(firstNonTextIndex)];
+}
+/** The serialized output messages with the reasoning part added, or null when the
+ * value isn't the expected JSON array of messages. */
+function _addReasoningToOutputMessages(rawOutputMessages, reasoning) {
+    if (typeof rawOutputMessages !== 'string')
+        return null;
+    let messages;
+    try {
+        messages = JSON.parse(rawOutputMessages);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(messages) || messages.length === 0)
+        return null;
+    const [first, ...rest] = messages;
+    if (!first || !Array.isArray(first.parts))
+        return null;
+    return JSON.stringify([{ ...first, parts: _withReasoningPart(first.parts, reasoning) }, ...rest]);
+}
+class OpenAIBedrockMantleInstrumentor {
+    // [owner, methodName, originalFunction] for uninstrument().
+    _patched = [];
+    // No-op (and never throws) if the instrumentor's internals have changed shape —
+    // the worst case is an OpenAI-attributed span without its chain of thought,
+    // never a crash.
+    instrument(instrumentation) {
+        if (!instrumentation)
+            return;
+        this._patchVendorDetection(instrumentation);
+        this._patchStreamedReasoning(instrumentation);
+        this._patchOutputMessages(instrumentation);
+    }
+    /** Hand the vendor detection the real client, not the resource it is called with. */
+    _patchVendorDetection(instrumentation) {
+        const original = instrumentation._detectVendorFromURL;
+        if (typeof original !== 'function')
+            return;
+        instrumentation._detectVendorFromURL = function detectVendorFromResolvedClient(client) {
+            const resolved = client && !client.baseURL && client._client ? client._client : client;
+            return original.call(this, resolved);
+        };
+        this._patched.push([instrumentation, '_detectVendorFromURL', original]);
+    }
+    /** Accumulate `delta.reasoning` across the streamed chunks. */
+    _patchStreamedReasoning(instrumentation) {
+        const original = instrumentation._streamingWrapPromise;
+        if (typeof original !== 'function')
+            return;
+        instrumentation._streamingWrapPromise = function streamingWrapWithReasoning(streamArgs) {
+            const span = streamArgs && streamArgs.span;
+            const wrappedStream = original.call(this, streamArgs);
+            if (!span)
+                return wrappedStream;
+            return (async function* accumulateReasoning() {
+                for await (const chunk of wrappedStream) {
+                    const reasoning = chunk?.choices?.[0]?.delta?.reasoning;
+                    if (typeof reasoning === 'string' && reasoning) {
+                        _streamedReasoningBySpan.set(span, (_streamedReasoningBySpan.get(span) ?? '') + reasoning);
+                    }
+                    yield chunk;
+                }
+            })();
+        };
+        this._patched.push([instrumentation, '_streamingWrapPromise', original]);
+    }
+    /** Add the reasoning part as the output message is written. */
+    _patchOutputMessages(instrumentation) {
+        const original = instrumentation._endSpan;
+        if (typeof original !== 'function')
+            return;
+        instrumentation._endSpan = function endSpanWithReasoning(args) {
+            const span = args && args.span;
+            const reasoning = _completeResponseReasoning(args && args.result) ??
+                (span ? _streamedReasoningBySpan.get(span) : undefined);
+            if (!span || !reasoning)
+                return original.call(this, args);
+            // The original builds the output messages and then ends the span, so the
+            // part is grafted on as the attribute is written rather than afterwards.
+            const previousSetAttribute = span.setAttribute;
+            span.setAttribute = function setAttributeWithReasoning(key, value) {
+                if (key === OUTPUT_MESSAGES_ATTR) {
+                    value = _addReasoningToOutputMessages(value, reasoning) ?? value;
+                }
+                return previousSetAttribute.call(this, key, value);
+            };
+            try {
+                return original.call(this, args);
+            }
+            finally {
+                span.setAttribute = previousSetAttribute;
+                _streamedReasoningBySpan.delete(span);
+            }
+        };
+        this._patched.push([instrumentation, '_endSpan', original]);
+    }
+    uninstrument() {
+        for (const [owner, methodName, original] of this._patched) {
+            owner[methodName] = original;
+        }
+        this._patched = [];
+    }
+}
+exports.OpenAIBedrockMantleInstrumentor = OpenAIBedrockMantleInstrumentor;

package/dist/src/instrumentation/openai/get_cache_and_reasoning_telemetry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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`
+ * or `.cache_write_tokens`, so spans for prompt-cache hits/writes carry no
+ * cached-token count. The Python OpenLLMetry instrumentor sets
+ * `gen_ai.usage.cache_read_input_tokens` from the former, so this brings the Node
+ * SDK to parity; the latter (GPT-5.6+'s cache-write count) has no OpenLLMetry
+ * equivalent on either side, so this is its only source.
+ *
+ * It wraps the instrumentor instance's `_endSpan({ span, type, result })`, which
+ * finalizes the span after the response resolves, letting us stamp the
+ * cached-token counts off `result.usage` while the span is still open.
+ * `cache_write_tokens` is stamped as `gen_ai.usage.cache_creation_input_tokens`,
+ * the attribute name the normalizer already reads for Anthropic/Bedrock/Vercel.
+ *
+ * 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).
+ */
+export declare class OpenAIPromptCachingInstrumentor {
+    private _patched;
+    instrument(instrumentation: any): void;
+    uninstrument(): void;
+}

package/dist/src/instrumentation/openai/get_cache_and_reasoning_telemetry.js

@@ -0,0 +1,72 @@
+"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`
+ * or `.cache_write_tokens`, so spans for prompt-cache hits/writes carry no
+ * cached-token count. The Python OpenLLMetry instrumentor sets
+ * `gen_ai.usage.cache_read_input_tokens` from the former, so this brings the Node
+ * SDK to parity; the latter (GPT-5.6+'s cache-write count) has no OpenLLMetry
+ * equivalent on either side, so this is its only source.
+ *
+ * It wraps the instrumentor instance's `_endSpan({ span, type, result })`, which
+ * finalizes the span after the response resolves, letting us stamp the
+ * cached-token counts off `result.usage` while the span is still open.
+ * `cache_write_tokens` is stamped as `gen_ai.usage.cache_creation_input_tokens`,
+ * the attribute name the normalizer already reads for Anthropic/Bedrock/Vercel.
+ *
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIPromptCachingInstrumentor = void 0;
+const CACHE_READ_INPUT_TOKENS_ATTR = 'gen_ai.usage.cache_read_input_tokens';
+const CACHE_CREATION_INPUT_TOKENS_ATTR = 'gen_ai.usage.cache_creation_input_tokens';
+const REASONING_TOKENS_ATTR = 'gen_ai.usage.reasoning_tokens';
+class OpenAIPromptCachingInstrumentor {
+    // [instrumentation, methodName, originalFunction] for uninstrument().
+    _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 cacheWriteTokens = usage && usage.prompt_tokens_details && usage.prompt_tokens_details.cache_write_tokens;
+                if (cacheWriteTokens && recording) {
+                    span.setAttribute(CACHE_CREATION_INPUT_TOKENS_ATTR, cacheWriteTokens);
+                }
+                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 = [];
+    }
+}
+exports.OpenAIPromptCachingInstrumentor = OpenAIPromptCachingInstrumentor;

package/dist/src/instrumentation/openai/get_cache_config_telemetry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Request-side prompt-caching config capture for OpenAI chat spans.
+ *
+ * OpenAI callers influence the (automatic, server-side) prompt cache with
+ * request parameters the traceloop instrumentor never records:
+ * `prompt_cache_key` (a client-chosen routing key — requests sharing a key are
+ * routed to the same cache shard), the retention tuning —
+ * `prompt_cache_retention` ("in_memory" / "24h") on older models, replaced by
+ * `prompt_cache_options: { ttl }` ("30m") on GPT-5.6+ — and, also on GPT-5.6+,
+ * explicit breakpoint placement: a `prompt_cache_breakpoint` marker on a
+ * message content block (`prompt_cache_options: { mode: "explicit" }`
+ * disables the automatic breakpoint, requiring these to cache anything).
+ *
+ * Wrap `startSpan({ type, params })` (covering the streamed and non-streamed
+ * paths) to stamp the values as `weflayr.cache.key` / `weflayr.cache.retention`
+ * (raw retention/ttl string) and, when any content block carries the marker,
+ * `weflayr.cache.breakpoints` (a JSON list of `{"location": "messages[i]"}`
+ * entries — the marker itself carries no TTL, unlike Anthropic's
+ * `cache_control`; the normalizer owns the vocabulary).
+ * `prompt_cache_options: { mode: "explicit" }` is stamped as
+ * `weflayr.cache.mode` so the normalizer knows not to also synthesize the
+ * automatic "auto"-location breakpoint OpenAI does not create in this mode.
+ */
+export declare class OpenAICacheConfigInstrumentor {
+    private _patched;
+    instrument(instrumentation: any): void;
+    uninstrument(): void;
+}