dd-trace 6.17.0 → 6.19.0

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

@@ -77,6 +77,7 @@ function promptFromData (data, source) {
     version: String(version),
     source,
     template: template || data.chat_template || [],
+    config: data.config,
     promptUuid: data.prompt_uuid,
     promptVersionUuid: data.prompt_version_uuid || data.id || data.ID,
   })
@@ -488,6 +489,9 @@ class PromptManager {
       if (requireAppKey && !this.config.DD_APP_KEY) {
         throw new PromptAPIError(0, 'DD_APP_KEY is required for prompt write operations', ERROR_NAMES.AUTH)
       }
+      if (body?.config !== undefined && !isPlainObject(body.config)) {
+        throw new PromptAPIError(0, 'config must be a JSON object', ERROR_NAMES.VALIDATION)
+      }
 
       const headers = {
         'Content-Type': 'application/json',
@@ -523,7 +527,8 @@ class PromptManager {
    * Create a text or chat prompt and its first version.
    * @param {string} promptId
    * @param {string | Array<{role: string, content: string}>} template
-   * @param {{title?: string, description?: string, userVersion?: string, envIds?: string[]}} [options]
+   * @param {{title?: string, description?: string, userVersion?: string, envIds?: string[],
+   *   config?: Record<string, unknown>}} [options]
    * @returns {Promise<object | object[]>}
    */
   async createPrompt (promptId, template, options = {}) {
@@ -532,6 +537,7 @@ class PromptManager {
     if (options.description) body.description = options.description
     if (options.userVersion) body.user_version = options.userVersion
     if (options.envIds !== undefined) body.env_ids = options.envIds
+    if (options.config !== undefined) body.config = options.config
     const response = await this.#request('POST', PROMPTS_PATH, body, true)
     this.#evictPrompt(promptId)
     return response
@@ -541,7 +547,8 @@ class PromptManager {
    * Add a text or chat version to an existing prompt.
    * @param {string} promptId
    * @param {string | Array<{role: string, content: string}>} template
-   * @param {{description?: string, userVersion?: string, envIds?: string[]}} [options]
+   * @param {{description?: string, userVersion?: string, envIds?: string[],
+   *   config?: Record<string, unknown>}} [options]
    * @returns {Promise<object | object[]>}
    */
   async createPromptVersion (promptId, template, options = {}) {
@@ -549,6 +556,7 @@ class PromptManager {
     if (options.description) body.description = options.description
     if (options.userVersion) body.user_version = options.userVersion
     if (options.envIds !== undefined) body.env_ids = options.envIds
+    if (options.config !== undefined) body.config = options.config
     const path = `${PROMPTS_PATH}/${encodeURIComponent(promptId)}/versions`
     const response = await this.#request('POST', path, body, true)
     this.#evictPrompt(promptId)

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

@@ -1,6 +1,43 @@
 'use strict'
 
-const VARIABLE_PATTERN = /(?<!\{)(?:\{\{\s*(\w+)\s*\}\}(?!\})|\{\s*(\w+)\s*\}(?!\}))/g
+/** @typedef {import('../../../../../index').llmobs.FormattedPromptMessage} FormattedPromptMessage */
+
+// Match double braces first; preserve surrounding braces such as the closing object in {"age": {age}}.
+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) => {
@@ -9,23 +46,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 +88,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 +116,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 +131,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 +140,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 +151,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/span_processor.js

@@ -38,41 +38,13 @@ const {
   SAMPLE_RATE,
   SAMPLING_DECISION,
   TRACE_ID,
-  INPUT_TOKENS_METRIC_KEY,
-  OUTPUT_TOKENS_METRIC_KEY,
-  TOTAL_TOKENS_METRIC_KEY,
-  CACHE_READ_INPUT_TOKENS_METRIC_KEY,
-  CACHE_WRITE_INPUT_TOKENS_METRIC_KEY,
-  REASONING_OUTPUT_TOKENS_METRIC_KEY,
-  GEN_AI_OPERATION_NAME,
-  GEN_AI_REQUEST_MODEL,
-  GEN_AI_PROVIDER_NAME,
-  GEN_AI_APPLICATION_NAME,
-  GEN_AI_CONVERSATION_ID,
-  GEN_AI_USAGE_INPUT_TOKENS_METRIC_KEY,
-  GEN_AI_USAGE_OUTPUT_TOKENS_METRIC_KEY,
-  GEN_AI_USAGE_TOTAL_TOKENS_METRIC_KEY,
-  GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS_METRIC_KEY,
-  GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS_METRIC_KEY,
-  GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_METRIC_KEY,
-  ARTIFICIAL_GEN_AI_TAGS,
+  DEFAULT_MODEL,
 } = require('./constants/tags')
 const { UNSERIALIZABLE_VALUE_TEXT } = require('./constants/text')
+const { setGenAiApmTags } = require('./gen-ai-tags')
 const telemetry = require('./telemetry')
 const LLMObsTagger = require('./tagger')
 
-const DEFAULT_MODEL = 'custom'
-const MODEL_BACKED_SPAN_KINDS = new Set(['llm', 'embedding'])
-
-const GEN_AI_TOKEN_METRIC_KEYS = [
-  [INPUT_TOKENS_METRIC_KEY, GEN_AI_USAGE_INPUT_TOKENS_METRIC_KEY],
-  [OUTPUT_TOKENS_METRIC_KEY, GEN_AI_USAGE_OUTPUT_TOKENS_METRIC_KEY],
-  [TOTAL_TOKENS_METRIC_KEY, GEN_AI_USAGE_TOTAL_TOKENS_METRIC_KEY],
-  [CACHE_READ_INPUT_TOKENS_METRIC_KEY, GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS_METRIC_KEY],
-  [CACHE_WRITE_INPUT_TOKENS_METRIC_KEY, GEN_AI_USAGE_CACHE_WRITE_INPUT_TOKENS_METRIC_KEY],
-  [REASONING_OUTPUT_TOKENS_METRIC_KEY, GEN_AI_USAGE_REASONING_OUTPUT_TOKENS_METRIC_KEY],
-]
-
 class LLMObservabilitySpan {
   /**
    * @param {string} kind span kind
@@ -320,46 +292,19 @@ class LLMObsSpanProcessor {
   }
 
   /**
-   * Writes the scalar `gen_ai.*` attributes onto the APM span, so model, provider, application,
-   * conversation and token usage are searchable in APM. Message bodies stay off the APM span.
-   *
    * @param {import('../opentracing/span')} span
    */
   #setGenAiApmTags (span) {
     const mlObsTags = LLMObsTagger.tagMap.get(span)
-    const spanContext = span.context()
-    const spanKind = mlObsTags[SPAN_KIND]
-
-    if (spanKind) spanContext.setTag(GEN_AI_OPERATION_NAME, spanKind)
-
-    const modelName = mlObsTags[MODEL_NAME]
-    const modelProvider = mlObsTags[MODEL_PROVIDER]
-    const modelBacked = MODEL_BACKED_SPAN_KINDS.has(spanKind)
-    if (modelBacked) {
-      spanContext.setTag(GEN_AI_REQUEST_MODEL, modelName || DEFAULT_MODEL)
-      spanContext.setTag(GEN_AI_PROVIDER_NAME, (modelProvider || DEFAULT_MODEL).toLowerCase())
-    } else {
-      if (modelName) spanContext.setTag(GEN_AI_REQUEST_MODEL, modelName)
-      if (modelProvider) spanContext.setTag(GEN_AI_PROVIDER_NAME, modelProvider.toLowerCase())
-    }
-
-    const mlApp = mlObsTags[ML_APP]
-    if (mlApp) spanContext.setTag(GEN_AI_APPLICATION_NAME, mlApp)
-
-    const sessionId = mlObsTags[SESSION_ID]
-    if (sessionId) spanContext.setTag(GEN_AI_CONVERSATION_ID, sessionId)
-
-    const metrics = mlObsTags[METRICS]
-    // Other kinds carry unrelated metrics that would be misleading under a `gen_ai.usage.*` key.
-    if (modelBacked && metrics) {
-      for (const [metricKey, genAiKey] of GEN_AI_TOKEN_METRIC_KEYS) {
-        const value = metrics[metricKey]
-        if (value != null) spanContext.setTag(genAiKey, value)
-      }
-    }
 
-    // matches the value dd-trace-py writes
-    spanContext.setTag(ARTIFICIAL_GEN_AI_TAGS, 'true')
+    setGenAiApmTags(span, {
+      spanKind: mlObsTags[SPAN_KIND],
+      modelName: mlObsTags[MODEL_NAME],
+      modelProvider: mlObsTags[MODEL_PROVIDER],
+      mlApp: mlObsTags[ML_APP],
+      sessionId: mlObsTags[SESSION_ID],
+      metrics: mlObsTags[METRICS],
+    })
   }
 
   // For now, this only applies to metadata, as we let users annotate this field with any object

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

@@ -29,14 +29,7 @@ const {
   PROPAGATED_PARENT_AGENT_ID_KEY,
   PROPAGATED_PARENT_AGENT_NAME_KEY,
   ROOT_PARENT_ID,
-  CACHE_READ_INPUT_TOKENS_METRIC_KEY,
-  CACHE_WRITE_INPUT_TOKENS_METRIC_KEY,
-  CACHE_WRITE_5M_INPUT_TOKENS_METRIC_KEY,
-  CACHE_WRITE_1H_INPUT_TOKENS_METRIC_KEY,
-  INPUT_TOKENS_METRIC_KEY,
-  OUTPUT_TOKENS_METRIC_KEY,
-  TOTAL_TOKENS_METRIC_KEY,
-  REASONING_OUTPUT_TOKENS_METRIC_KEY,
+  METRIC_KEY_ALIASES,
   INTEGRATION,
   DECORATOR,
   PROPAGATED_ML_APP_KEY,
@@ -307,35 +300,8 @@ class LLMObsTagger {
   tagMetrics (span, metrics) {
     const filterdMetrics = {}
     for (const [key, value] of Object.entries(metrics)) {
-      let processedKey = key
-
       // processing these specifically for our metrics ingestion
-      switch (key) {
-        case 'inputTokens':
-          processedKey = INPUT_TOKENS_METRIC_KEY
-          break
-        case 'outputTokens':
-          processedKey = OUTPUT_TOKENS_METRIC_KEY
-          break
-        case 'totalTokens':
-          processedKey = TOTAL_TOKENS_METRIC_KEY
-          break
-        case 'cacheReadTokens':
-          processedKey = CACHE_READ_INPUT_TOKENS_METRIC_KEY
-          break
-        case 'cacheWriteTokens':
-          processedKey = CACHE_WRITE_INPUT_TOKENS_METRIC_KEY
-          break
-        case 'cacheWrite5mTokens':
-          processedKey = CACHE_WRITE_5M_INPUT_TOKENS_METRIC_KEY
-          break
-        case 'cacheWrite1hTokens':
-          processedKey = CACHE_WRITE_1H_INPUT_TOKENS_METRIC_KEY
-          break
-        case 'reasoningOutputTokens':
-          processedKey = REASONING_OUTPUT_TOKENS_METRIC_KEY
-          break
-      }
+      const processedKey = METRIC_KEY_ALIASES[key] ?? key
 
       if (typeof value === 'number') {
         filterdMetrics[processedKey] = value
@@ -505,10 +471,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 +501,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)
   }