weflayr 0.22.2 → 0.24.0

package/src/instrumentation/bedrock/get_cache_config_telemetry.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Request-side prompt-caching config capture for Bedrock invoke_model spans.
+ *
+ * Bedrock callers opt into caching in the request body, in the model vendor's
+ * own schema: Anthropic-on-Bedrock bodies carry `cache_control` blocks (the
+ * native Anthropic shape), Amazon Nova bodies carry `cachePoint` blocks (the
+ * Converse shape) — on system entries, message content blocks or tool
+ * definitions, each with an optional raw `ttl` string ("5m"/"1h"). The
+ * traceloop instrumentor never records them.
+ *
+ * Wrap the instrumentor's `_startSpan({ params })` (params.body is the raw
+ * request JSON) to stamp every breakpoint found as `weflayr.cache.breakpoints`.
+ * Bedrock responses report no TTL split of the written tokens; the worker
+ * derives it from these breakpoints when they all share one TTL.
+ */
+
+const { extractCacheBreakpoints } = require('../anthropic/get_cache_config_telemetry');
+
+const BREAKPOINTS_ATTR = 'weflayr.cache.breakpoints';
+
+// A breakpoint as location + the raw `cachePoint` `ttl` string, omitted when
+// the request sets none.
+function _cachePointEntry(location, cachePoint) {
+  const ttl = cachePoint && cachePoint.ttl;
+  return ttl ? { location, ttl: String(ttl) } : { location };
+}
+
+// The first `cachePoint` among a list of blocks (attached to a content block,
+// or standing alone as its own block), or undefined.
+function _cachePointOfBlocks(blocks) {
+  if (!Array.isArray(blocks)) return undefined;
+  const block = blocks.find((entry) => entry && entry.cachePoint != null);
+  return block && block.cachePoint;
+}
+
+// Every cache breakpoint in an InvokeModel request body, as location + the
+// raw `ttl` string (omitted when the breakpoint sets none): the
+// Anthropic-on-Bedrock `cache_control` shape and the Nova `cachePoint` shape
+// (which never overlap in one body).
+function extractBedrockCacheBreakpoints(body) {
+  const breakpoints = extractCacheBreakpoints(body);
+  const systemCachePoint = _cachePointOfBlocks(body.system);
+  if (systemCachePoint != null) {
+    breakpoints.push(_cachePointEntry('system', systemCachePoint));
+  }
+  (body.messages || []).forEach((message, index) => {
+    const cachePoint = _cachePointOfBlocks(message && message.content);
+    if (cachePoint != null) {
+      breakpoints.push(_cachePointEntry(`messages[${index}]`, cachePoint));
+    }
+  });
+  const tools = (body.toolConfig && body.toolConfig.tools) || [];
+  tools.forEach((tool, index) => {
+    if (tool && tool.cachePoint != null) {
+      breakpoints.push(_cachePointEntry(`tools[${index}]`, tool.cachePoint));
+    }
+  });
+  return breakpoints;
+}
+
+class BedrockCacheConfigInstrumentor {
+  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 cache-config capture, never a crash.
+  instrument(instrumentation) {
+    if (!instrumentation) return;
+    const startSpanOriginal = instrumentation._startSpan;
+    if (typeof startSpanOriginal !== 'function') return;
+
+    instrumentation._startSpan = function startSpanWithCacheConfig(request) {
+      const span = startSpanOriginal.call(this, request);
+      try {
+        const rawBody =
+          request && request.params && request.params.input && request.params.input.body;
+        if (typeof rawBody === 'string' || rawBody instanceof Uint8Array) {
+          const body = JSON.parse(
+            typeof rawBody === 'string' ? rawBody : new TextDecoder().decode(rawBody)
+          );
+          const breakpoints = extractBedrockCacheBreakpoints(body || {});
+          if (breakpoints.length) {
+            span.setAttribute(BREAKPOINTS_ATTR, JSON.stringify(breakpoints));
+          }
+        }
+      } catch {
+        // Never break span creation over an enrichment failure.
+      }
+      return span;
+    };
+    this._patched.push([instrumentation, '_startSpan', startSpanOriginal]);
+  }
+
+  uninstrument() {
+    for (const [owner, methodName, original] of this._patched) {
+      owner[methodName] = original;
+    }
+    this._patched = [];
+  }
+}
+
+module.exports = { BedrockCacheConfigInstrumentor, extractBedrockCacheBreakpoints };

