dd-trace 6.17.0 → 6.18.0

package/packages/dd-trace/src/llmobs/prompts/prompt.js

@@ -1,7 +1,43 @@
 'use strict'
 
+/** @typedef {import('../../../../../index').llmobs.FormattedPromptMessage} FormattedPromptMessage */
+
 const VARIABLE_PATTERN = /(?<!\{)(?:\{\{\s*(\w+)\s*\}\}(?!\})|\{\s*(\w+)\s*\}(?!\}))/g
 
+function isMessage (value) {
+  return typeof value?.role === 'string' &&
+    value?.type !== 'placeholder' &&
+    (value?.content == null || typeof value.content === 'string') &&
+    (typeof value?.content === 'string' ||
+      (Array.isArray(value?.tool_calls) && value.tool_calls.length > 0) ||
+      (Array.isArray(value?.tool_results) && value.tool_results.length > 0))
+}
+
+function isPlaceholder (value) {
+  return value?.type === 'placeholder' && typeof value?.name === 'string'
+}
+
+function isObject (value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isTool (value) {
+  return isObject(value) &&
+    (value.id == null || typeof value.id === 'string') &&
+    (value.type == null || typeof value.type === 'string') &&
+    (value.tool_id == null || typeof value.tool_id === 'string') &&
+    (value.name == null || typeof value.name === 'string')
+}
+
+function hasValidTools (message) {
+  return (message.tool_call_id == null || typeof message.tool_call_id === 'string') &&
+    (message.tool_calls == null || (Array.isArray(message.tool_calls) && message.tool_calls.every(call =>
+      isTool(call) && (call.function == null ||
+        (isObject(call.function) &&
+          typeof call.function.name === 'string' && typeof call.function.arguments === 'string'))))) &&
+    (message.tool_results == null || (Array.isArray(message.tool_results) && message.tool_results.every(isTool)))
+}
+
 function render (template, variables) {
   return template.replaceAll(VARIABLE_PATTERN, (match, doubleName, singleName) => {
     const name = doubleName ?? singleName
@@ -9,23 +45,40 @@ function render (template, variables) {
   })
 }
 
+function freezeConfig (config) {
+  if (config === undefined) return Object.freeze({})
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new TypeError('Invalid prompt config: expected a JSON object')
+  }
+  const copy = structuredClone(config)
+  const freeze = value => {
+    if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value
+    for (const nested of Object.values(value)) freeze(nested)
+    return Object.freeze(value)
+  }
+  return freeze(copy)
+}
 class ManagedPrompt {
   /**
    * @param {object} data
    * @param {string} data.id
    * @param {string} data.version
    * @param {'registry'|'cache'|'fallback'|'ff'|'resolve'} data.source
-   * @param {string | Array<{role: string, content: string}>} data.template
+   * @param {string | Array<{role: string, content: string} | {type: 'placeholder', name: string}>} data.template
+   * @param {Record<string, unknown>} [data.config]
    * @param {string} [data.promptUuid]
    * @param {string} [data.promptVersionUuid]
    */
-  constructor ({ id, version, source, template, promptUuid, promptVersionUuid }) {
+  constructor ({ id, version, source, template, config, promptUuid, promptVersionUuid }) {
     this.id = id
     this.version = version
     this.source = source
     this.template = Array.isArray(template)
-      ? Object.freeze(template.map(message => Object.freeze({ role: message.role, content: message.content })))
+      ? Object.freeze(template.map(item => Object.freeze(isPlaceholder(item)
+        ? { type: 'placeholder', name: item.name }
+        : { role: item.role, content: item.content })))
       : template
+    this.config = freezeConfig(config)
     this.promptUuid = promptUuid
     this.promptVersionUuid = promptVersionUuid
     Object.freeze(this)
@@ -34,11 +87,21 @@ class ManagedPrompt {
   /**
    * Render the prompt without changing its stored template.
    * @param {Record<string, unknown>} [variables]
-   * @returns {string | Array<{role: string, content: string}>}
+   * @returns {string | FormattedPromptMessage[]}
    */
   format (variables = {}) {
     if (typeof this.template === 'string') return render(this.template, variables)
-    return this.template.map(message => ({ role: message.role, content: render(message.content, variables) }))
+    return this.template.flatMap(item => {
+      if (!isPlaceholder(item)) return [{ ...item, content: render(item.content, variables) }]
+      if (!Object.hasOwn(variables, item.name)) {
+        throw new TypeError(`Missing message placeholder variable '${item.name}'`)
+      }
+      const messages = variables[item.name]
+      if (!Array.isArray(messages) || !messages.every(message => isMessage(message) && hasValidTools(message))) {
+        throw new TypeError(`Invalid message placeholder variable '${item.name}': expected an array of messages`)
+      }
+      return structuredClone(messages)
+    })
   }
 
   /**
@@ -52,7 +115,10 @@ class ManagedPrompt {
       version: this.version,
       template: typeof this.template === 'string' ? this.template : this.template.map(message => ({ ...message })),
     }
-    const entries = Object.entries(variables ?? {})
+    const placeholderNames = new Set(Array.isArray(this.template)
+      ? this.template.filter(isPlaceholder).map(item => item.name)
+      : [])
+    const entries = Object.entries(variables ?? {}).filter(([name]) => !placeholderNames.has(name))
     if (entries.length) {
       annotation.variables = Object.fromEntries(entries.map(([name, value]) => [name, String(value)]))
     }
@@ -64,8 +130,8 @@ class ManagedPrompt {
   /**
    * Convert a caller fallback to a managed prompt.
    * @param {string} promptId
-   * @param {string | object | Array<{role: string, content: string}> |
-   *   (() => string | object | Array<{role: string, content: string}>)} fallback
+   * @param {string | object | Array<{role: string, content: string} | {type: 'placeholder', name: string}> |
+   *   (() => string | object | Array<{role: string, content: string} | {type: 'placeholder', name: string}>)} fallback
    * @returns {ManagedPrompt}
    */
   static fromFallback (promptId, fallback) {
@@ -73,9 +139,8 @@ class ManagedPrompt {
     const promptLike = value && !Array.isArray(value) && typeof value === 'object'
     const template = promptLike ? value.template : value
     const validTemplate = typeof template === 'string' || (
-      Array.isArray(template) && template.every(message => {
-        return message && typeof message.role === 'string' && typeof message.content === 'string'
-      })
+      Array.isArray(template) && template.every(item =>
+        isPlaceholder(item) || (isMessage(item) && typeof item.content === 'string'))
     )
     if (!validTemplate) {
       throw new TypeError('Invalid prompt fallback: expected a string, chat message array, or object with a template')
@@ -85,6 +150,7 @@ class ManagedPrompt {
       version: String(promptLike && value.version ? value.version : 'fallback'),
       source: 'fallback',
       template,
+      config: promptLike ? value.config : undefined,
     })
   }
 }

package/packages/dd-trace/src/llmobs/tagger.js

@@ -505,10 +505,13 @@ class LLMObsTagger {
     }
 
     if (Array.isArray(template)) {
-      for (const message of template) {
-        if (typeof message !== 'object' || !message.role || !message.content) {
+      for (const item of template) {
+        const valid = item?.type === 'placeholder'
+          ? typeof item.name === 'string'
+          : typeof item?.role === 'string' && typeof item?.content === 'string'
+        if (!valid) {
           this.#handleFailure(
-            'Prompt chat template must be an array of objects with role and content properties.', 'invalid_prompt'
+            'Prompt chat template must contain messages or message placeholders.', 'invalid_prompt'
           )
           return
         }
@@ -532,7 +535,9 @@ class LLMObsTagger {
     if (typeof template === 'string') {
       finalTemplate = template
     } else if (Array.isArray(template)) {
-      finalChatTemplate = template.map(message => ({ role: message.role, content: message.content }))
+      finalChatTemplate = template.map(item => item.type === 'placeholder'
+        ? { type: 'placeholder', name: item.name }
+        : { role: item.role, content: item.content })
     }
 
     const validatedPrompt = {}

package/packages/dd-trace/src/openfeature/configuration_source.js

@@ -1,5 +1,6 @@
 'use strict'
 
+const { createSiteUrl } = require('../exporters/common/url')
 const log = require('../log')
 
 const DEFAULT_AGENTLESS_PATH = '/api/v2/feature-flagging/config/rules-based/server'
@@ -60,7 +61,9 @@ function endpoint (config, configuredBaseUrl) {
   const configured = configuredBaseUrl?.trim()
 
   if (!configured) {
-    const url = new URL(`https://ufc-server.ff-cdn.${config.site.toLowerCase()}${DEFAULT_AGENTLESS_PATH}`)
+    const url = createSiteUrl(config.site, 'ufc-server.ff-cdn')
+    if (url === undefined) throw new Error('Invalid DD_SITE for Feature Flagging agentless configuration')
+    url.pathname = DEFAULT_AGENTLESS_PATH
     if (config.env) url.searchParams.set('dd_env', config.env)
     return url
   }

package/packages/dd-trace/src/openfeature/flagging_provider.js

@@ -27,12 +27,12 @@ class FlaggingProvider extends DatadogNodeServerProvider {
   constructor (tracer, config) {
     super({
       exposureChannel: channel(EXPOSURE_CHANNEL),
-      initializationTimeoutMs: config.experimental.flaggingProvider.initializationTimeoutMs,
+      initializationTimeoutMs: config.featureFlags.DD_EXPERIMENTAL_FLAGGING_PROVIDER_INITIALIZATION_TIMEOUT_MS,
     })
 
     this.hooks.push(new EvalMetricsHook(config))
 
-    if (config.experimental.flaggingProvider.spanEnrichment?.enabled) {
+    if (config.featureFlags.DD_EXPERIMENTAL_FLAGGING_PROVIDER_SPAN_ENRICHMENT_ENABLED) {
       this.#spanEnrichmentHook = new SpanEnrichmentHook(tracer)
       // @ts-expect-error The upstream constructor always initializes its optional hooks property.
       this.hooks.push(this.#spanEnrichmentHook)
@@ -42,7 +42,7 @@ class FlaggingProvider extends DatadogNodeServerProvider {
     }
 
     log.debug('%s created with timeout: %dms', this.constructor.name,
-      config.experimental.flaggingProvider.initializationTimeoutMs)
+      config.featureFlags.DD_EXPERIMENTAL_FLAGGING_PROVIDER_INITIALIZATION_TIMEOUT_MS)
 
     this.#configurationSource = configurationSource.create(config, this.setConfiguration.bind(this))
     this.#configurationSource?.start()

package/packages/dd-trace/src/openfeature/index.js

@@ -3,12 +3,13 @@
 const { channel } = require('dc-polyfill')
 const log = require('../log')
 const ExposuresWriter = require('./writers/exposures')
-const { setExposureDeliveryStrategy } = require('./writers/util')
+const { setEventDeliveryStrategy } = require('./writers/util')
 
 const exposureSubmitCh = channel('ffe:exposure:submit')
 const flushCh = channel('ffe:writers:flush')
 
 let exposuresWriter = null
+let stopEventDeliveryStrategy
 
 /**
  * @private
@@ -42,7 +43,7 @@ function enable (config) {
   exposureSubmitCh.subscribe(_handleExposureSubmit)
   flushCh.subscribe(_handleFlush)
 
-  setExposureDeliveryStrategy(config, (enabled, route) => {
+  stopEventDeliveryStrategy = setEventDeliveryStrategy(config, (enabled, route) => {
     if (exposuresWriter !== writer) return
 
     writer.setEnabled(enabled, route)
@@ -55,6 +56,9 @@ function enable (config) {
 function disable () {
   if (!exposuresWriter) return
 
+  stopEventDeliveryStrategy?.()
+  stopEventDeliveryStrategy = undefined
+
   if (exposureSubmitCh.hasSubscribers) {
     exposureSubmitCh.unsubscribe(_handleExposureSubmit)
   }

package/packages/dd-trace/src/openfeature/writers/base.js

@@ -1,9 +1,14 @@
 'use strict'
 
 const request = require('../../exporters/common/request')
-const { safeJSONStringify } = require('../../exporters/common/util')
 
 const log = require('../../log')
+const tracerVersion = require('../../../../../package.json').version
+
+const EVP_ORIGIN_HEADERS = {
+  'DD-EVP-ORIGIN': 'dd-trace-js',
+  'DD-EVP-ORIGIN-VERSION': tracerVersion,
+}
 
 /**
  * @typedef {object} BaseFFEWriterOptions
@@ -23,6 +28,8 @@ const log = require('../../log')
  * @property {string} endpoint - Route endpoint
  * @property {object} headers - Route-specific headers
  * @property {import('node:https').Agent} [agent] - Optional HTTPS proxy agent
+ * @property {Function} [onFallback] - Called after direct fallback becomes active
+ * @property {Function} [onUnavailable] - Called after the local route becomes unavailable
  */
 
 /**
@@ -30,6 +37,8 @@ const log = require('../../log')
  * @property {URL} url - Route base URL
  * @property {string} endpoint - Route endpoint
  * @property {object} requestOptions - HTTP request options
+ * @property {Function} [onFallback] - Called after direct fallback becomes active
+ * @property {Function} [onUnavailable] - Called after the local route becomes unavailable
  */
 
 /**
@@ -38,19 +47,31 @@ const log = require('../../log')
  * @param {Error | null} error - Request error
  * @param {number | undefined} statusCode - HTTP response status
  */
-function isDefinitiveRejection (error, statusCode) {
+function isSafeToReplay (error, statusCode) {
   return error?.code === 'EAI_AGAIN' || error?.code === 'ECONNREFUSED' ||
     error?.code === 'ENOENT' || error?.code === 'ENOTFOUND' ||
-    statusCode === 403 || statusCode === 404 || statusCode === 405
+    statusCode === 404 || statusCode === 405
 }
 
 /**
- * Tests whether a local route can have accepted an event batch before failing.
+ * Tests whether a local route failed without an authoritative HTTP response.
  *
  * @param {Error | null} error - Request error
+ * @param {number | undefined} statusCode - HTTP response status
+ */
+function isTransportFailure (error, statusCode) {
+  // SDK backpressure says nothing about the local receiver's health.
+  return error !== null && error !== undefined && statusCode === undefined &&
+    error.code !== 'ERR_DD_REQUEST_BUFFER_FULL'
+}
+
+/**
+ * Tests whether an HTTP response should move only future Agentless batches.
+ *
+ * @param {number | undefined} statusCode - HTTP response status
  */
-function isAmbiguousNetworkFailure (error) {
-  return error?.code === 'ECONNRESET' || error?.code === 'EPIPE' || error?.code === 'ETIMEDOUT'
+function shouldSwitchFutureRoute (statusCode) {
+  return statusCode === 403 || statusCode === 429 || statusCode >= 500 && statusCode < 600
 }
 
 /**
@@ -81,10 +102,11 @@ class BaseFFEWriter {
     this._requestOptions = {
       headers: {
         ...this._headers,
+        ...EVP_ORIGIN_HEADERS,
         'Content-Type': 'application/json',
       },
       method: 'POST',
-      retry: true,
+      retry: false,
       timeout: this._timeout,
       url: this._baseUrl,
       path: this._endpoint,
@@ -150,11 +172,10 @@ class BaseFFEWriter {
 
     const payload = this._encode(this.makePayload(events))
 
+    // Keep byte counting behind the debug callback because payloads can be several megabytes.
     // eslint-disable-next-line eslint-rules/eslint-log-printf-style
-    log.debug(() => `${this.constructor.name} flushing payload: ${safeJSONStringify(payload)}`)
-
-    const route = this.#createActiveRoute()
-    this.#sendRequest(payload, events.length, route, this._fallbackRoute)
+    log.debug(() => `${this.constructor.name} flushing ${events.length} events (${Buffer.byteLength(payload)} bytes)`)
+    this._sendPayload(payload, events.length)
   }
 
   /**
@@ -192,6 +213,18 @@ class BaseFFEWriter {
     return JSON.stringify(payload)
   }
 
+  /**
+   * Sends one encoded event batch through a snapshot of the selected routes.
+   *
+   * @protected
+   * @param {string} payload - Encoded event batch
+   * @param {number} eventCount - Event count
+   */
+  _sendPayload (payload, eventCount) {
+    const route = this.#createActiveRoute()
+    this.#sendRequest(payload, eventCount, route, this._fallbackRoute)
+  }
+
   /**
    * Applies the active route and an optional direct fallback route.
    *
@@ -213,10 +246,11 @@ class BaseFFEWriter {
     const requestOptions = {
       headers: {
         ...route.headers,
+        ...EVP_ORIGIN_HEADERS,
         'Content-Type': 'application/json',
       },
       method: 'POST',
-      retry: true,
+      retry: false,
       timeout: this._timeout,
       url: route.url,
       path: route.endpoint,
@@ -227,6 +261,8 @@ class BaseFFEWriter {
       url: route.url,
       endpoint: route.endpoint,
       requestOptions,
+      onFallback: route.onFallback,
+      onUnavailable: route.onUnavailable,
     }
   }
 
@@ -240,6 +276,8 @@ class BaseFFEWriter {
       url: this._baseUrl,
       endpoint: this._endpoint,
       requestOptions: this._requestOptions,
+      onFallback: this._onFallback,
+      onUnavailable: this._onUnavailable,
     }
   }
 
@@ -252,10 +290,12 @@ class BaseFFEWriter {
     this._baseUrl = route.url
     this._endpoint = route.endpoint
     this._requestOptions = route.requestOptions
+    this._onFallback = route.onFallback
+    this._onUnavailable = route.onUnavailable
   }
 
   /**
-   * Sends an encoded batch and retries it through direct intake after a local route failure.
+   * Sends an encoded batch once per route and applies safe local fallback semantics.
    *
    * @param {string} payload - Encoded event batch
    * @param {number} eventCount - Event count
@@ -264,7 +304,7 @@ class BaseFFEWriter {
    */
   #sendRequest (payload, eventCount, route, fallbackRoute) {
     request(payload, route.requestOptions, (error, response, statusCode) => {
-      if (fallbackRoute && isDefinitiveRejection(error, statusCode)) {
+      if (fallbackRoute && isSafeToReplay(error, statusCode)) {
         log.debug(
           '%s switching from %s%s to direct intake after definitive rejection',
           this.constructor.name,
@@ -273,20 +313,53 @@ class BaseFFEWriter {
         )
         this.#activateRoute(fallbackRoute)
         this._fallbackRoute = undefined
+        route.onFallback?.()
         this.#sendRequest(payload, eventCount, fallbackRoute)
         return
       }
 
-      if (fallbackRoute && isAmbiguousNetworkFailure(error)) {
+      if (fallbackRoute && isTransportFailure(error, statusCode)) {
         log.debug(
-          '%s retrying through direct intake and switching future batches from %s%s after ambiguous failure',
+          '%s switching future batches from %s%s to direct intake after an ambiguous failure without replay',
           this.constructor.name,
           route.url.href,
           route.endpoint
         )
         this.#activateRoute(fallbackRoute)
         this._fallbackRoute = undefined
-        this.#sendRequest(payload, eventCount, fallbackRoute)
+        route.onFallback?.()
+        log.error('Failed to send events to %s%s: %s', route.url.href, route.endpoint, error.message)
+        return
+      }
+
+      if (fallbackRoute && shouldSwitchFutureRoute(statusCode)) {
+        log.debug(
+          '%s switching future batches from %s%s to direct intake after status %d without replay',
+          this.constructor.name,
+          route.url.href,
+          route.endpoint,
+          statusCode
+        )
+        this.#activateRoute(fallbackRoute)
+        this._fallbackRoute = undefined
+        route.onFallback?.()
+        log.warn('Events request returned status %d', statusCode)
+        return
+      }
+
+      if (
+        !fallbackRoute &&
+        route.onUnavailable &&
+        (isSafeToReplay(error, statusCode) ||
+          isTransportFailure(error, statusCode) ||
+          shouldSwitchFutureRoute(statusCode))
+      ) {
+        route.onUnavailable()
+        if (error) {
+          log.error('Failed to send events to %s%s: %s', route.url.href, route.endpoint, error.message)
+        } else {
+          log.warn('Events request returned status %d', statusCode)
+        }
         return
       }
 

package/packages/dd-trace/src/openfeature/writers/exposures.js

@@ -26,6 +26,8 @@ const PENDING_MAX_EVENTS = 1000
  * @property {object} [headers] - Route-specific headers
  * @property {import('node:https').Agent} [agent] - Optional HTTPS proxy agent
  * @property {ExposureRoute} [fallback] - Optional direct fallback route
+ * @property {Function} [onFallback] - Called after direct fallback becomes active
+ * @property {Function} [onUnavailable] - Called after the local route becomes unavailable
  */
 
 /**
@@ -150,6 +152,8 @@ class ExposuresWriter extends BaseFFEWriter {
       endpoint: joinEVPProxyPath(route.basePath, EXPOSURES_ENDPOINT),
       headers,
       agent: route.agent,
+      onFallback: route.onFallback,
+      onUnavailable: route.onUnavailable,
     }, fallbackRoute)
   }