weflayr 0.23.0 → 0.24.0

package/tests/index.test.js

@@ -234,22 +234,32 @@ test('buildExporter does not warn when warnOnExportError is false', async () =>
 
 // ── span-filter ───────────────────────────────────────────────────────────────
 
-test('isDefaultExportSpan accepts spans with gen_ai.* attributes', () => {
+test('isDefaultExportSpan accepts spans from known instrumentation scopes', () => {
   const span = makeFakeSpan({
-    attributes: { 'gen_ai.system': 'openai' },
-    instrumentationScope: { name: 'unknown' },
+    attributes: {},
+    instrumentationScope: { name: 'opentelemetry.instrumentation.openai' },
   });
   assert.equal(isDefaultExportSpan(span), true);
 });
 
-test('isDefaultExportSpan accepts spans from known instrumentation scopes', () => {
+test('isDefaultExportSpan accepts weflayr instrumentation spans', () => {
   const span = makeFakeSpan({
     attributes: {},
-    instrumentationScope: { name: 'opentelemetry.instrumentation.openai' },
+    instrumentationScope: { name: 'weflayr.instrumentation.openai_audio' },
   });
   assert.equal(isDefaultExportSpan(span), true);
 });
 
+test('isDefaultExportSpan rejects gen_ai spans from unknown scopes', () => {
+  // APM SDKs (Sentry, Datadog, ...) also instrument LLM calls with gen_ai.*
+  // attributes — exporting them would duplicate the instrumentor's span.
+  const span = makeFakeSpan({
+    attributes: { 'gen_ai.system': 'openai' },
+    instrumentationScope: { name: '@sentry/node' },
+  });
+  assert.equal(isDefaultExportSpan(span), false);
+});
+
 test('isDefaultExportSpan rejects unrelated spans', () => {
   const span = makeFakeSpan({
     attributes: { 'http.method': 'GET' },
@@ -335,6 +345,26 @@ test('WeflayrSpanProcessor applies mask before export', async () => {
   assert.equal(span.attributes['gen_ai.prompt'], '[REDACTED]');
 });
 
+test('WeflayrSpanProcessor stamps mask function source on exported spans', async () => {
+  const exporter = makeExporterStub();
+  const mask = (attrs) => attrs;
+  const proc = new WeflayrSpanProcessor({ exporter, exportMode: 'immediate', mask });
+  const span = makeFakeSpan({ attributes: { 'gen_ai.system': 'openai' } });
+  proc.onEnd(span);
+  await proc.forceFlush();
+  const maskFunctionSource = exporter.exported[0].attributes['weflayr.mask_function'];
+  assert.ok(maskFunctionSource.includes('(attrs) => attrs'));
+});
+
+test('WeflayrSpanProcessor omits mask function attribute without mask', async () => {
+  const exporter = makeExporterStub();
+  const proc = new WeflayrSpanProcessor({ exporter, exportMode: 'immediate' });
+  const span = makeFakeSpan({ attributes: { 'gen_ai.system': 'openai' } });
+  proc.onEnd(span);
+  await proc.forceFlush();
+  assert.equal(exporter.exported[0].attributes['weflayr.mask_function'], undefined);
+});
+
 test('WeflayrSpanProcessor strips message content when capture disabled', async () => {
   // Instrumentors gate content on their own env vars (openllmetry captures by
   // default), so the processor itself must drop message content when
@@ -395,7 +425,7 @@ function _makeMetadataHarness() {
   const exporter = makeExporterStub();
   const proc = new WeflayrSpanProcessor({ exporter, exportMode: 'immediate' });
   const provider = new BasicTracerProvider({ spanProcessors: [proc] });
-  const tracer = provider.getTracer('test');
+  const tracer = provider.getTracer('opentelemetry.instrumentation.openai');
   return { exporter, proc, provider, tracer };
 }
 
@@ -558,9 +588,34 @@ test('propagateMetadata callable form runs function', async () => {
   await provider.shutdown();
 });
 
-test('propagateMetadata providerName writes attribute', async () => {
+test('propagateMetadata providerNameOverride writes attribute', async () => {
+  const { exporter, proc, provider, tracer } = _makeMetadataHarness();
+
+  await weflayr.propagateMetadata(
+    {
+      featureName: 'f',
+      customerName: 'c',
+      providerNameOverride: weflayr.AIProviderName.VERCEL_AI_GATEWAY,
+    },
+    async () => {
+      const span = tracer.startSpan('child');
+      span.setAttribute('gen_ai.system', 'openai');
+      span.end();
+    }
+  );
+
+  await proc.forceFlush();
+  assert.equal(exporter.exported[0].attributes['weflayr.provider_name'], 'vercel_ai_gateway');
+  await provider.shutdown();
+});
+
+test('propagateMetadata deprecated providerName still works', async () => {
   const { exporter, proc, provider, tracer } = _makeMetadataHarness();
 
+  const warnings = [];
+  const onWarning = (warning) => warnings.push(warning);
+  process.on('warning', onWarning);
+
   await weflayr.propagateMetadata(
     {
       featureName: 'f',
@@ -574,6 +629,11 @@ test('propagateMetadata providerName writes attribute', async () => {
     }
   );
 
+  // process.emitWarning delivers on a later tick; drain it before asserting.
+  await new Promise((resolve) => process.nextTick(resolve));
+  process.removeListener('warning', onWarning);
+  assert.ok(warnings.some((warning) => /providerName.*deprecated/.test(warning.message)));
+
   await proc.forceFlush();
   assert.equal(exporter.exported[0].attributes['weflayr.provider_name'], 'vercel_ai_gateway');
   await provider.shutdown();

package/tests/instrumentation/anthropic/get_cache_and_reasoning_telemetry.test.js

@@ -63,6 +63,29 @@ test('stamps cache read on a warm call', () => {
   assert.equal(span.attrs['gen_ai.usage.cache_creation_input_tokens'], undefined);
 });
 
+test('stamps usage.cache_creation verbatim', () => {
+  const instrumentation = { _endSpan() {} };
+  new AnthropicPromptCachingInstrumentor().instrument(instrumentation);
+
+  const span = fakeSpan();
+  instrumentation._endSpan({
+    span,
+    type: 'completion',
+    result: {
+      usage: {
+        input_tokens: 10,
+        cache_creation_input_tokens: 5300,
+        cache_creation: { ephemeral_5m_input_tokens: 4000, ephemeral_1h_input_tokens: 1300 },
+      },
+    },
+  });
+
+  assert.deepEqual(JSON.parse(span.attrs['weflayr.cache.creation']), {
+    ephemeral_5m_input_tokens: 4000,
+    ephemeral_1h_input_tokens: 1300,
+  });
+});
+
 test('sets nothing for an uncached call', () => {
   const instrumentation = { _endSpan() {} };
   new AnthropicPromptCachingInstrumentor().instrument(instrumentation);

package/tests/instrumentation/anthropic/get_cache_config_telemetry.test.js

@@ -0,0 +1,92 @@
+'use strict';
+
+// Tests for the Anthropic request-side cache_control breakpoint capture.
+//
+// The traceloop instrumentation instance is stubbed with a `startSpan` that
+// returns a fake span, so the wrap can be exercised without the real SDK.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  AnthropicCacheConfigInstrumentor,
+  extractCacheBreakpoints,
+} = require('../../../src/instrumentation/anthropic/get_cache_config_telemetry');
+
+function makeFakeSpan() {
+  const attributes = {};
+  return {
+    attributes,
+    setAttribute(key, value) {
+      attributes[key] = value;
+    },
+  };
+}
+
+function makeStubInstrumentation() {
+  return {
+    startSpan() {
+      return makeFakeSpan();
+    },
+  };
+}
+
+test('stamps breakpoints from system, message content and tools', () => {
+  const instrumentation = makeStubInstrumentation();
+  new AnthropicCacheConfigInstrumentor().instrument(instrumentation);
+
+  const span = instrumentation.startSpan({
+    type: 'chat',
+    params: {
+      system: [{ type: 'text', text: 'big prefix', cache_control: { type: 'ephemeral' } }],
+      messages: [
+        { role: 'user', content: 'plain string content' },
+        {
+          role: 'user',
+          content: [{ type: 'text', text: 'doc', cache_control: { type: 'ephemeral', ttl: '1h' } }],
+        },
+      ],
+      tools: [
+        { name: 'get_weather', cache_control: { type: 'ephemeral' } },
+        { name: 'uncached_tool' },
+      ],
+    },
+  });
+
+  assert.deepEqual(JSON.parse(span.attributes['weflayr.cache.breakpoints']), [
+    { location: 'system' },
+    { location: 'messages[1]', ttl: '1h' },
+    { location: 'tools[0]' },
+  ]);
+});
+
+test('no attribute without breakpoints', () => {
+  const instrumentation = makeStubInstrumentation();
+  new AnthropicCacheConfigInstrumentor().instrument(instrumentation);
+
+  const span = instrumentation.startSpan({
+    type: 'chat',
+    params: { messages: [{ role: 'user', content: 'hello' }] },
+  });
+
+  assert.ok(!('weflayr.cache.breakpoints' in span.attributes));
+});
+
+test('extractCacheBreakpoints omits the ttl when the request sets none', () => {
+  assert.deepEqual(
+    extractCacheBreakpoints({
+      system: [{ type: 'text', text: 'p', cache_control: { type: 'ephemeral' } }],
+    }),
+    [{ location: 'system' }]
+  );
+});
+
+test('uninstrument restores the original startSpan', () => {
+  const instrumentation = makeStubInstrumentation();
+  const original = instrumentation.startSpan;
+  const instrumentor = new AnthropicCacheConfigInstrumentor();
+  instrumentor.instrument(instrumentation);
+  assert.notEqual(instrumentation.startSpan, original);
+  instrumentor.uninstrument();
+  assert.equal(instrumentation.startSpan, original);
+});

package/tests/instrumentation/anthropic/get_tool_definitions_telemetry.test.js

@@ -52,6 +52,21 @@ test('stamps tool definitions from the request params', () => {
   assert.deepEqual(JSON.parse(span.attributes['gen_ai.tool.definitions']), [WEATHER_TOOL]);
 });
 
+test('drops cache_control from the stamped tool definitions', () => {
+  const instrumentation = makeStubInstrumentation();
+  new AnthropicToolDefinitionsInstrumentor().instrument(instrumentation);
+
+  const span = instrumentation.startSpan({
+    type: 'chat',
+    params: {
+      model: 'claude-haiku-4-5',
+      tools: [{ ...WEATHER_TOOL, cache_control: { type: 'ephemeral', ttl: '1h' } }],
+    },
+  });
+
+  assert.deepEqual(JSON.parse(span.attributes['gen_ai.tool.definitions']), [WEATHER_TOOL]);
+});
+
 test('no attribute when the request has no tools', () => {
   const instrumentation = makeStubInstrumentation();
   new AnthropicToolDefinitionsInstrumentor().instrument(instrumentation);

package/tests/instrumentation/bedrock/get_cache_config_telemetry.test.js

@@ -0,0 +1,107 @@
+'use strict';
+
+// Tests for the Bedrock request-side cache breakpoint capture.
+//
+// The extractor reads both body schemas an InvokeModel request can carry:
+// Anthropic-on-Bedrock `cache_control` blocks and Amazon Nova `cachePoint`
+// blocks (attached to a content block or standing alone). The traceloop
+// instrumentation instance is stubbed with a `_startSpan` returning a fake
+// span, so the wrap can be exercised without the real SDK.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  BedrockCacheConfigInstrumentor,
+  extractBedrockCacheBreakpoints,
+} = require('../../../src/instrumentation/bedrock/get_cache_config_telemetry');
+
+function makeFakeSpan() {
+  const attributes = {};
+  return {
+    attributes,
+    setAttribute(key, value) {
+      attributes[key] = value;
+    },
+  };
+}
+
+function makeStubInstrumentation() {
+  return {
+    _startSpan() {
+      return makeFakeSpan();
+    },
+  };
+}
+
+test('extracts nova cache points', () => {
+  const body = {
+    system: [{ text: 'sys' }, { cachePoint: { type: 'default' } }],
+    messages: [
+      {
+        role: 'user',
+        content: [
+          { text: 'big prefix', cachePoint: { type: 'default' } },
+          { text: 'Reply with OK.' },
+        ],
+      },
+    ],
+    toolConfig: {
+      tools: [
+        { toolSpec: { name: 'get_weather' } },
+        { cachePoint: { type: 'default', ttl: '1h' } },
+      ],
+    },
+  };
+  assert.deepEqual(extractBedrockCacheBreakpoints(body), [
+    { location: 'system' },
+    { location: 'messages[0]' },
+    { location: 'tools[1]', ttl: '1h' },
+  ]);
+});
+
+test('extracts anthropic-on-bedrock cache_control', () => {
+  const body = {
+    anthropic_version: 'bedrock-2023-05-31',
+    system: [{ type: 'text', text: 'big prefix', cache_control: { type: 'ephemeral', ttl: '1h' } }],
+    messages: [{ role: 'user', content: 'Reply with OK.' }],
+  };
+  assert.deepEqual(extractBedrockCacheBreakpoints(body), [{ location: 'system', ttl: '1h' }]);
+});
+
+test('no breakpoints without cache blocks', () => {
+  assert.deepEqual(
+    extractBedrockCacheBreakpoints({ messages: [{ role: 'user', content: 'hello' }] }),
+    []
+  );
+});
+
+test('stamps breakpoints from the request body', () => {
+  const instrumentation = makeStubInstrumentation();
+  new BedrockCacheConfigInstrumentor().instrument(instrumentation);
+
+  const span = instrumentation._startSpan({
+    params: {
+      input: {
+        modelId: 'amazon.nova-micro-v1:0',
+        body: JSON.stringify({
+          messages: [{ role: 'user', content: [{ text: 'p', cachePoint: { type: 'default' } }] }],
+        }),
+      },
+    },
+  });
+
+  assert.deepEqual(JSON.parse(span.attributes['weflayr.cache.breakpoints']), [
+    { location: 'messages[0]' },
+  ]);
+});
+
+test('uninstrument restores the original _startSpan', () => {
+  const instrumentation = makeStubInstrumentation();
+  const original = instrumentation._startSpan;
+  const instrumentor = new BedrockCacheConfigInstrumentor();
+  instrumentor.instrument(instrumentation);
+  assert.notEqual(instrumentation._startSpan, original);
+  instrumentor.uninstrument();
+  assert.equal(instrumentation._startSpan, original);
+});

package/tests/instrumentation/bedrock/get_cache_telemetry.test.js

@@ -32,6 +32,22 @@ function passthroughInstrumentation() {
   return { _wrapPromise: (_span, promise) => Promise.resolve(promise) };
 }
 
+test('stamps cache write from an anthropic-on-bedrock usage shape', () => {
+  const instrumentation = { _wrapPromise: (span, promise) => promise };
+  new BedrockPromptCachingInstrumentor().instrument(instrumentation);
+
+  const span = fakeSpan();
+  const body = new TextEncoder().encode(
+    JSON.stringify({
+      usage: { input_tokens: 10, cache_creation_input_tokens: 5300, cache_read_input_tokens: 0 },
+    })
+  );
+  return instrumentation._wrapPromise(span, Promise.resolve({ body })).then(() => {
+    assert.equal(span.attrs['gen_ai.usage.cache_creation_input_tokens'], 5300);
+    assert.equal(span.attrs['gen_ai.usage.cache_read_input_tokens'], undefined);
+  });
+});
+
 test('stamps cache read/write from a buffered InvokeModel body', async () => {
   const instrumentation = passthroughInstrumentation();
   new BedrockPromptCachingInstrumentor().instrument(instrumentation);

package/tests/instrumentation/google/get_cache_operations_telemetry.test.js

@@ -0,0 +1,130 @@
+'use strict';
+
+// Tests for the Google GenAI explicit-cache lifecycle telemetry.
+//
+// The @google/genai `Caches` class is stubbed with prototype
+// create/update/delete methods mirroring the SDK shape.
+// `instrumentCacheOperations(Caches, patched)` wraps them and pushes the
+// restore tuples onto `patched`.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { trace, SpanStatusCode } = require('@opentelemetry/api');
+const {
+  BasicTracerProvider,
+  InMemorySpanExporter,
+  SimpleSpanProcessor,
+} = require('@opentelemetry/sdk-trace-base');
+
+const {
+  instrumentCacheOperations,
+} = require('../../../src/instrumentation/google/get_cache_operations_telemetry');
+
+const exporter = new InMemorySpanExporter();
+trace.setGlobalTracerProvider(
+  new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(exporter)] })
+);
+
+const CACHED_CONTENT = {
+  name: 'cachedContents/abc123',
+  expireTime: '2026-07-16T14:00:00Z',
+  usageMetadata: { totalTokenCount: 5300 },
+};
+
+class StubCaches {
+  create(params = {}) {
+    if (params.model === 'boom') return Promise.reject(new Error('api error'));
+    return Promise.resolve(CACHED_CONTENT);
+  }
+
+  update() {
+    return Promise.resolve(CACHED_CONTENT);
+  }
+
+  delete() {
+    return Promise.resolve({});
+  }
+}
+
+function instrumented() {
+  const patched = [];
+  instrumentCacheOperations(StubCaches, patched);
+  return () => {
+    for (const [owner, methodName, original] of patched) owner[methodName] = original;
+    exporter.reset();
+  };
+}
+
+test('create span carries cache facts and content', async () => {
+  const teardown = instrumented();
+  try {
+    await new StubCaches().create({
+      model: 'models/gemini-2.5-flash',
+      config: {
+        contents: ['a very large document to cache'],
+        systemInstruction: 'Answer from the document.',
+        ttl: '3600s',
+      },
+    });
+
+    const [span] = exporter.getFinishedSpans();
+    assert.equal(span.name, 'cache_create');
+    assert.equal(span.attributes['gen_ai.system'], 'gemini');
+    assert.equal(span.attributes['gen_ai.request.model'], 'gemini-2.5-flash');
+    assert.equal(span.attributes['weflayr.cache.operation'], 'create');
+    assert.equal(span.attributes['weflayr.cache.cached_content_id'], 'cachedContents/abc123');
+    assert.equal(span.attributes['weflayr.cache.expire_time'], '2026-07-16T14:00:00Z');
+    assert.equal(span.attributes['gen_ai.usage.input_tokens'], 5300);
+    assert.deepEqual(JSON.parse(span.attributes['gen_ai.input.messages']), [
+      { role: 'user', parts: [{ type: 'text', content: 'a very large document to cache' }] },
+    ]);
+    assert.deepEqual(JSON.parse(span.attributes['gen_ai.system_instructions']), [
+      { type: 'text', content: 'Answer from the document.' },
+    ]);
+  } finally {
+    teardown();
+  }
+});
+
+test('update span carries the new expiry but no token count', async () => {
+  const teardown = instrumented();
+  try {
+    await new StubCaches().update({ name: 'cachedContents/abc123', config: { ttl: '180s' } });
+
+    const [span] = exporter.getFinishedSpans();
+    assert.equal(span.name, 'cache_update');
+    assert.equal(span.attributes['weflayr.cache.operation'], 'update');
+    assert.equal(span.attributes['weflayr.cache.expire_time'], '2026-07-16T14:00:00Z');
+    assert.ok(!('gen_ai.usage.input_tokens' in span.attributes));
+  } finally {
+    teardown();
+  }
+});
+
+test('delete span carries operation and cache id', async () => {
+  const teardown = instrumented();
+  try {
+    await new StubCaches().delete({ name: 'cachedContents/abc123' });
+
+    const [span] = exporter.getFinishedSpans();
+    assert.equal(span.name, 'cache_delete');
+    assert.equal(span.attributes['weflayr.cache.operation'], 'delete');
+    assert.equal(span.attributes['weflayr.cache.cached_content_id'], 'cachedContents/abc123');
+    assert.ok(!('gen_ai.usage.input_tokens' in span.attributes));
+  } finally {
+    teardown();
+  }
+});
+
+test('error span records status', async () => {
+  const teardown = instrumented();
+  try {
+    await assert.rejects(new StubCaches().create({ model: 'boom' }));
+
+    const [span] = exporter.getFinishedSpans();
+    assert.equal(span.status.code, SpanStatusCode.ERROR);
+  } finally {
+    teardown();
+  }
+});

package/tests/instrumentation/openai/get_cache_config_telemetry.test.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// Tests for the OpenAI request-side prompt-cache param capture.
+//
+// The traceloop instrumentation instance is stubbed with a `startSpan` that
+// returns a fake span, so the wrap can be exercised without the real SDK.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  OpenAICacheConfigInstrumentor,
+} = require('../../../src/instrumentation/openai/get_cache_config_telemetry');
+
+function makeFakeSpan() {
+  const attributes = {};
+  return {
+    attributes,
+    setAttribute(key, value) {
+      attributes[key] = value;
+    },
+  };
+}
+
+function makeStubInstrumentation() {
+  return {
+    startSpan() {
+      return makeFakeSpan();
+    },
+  };
+}
+
+test('stamps prompt cache key and retention from the request params', () => {
+  const instrumentation = makeStubInstrumentation();
+  new OpenAICacheConfigInstrumentor().instrument(instrumentation);
+
+  const span = instrumentation.startSpan({
+    type: 'chat',
+    params: {
+      model: 'gpt-4o-mini',
+      prompt_cache_key: 'session-42',
+      prompt_cache_retention: '24h',
+    },
+  });
+
+  assert.equal(span.attributes['weflayr.cache.key'], 'session-42');
+  assert.equal(span.attributes['weflayr.cache.retention'], '24h');
+});
+
+test('stamps prompt cache options ttl as the retention', () => {
+  const instrumentation = makeStubInstrumentation();
+  new OpenAICacheConfigInstrumentor().instrument(instrumentation);
+
+  const span = instrumentation.startSpan({
+    type: 'chat',
+    params: {
+      model: 'gpt-5.6',
+      prompt_cache_options: { ttl: '30m' },
+    },
+  });
+
+  assert.equal(span.attributes['weflayr.cache.retention'], '30m');
+});
+
+test('no attributes without cache params', () => {
+  const instrumentation = makeStubInstrumentation();
+  new OpenAICacheConfigInstrumentor().instrument(instrumentation);
+
+  const span = instrumentation.startSpan({ type: 'chat', params: { model: 'gpt-4o-mini' } });
+
+  assert.ok(!('weflayr.cache.key' in span.attributes));
+  assert.ok(!('weflayr.cache.retention' in span.attributes));
+});
+
+test('uninstrument restores the original startSpan', () => {
+  const instrumentation = makeStubInstrumentation();
+  const original = instrumentation.startSpan;
+  const instrumentor = new OpenAICacheConfigInstrumentor();
+  instrumentor.instrument(instrumentation);
+  assert.notEqual(instrumentation.startSpan, original);
+  instrumentor.uninstrument();
+  assert.equal(instrumentation.startSpan, original);
+});