package/src/instrumentation/bedrock/get_cache_telemetry.js

@@ -7,7 +7,9 @@
  * off the InvokeModel response body but never reads its cache-token counts, so
  * spans for prompt-cache hits carry no cached-token figures. Amazon Nova's native
  * InvokeModel response includes `usage.cacheReadInputTokenCount` /
- * `usage.cacheWriteInputTokenCount`; this maps them to the
+ * `usage.cacheWriteInputTokenCount` (Anthropic-on-Bedrock responses carry the
+ * native `usage.cache_read_input_tokens` / `cache_creation_input_tokens`);
+ * this maps them to the
  * `gen_ai.usage.cache_read_input_tokens` / `cache_creation_input_tokens`
  * attributes the worker reads, matching the Python SDK.
  *
@@ -19,14 +21,17 @@
 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';
 
-// Stamp cache counts from a Nova `usage` object onto the span.
+// Stamp cache counts from a `usage` object onto the span: Nova's camelCase
+// count fields, or Anthropic-on-Bedrock's native snake_case ones.
 function _setCacheFromUsage(span, usage) {
   if (!usage || !span || !span.isRecording || !span.isRecording()) return;
-  if (typeof usage.cacheReadInputTokenCount === 'number' && usage.cacheReadInputTokenCount) {
-    span.setAttribute(CACHE_READ_INPUT_TOKENS_ATTR, usage.cacheReadInputTokenCount);
+  const read = usage.cacheReadInputTokenCount ?? usage.cache_read_input_tokens;
+  const write = usage.cacheWriteInputTokenCount ?? usage.cache_creation_input_tokens;
+  if (typeof read === 'number' && read) {
+    span.setAttribute(CACHE_READ_INPUT_TOKENS_ATTR, read);
   }
-  if (typeof usage.cacheWriteInputTokenCount === 'number' && usage.cacheWriteInputTokenCount) {
-    span.setAttribute(CACHE_CREATION_INPUT_TOKENS_ATTR, usage.cacheWriteInputTokenCount);
+  if (typeof write === 'number' && write) {
+    span.setAttribute(CACHE_CREATION_INPUT_TOKENS_ATTR, write);
   }
 }
 

package/src/instrumentation/bedrock/set_telemetry_attributes.js

@@ -5,10 +5,13 @@
  *
  * 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).
+ * response body but traceloop never reads them), the request's cache
+ * breakpoints (`cache_control` / `cachePoint` blocks it never records) and the
+ * streamed output message content (its stream path formats an empty-parts
+ * message).
  */
 
+const { BedrockCacheConfigInstrumentor } = require('./get_cache_config_telemetry');
 const { BedrockPromptCachingInstrumentor } = require('./get_cache_telemetry');
 const { BedrockInputMessageContentInstrumentor } = require('./get_input_message_content_telemetry');
 const {
@@ -19,6 +22,7 @@ class BedrockTelemetryInstrumentor {
   constructor() {
     this._subInstrumentors = [
       new BedrockPromptCachingInstrumentor(),
+      new BedrockCacheConfigInstrumentor(),
       new BedrockInputMessageContentInstrumentor(),
       new BedrockStreamingOutputMessageInstrumentor(),
     ];

package/src/instrumentation/google/get_cache_operations_telemetry.js

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

@@ -1,16 +1,24 @@
 'use strict';
 
 /**
- * Context-caching token enrichment for the Google GenAI (Gemini) chat span.
+ * Context-caching 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`
+ *
+ * Also captures the request's explicit-cache reference: a call using explicit
+ * caching passes `config.cachedContent` (the `cachedContents/{id}` name of a
+ * cache created via `client.caches.create`), stamped as
+ * `weflayr.cache.cached_content_id` so the call can be joined to its cache
+ * lifecycle rows.
  */
 
 const { _audioTokens } = require('./get_audio_telemetry');
 
+const CACHED_CONTENT_ID_ATTR = 'weflayr.cache.cached_content_id';
+
 function setCacheTelemetry(span, response) {
   const usage = response && response.usageMetadata;
   const cachedTokens = (usage && usage.cachedContentTokenCount) || 0;
@@ -22,4 +30,10 @@ function setCacheTelemetry(span, response) {
   if (cacheRead) span.setAttribute('gen_ai.usage.cache_read_input_tokens', cacheRead);
 }
 
-module.exports = { setCacheTelemetry };
+// Stamp the request's explicit-cache reference (`config.cachedContent`).
+function setCacheConfigTelemetry(span, config) {
+  const cachedContent = config && config.cachedContent;
+  if (cachedContent) span.setAttribute(CACHED_CONTENT_ID_ATTR, String(cachedContent));
+}
+
+module.exports = { setCacheTelemetry, setCacheConfigTelemetry };

package/src/instrumentation/google/set_telemetry_attributes.js

@@ -17,9 +17,10 @@ const { trace } = require('@opentelemetry/api');
 
 const { getProviderName } = require('./get_provider_name');
 const { setAudioTelemetry } = require('./get_audio_telemetry');
-const { setCacheTelemetry } = require('./get_cache_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() {
@@ -29,8 +30,9 @@ class GoogleTelemetryInstrumentor {
 
   instrument() {
     let Models;
+    let Caches;
     try {
-      ({ Models } = require('@google/genai'));
+      ({ Models, Caches } = require('@google/genai'));
     } catch (err) {
       throw new Error(
         'weflayr.autoInstrument(GOOGLE_GENAI): the @google/genai client is not installed. ' +
@@ -45,6 +47,9 @@ class GoogleTelemetryInstrumentor {
     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 }) {
@@ -56,6 +61,7 @@ class GoogleTelemetryInstrumentor {
         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);

package/src/instrumentation/openai/get_cache_config_telemetry.js

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * 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) and the retention tuning —
+ * `prompt_cache_retention` ("in_memory" / "24h") on older models, replaced by
+ * `prompt_cache_options: { ttl }` ("30m") on GPT-5.6+.
+ *
+ * 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; the normalizer owns the vocabulary).
+ */
+
+const CACHE_KEY_ATTR = 'weflayr.cache.key';
+const CACHE_RETENTION_ATTR = 'weflayr.cache.retention';
+
+class OpenAICacheConfigInstrumentor {
+  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 cache-config capture, never a crash.
+  instrument(instrumentation) {
+    if (!instrumentation) return;
+    const startSpanOriginal = instrumentation.startSpan;
+    if (typeof startSpanOriginal !== 'function') return;
+
+    instrumentation.startSpan = function startSpanWithCacheConfig(request) {
+      const span = startSpanOriginal.call(this, request);
+      try {
+        const params = (request && request.params) || {};
+        if (params.prompt_cache_key) {
+          span.setAttribute(CACHE_KEY_ATTR, String(params.prompt_cache_key));
+        }
+        const retention =
+          params.prompt_cache_retention ||
+          (params.prompt_cache_options && params.prompt_cache_options.ttl);
+        if (retention) {
+          span.setAttribute(CACHE_RETENTION_ATTR, String(retention));
+        }
+      } catch {
+        // Never break span creation over an enrichment failure.
+      }
+      return span;
+    };
+    this._patched.push([instrumentation, 'startSpan', startSpanOriginal]);
+  }
+
+  uninstrument() {
+    for (const [owner, methodName, original] of this._patched) {
+      owner[methodName] = original;
+    }
+    this._patched = [];
+  }
+}
+
+module.exports = { OpenAICacheConfigInstrumentor };

package/src/instrumentation/openai/set_telemetry_attributes.js

@@ -11,6 +11,7 @@
  */
 
 const { OpenAIAudioInstrumentor } = require('./get_audio_telemetry');
+const { OpenAICacheConfigInstrumentor } = require('./get_cache_config_telemetry');
 const { OpenAIEmbeddingsInstrumentor } = require('./get_embeddings_telemetry');
 const { OpenAIStreamingUsageInstrumentor } = require('./get_streaming_usage');
 const { OpenAIPromptCachingInstrumentor } = require('./get_cache_and_reasoning_telemetry');
@@ -22,6 +23,7 @@ class OpenAITelemetryInstrumentor {
       new OpenAIEmbeddingsInstrumentor(),
       new OpenAIStreamingUsageInstrumentor(),
       new OpenAIPromptCachingInstrumentor(),
+      new OpenAICacheConfigInstrumentor(),
     ];
   }
 

package/src/instrumentation/vercel/full_instrumentation.js

@@ -7,7 +7,8 @@
  * is registering it globally so every generateText/streamText/embed call emits
  * GenAI semconv spans through the tracer provider weflayr's setup() installed.
  * `usage: true` adds the `ai.usage.*` token details (reasoning tokens, uncached
- * input) that the semconv attributes do not carry.
+ * input) that the semconv attributes do not carry; `providerMetadata: true`
+ * opts into `ai.response.providerMetadata` on the spans that carry it.
  *
  * The aggregate spans the integration emits around each model call
  * (invoke_agent, agent_step, duplicated embeddings spans) are filtered out
@@ -37,7 +38,14 @@ class VercelAiSdkInstrumentor {
           'experimental_telemetry: { isEnabled: true } is passed on each generateText/streamText call.'
       );
     }
-    registerTelemetry(new OpenTelemetry({ usage: true }));
+    const dispatcher = new OpenTelemetry({ usage: true, providerMetadata: true });
+    // The integration never emits the raw provider usage, the only place the
+    // written cache tokens per TTL (Anthropic's `cache_creation`) are
+    // reported; this complement stamps it on the model-call span (see
+    // get_cache_creation_telemetry).
+    const { VercelCacheCreationInstrumentor } = require('./get_cache_creation_telemetry');
+    new VercelCacheCreationInstrumentor().instrument(dispatcher);
+    registerTelemetry(dispatcher);
   }
 }
 

package/src/instrumentation/vercel/get_cache_creation_telemetry.js

@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * Cache-write capture for Vercel AI SDK (ai >= 7) model-call spans.
+ *
+ * Anthropic reports the written cache tokens per TTL in its raw usage
+ * (`usage.cache_creation`, ephemeral_5m/1h buckets — billed at different
+ * rates). ai >= 7 carries that verbatim on the model-call telemetry event as
+ * `event.usage.raw` (a documented field of LanguageModelUsage), but the
+ * `@ai-sdk/otel` integration never emits it, so the span loses it.
+ *
+ * Wrap the telemetry dispatcher's `onLanguageModelCallEnd(event)` (a public
+ * callback of the telemetry interface) to read `usage.cache_creation` off the
+ * raw usage and stamp it verbatim as `weflayr.cache.creation` on the
+ * still-open model-call span (reached through the integration's call state)
+ * before the original handler ends it; the normalizer owns the mapping to TTL
+ * tiers.
+ */
+
+const CACHE_CREATION_ATTR = 'weflayr.cache.creation';
+
+// The raw `usage.cache_creation` of a provider usage, or undefined when the
+// provider reports none (or reports only zeros — non-caching calls carry no
+// attribute).
+function cacheCreationFromRawUsage(rawUsage) {
+  const cacheCreation = rawUsage && rawUsage.cache_creation;
+  if (!cacheCreation) return undefined;
+  return Object.values(cacheCreation).some(Boolean) ? cacheCreation : undefined;
+}
+
+class VercelCacheCreationInstrumentor {
+  constructor() {
+    // [owner, methodName, originalFunction] for uninstrument().
+    this._patched = [];
+  }
+
+  // No-op (and never throws) if the interface is missing — the worst case is
+  // the cache-write capture staying empty, exactly the pre-complement
+  // behaviour.
+  instrument(dispatcher) {
+    if (!dispatcher || typeof dispatcher.onLanguageModelCallEnd !== 'function') return;
+    const original = dispatcher.onLanguageModelCallEnd;
+
+    dispatcher.onLanguageModelCallEnd = function onLanguageModelCallEndWithCacheCreation(event) {
+      try {
+        const cacheCreation = cacheCreationFromRawUsage(event && event.usage && event.usage.raw);
+        if (cacheCreation) {
+          const callState = this.getCallState && this.getCallState(event.callId);
+          const span = callState && callState.inferenceSpan;
+          if (span && typeof span.setAttribute === 'function') {
+            span.setAttribute(CACHE_CREATION_ATTR, JSON.stringify(cacheCreation));
+          }
+        }
+      } catch {
+        // Never break span finalization over an enrichment failure.
+      }
+      return original.call(this, event);
+    };
+    this._patched.push([dispatcher, 'onLanguageModelCallEnd', original]);
+  }
+
+  uninstrument() {
+    for (const [owner, methodName, original] of this._patched) {
+      owner[methodName] = original;
+    }
+    this._patched = [];
+  }
+}
+
+module.exports = { VercelCacheCreationInstrumentor, cacheCreationFromRawUsage };

package/src/otel/propagation.js

@@ -6,7 +6,7 @@
 // This file has been modified from its original form:
 //   - Translated from TypeScript to JavaScript
 //   - Replaced Langfuse's fixed schema with Weflayr's structured metadata
-//     (featureName, customerName, providerName, extraTags) plus an
+//     (featureName, customerName, providerNameOverride, extraTags) plus an
 //     auto-generated per-call uuid
 //   - Removed asBaggage cross-process propagation (not needed yet)
 //   - Removed experiment framework keys
@@ -36,7 +36,13 @@ function getMergedMetadataFromContext(parentContext) {
   return existing && typeof existing === 'object' ? { ...existing } : {};
 }
 
-function _buildAttributes({ featureName, customerName, providerName, extraTags, spanUuid }) {
+function _buildAttributes({
+  featureName,
+  customerName,
+  providerNameOverride,
+  extraTags,
+  spanUuid,
+}) {
   const attributes = {
     [FEATURE_NAME_ATTR]: featureName,
     [CUSTOMER_NAME_ATTR]: customerName,
@@ -45,8 +51,8 @@ function _buildAttributes({ featureName, customerName, providerName, extraTags,
   for (const [key, value] of Object.entries(extraTags)) {
     attributes[`${EXTRA_TAG_PREFIX}${key}`] = value;
   }
-  if (providerName !== undefined && providerName !== null) {
-    attributes[PROVIDER_NAME_ATTR] = providerName;
+  if (providerNameOverride !== undefined && providerNameOverride !== null) {
+    attributes[PROVIDER_NAME_ATTR] = providerNameOverride;
   }
   return attributes;
 }
@@ -62,8 +68,8 @@ function _buildAttributes({ featureName, customerName, providerName, extraTags,
  * propagateMetadata call" contract.
  */
 function propagateMetadata(options, fn) {
-  const { featureName, customerId } = options ?? {};
-  let { customerName } = options ?? {};
+  const { featureName, customerId, providerName } = options ?? {};
+  let { customerName, providerNameOverride } = options ?? {};
   if (customerId != null) {
     process.emitWarning(
       'propagateMetadata: `customerId` is deprecated, use `customerName`',
@@ -71,10 +77,17 @@ function propagateMetadata(options, fn) {
     );
     customerName = customerName ?? customerId;
   }
+  if (providerName != null) {
+    process.emitWarning(
+      'propagateMetadata: `providerName` is deprecated, use `providerNameOverride`',
+      'DeprecationWarning'
+    );
+    providerNameOverride = providerNameOverride ?? providerName;
+  }
   if (featureName == null || customerName == null) {
     throw new Error('propagateMetadata: `featureName` and `customerName` are required');
   }
-  const normalizedOptions = { ...options, customerName };
+  const normalizedOptions = { ...options, customerName, providerNameOverride };
 
   if (typeof fn === 'function') {
     return _runWithMetadata(normalizedOptions, fn);
@@ -98,11 +111,11 @@ function propagateMetadata(options, fn) {
 }
 
 function _runWithMetadata(options, fn) {
-  const { featureName, customerName, providerName, extraTags } = options;
+  const { featureName, customerName, providerNameOverride, extraTags } = options;
   const attributes = _buildAttributes({
     featureName,
     customerName,
-    providerName,
+    providerNameOverride,
     extraTags: extraTags ?? {},
     spanUuid: randomUUID().replace(/-/g, ''),
   });