dd-trace 5.82.0 → 5.83.0

package/packages/dd-trace/src/exporters/agent/writer.js

@@ -1,5 +1,7 @@
 'use strict'
 
+const { inspect } = require('util')
+
 const request = require('../common/request')
 const { startupLog } = require('../../startup-log')
 const runtimeMetrics = require('../../runtime_metrics')
@@ -26,7 +28,10 @@ class AgentWriter extends BaseWriter {
     runtimeMetrics.increment(`${METRIC_PREFIX}.requests`, true)
 
     const { _headers, _lookup, _protocolVersion, _url } = this
-    makeRequest(_protocolVersion, data, count, _url, _headers, _lookup, true, (err, res, status) => {
+    makeRequest(_protocolVersion, data, count, _url, _headers, _lookup, (err, res, status) => {
+      // Note that logging will only happen once, regardless of how many times this is called.
+      startupLog(status !== 404 && status !== 200 ? { status, message: err?.message ?? inspect(err) } : undefined)
+
       if (status) {
         runtimeMetrics.increment(`${METRIC_PREFIX}.responses`, true)
         runtimeMetrics.increment(`${METRIC_PREFIX}.responses.by.status`, `status:${status}`, true)
@@ -39,8 +44,6 @@ class AgentWriter extends BaseWriter {
         }
       }
 
-      startupLog({ agentError: err })
-
       if (err) {
         log.errorWithoutTelemetry('Error sending payload to the agent (status code: %s)', err.status, err)
         done()
@@ -68,7 +71,7 @@ function getEncoder (protocolVersion) {
     : require('../../encode/0.4').AgentEncoder
 }
 
-function makeRequest (version, data, count, url, headers, lookup, needsStartupLog, cb) {
+function makeRequest (version, data, count, url, headers, lookup, cb) {
   const options = {
     path: `/v${version}/traces`,
     method: 'PUT',
@@ -79,7 +82,7 @@ function makeRequest (version, data, count, url, headers, lookup, needsStartupLo
       'X-Datadog-Trace-Count': String(count),
       'Datadog-Meta-Lang': 'nodejs',
       'Datadog-Meta-Lang-Version': process.version,
-      'Datadog-Meta-Lang-Interpreter': process.jsEngine || 'v8'
+      'Datadog-Meta-Lang-Interpreter': process.versions.bun ? 'JavaScriptCore' : 'v8'
     },
     lookup,
     url
@@ -87,15 +90,7 @@ function makeRequest (version, data, count, url, headers, lookup, needsStartupLo
 
   log.debug('Request to the agent: %j', options)
 
-  request(data, options, (err, res, status) => {
-    if (needsStartupLog) {
-      // Note that logging will only happen once, regardless of how many times this is called.
-      startupLog({
-        agentError: status !== 404 && status !== 200 ? err : undefined
-      })
-    }
-    cb(err, res, status)
-  })
+  request(data, options, cb)
 }
 
 module.exports = AgentWriter

package/packages/dd-trace/src/exporters/common/agent-info-exporter.js

@@ -2,7 +2,7 @@
 
 const { URL, format } = require('url')
 
-const defaults = require('../../config_defaults')
+const defaults = require('../../config/defaults')
 const { incrementCountMetric, TELEMETRY_EVENTS_ENQUEUED_FOR_SERIALIZATION } = require('../../ci-visibility/telemetry')
 const request = require('./request')
 

package/packages/dd-trace/src/exporters/common/docker.js

@@ -1,9 +1,9 @@
 'use strict'
 
 const fs = require('fs')
-const { getEnvironmentVariable } = require('../../config-helper')
+const { getValueFromEnvSources } = require('../../config/helper')
 
-const DD_EXTERNAL_ENV = getEnvironmentVariable('DD_EXTERNAL_ENV')
+const DD_EXTERNAL_ENV = getValueFromEnvSources('DD_EXTERNAL_ENV')
 
 // The second part is the PCF / Garden regexp. We currently assume no suffix($) to avoid matching pod UIDs
 // See https://github.com/DataDog/datadog-agent/blob/7.40.x/pkg/util/cgroups/reader.go#L50

package/packages/dd-trace/src/exporters/common/request.js

@@ -77,7 +77,7 @@ function request (data, options, callback) {
     res.on('data', chunk => {
       chunks.push(chunk)
     })
-    res.on('end', () => {
+    res.once('end', () => {
       activeRequests--
       const buffer = Buffer.concat(chunks)
 

package/packages/dd-trace/src/exporters/common/util.js

@@ -1,12 +1,12 @@
 'use strict'
 
-const { getEnvironmentVariable } = require('../../config-helper')
+const { getValueFromEnvSources } = require('../../config/helper')
 
 function safeJSONStringify (value) {
   return JSON.stringify(
     value,
     (key, value) => key === 'dd-api-key' ? undefined : value,
-    getEnvironmentVariable('DD_TRACE_BEAUTIFUL_LOGS') ? 2 : undefined
+    getValueFromEnvSources('DD_TRACE_BEAUTIFUL_LOGS') ? 2 : undefined
   )
 }
 

package/packages/dd-trace/src/exporters/span-stats/index.js

@@ -2,7 +2,7 @@
 
 const { URL, format } = require('url')
 
-const defaults = require('../../config_defaults')
+const defaults = require('../../config/defaults')
 const { Writer } = require('./writer')
 
 class SpanStatsExporter {

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

@@ -64,7 +64,7 @@ const flare = {
   },
 
   _sendFile (task, file, filename) {
-    if (!file) return
+    if (!file || file.length === 0) return
 
     const form = new FormData()
 

package/packages/dd-trace/src/guardrails/telemetry.js

@@ -80,7 +80,7 @@ function sendTelemetry (name, tags, resultMetadata) {
   proc.on('error', function () {
     log.error('Failed to spawn telemetry forwarder')
   })
-  proc.on('exit', function (code) {
+  proc.once('exit', function (code) {
     if (code !== 0) {
       log.error('Telemetry forwarder exited with code', code)
     }

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

@@ -1,14 +1,14 @@
 'use strict'
 
-const { getEnvironmentVariable } = require('../../dd-trace/src/config-helper')
+const { getValueFromEnvSources } = require('./config/helper')
 const { isFalse } = require('./util')
 
 // Global `jest` is only present in Jest workers.
 const inJestWorker = typeof jest !== 'undefined'
 
-const ddTraceDisabled = getEnvironmentVariable('DD_TRACE_ENABLED')
-  ? isFalse(getEnvironmentVariable('DD_TRACE_ENABLED'))
-  : String(getEnvironmentVariable('OTEL_TRACES_EXPORTER')).toLowerCase() === 'none'
+const ddTraceDisabled = getValueFromEnvSources('DD_TRACE_ENABLED')
+  ? isFalse(getValueFromEnvSources('DD_TRACE_ENABLED'))
+  : String(getValueFromEnvSources('OTEL_TRACES_EXPORTER')).toLowerCase() === 'none'
 
 module.exports = ddTraceDisabled || inJestWorker
   ? require('./noop/proxy')

package/packages/dd-trace/src/lambda/handler.js

@@ -3,7 +3,7 @@
 const log = require('../log')
 const { channel } = require('../../../datadog-instrumentations/src/helpers/instrument')
 const { ERROR_MESSAGE, ERROR_TYPE } = require('../constants')
-const { getEnvironmentVariable } = require('../config-helper')
+const { getValueFromEnvSources } = require('../config/helper')
 const { ImpendingTimeout } = require('./runtime/errors')
 
 const globalTracer = global._ddtrace
@@ -26,7 +26,7 @@ let __lambdaTimeout
 function checkTimeout (context) {
   const remainingTimeInMillis = context.getRemainingTimeInMillis()
 
-  let apmFlushDeadline = Number.parseInt(getEnvironmentVariable('DD_APM_FLUSH_DEADLINE_MILLISECONDS')) || 100
+  let apmFlushDeadline = Number.parseInt(getValueFromEnvSources('DD_APM_FLUSH_DEADLINE_MILLISECONDS')) || 100
   apmFlushDeadline = apmFlushDeadline < 0 ? 100 : apmFlushDeadline
 
   __lambdaTimeout = setTimeout(() => {

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

@@ -1,13 +1,13 @@
 'use strict'
 
-const { getEnvironmentVariable } = require('../config-helper')
+const { getValueFromEnvSources } = require('../config/helper')
 const { registerLambdaHook } = require('./runtime/ritm')
 
 /**
  * It is safe to do it this way, since customers will never be expected to disable
  * this specific instrumentation through the init config object.
  */
-const _DD_TRACE_DISABLED_INSTRUMENTATIONS = getEnvironmentVariable('DD_TRACE_DISABLED_INSTRUMENTATIONS') || ''
+const _DD_TRACE_DISABLED_INSTRUMENTATIONS = getValueFromEnvSources('DD_TRACE_DISABLED_INSTRUMENTATIONS') || ''
 const _disabledInstrumentations = new Set(
   _DD_TRACE_DISABLED_INSTRUMENTATIONS ? _DD_TRACE_DISABLED_INSTRUMENTATIONS.split(',') : []
 )

package/packages/dd-trace/src/lambda/runtime/patch.js

@@ -5,7 +5,7 @@ const path = require('path')
 const { datadog } = require('../handler')
 const { addHook } = require('../../../../datadog-instrumentations/src/helpers/instrument')
 const shimmer = require('../../../../datadog-shimmer')
-const { getEnvironmentVariable } = require('../../config-helper')
+const { getEnvironmentVariable, getValueFromEnvSources } = require('../../config/helper')
 const { _extractModuleNameAndHandlerPath, _extractModuleRootAndHandler, _getLambdaFilePaths } = require('./ritm')
 
 /**
@@ -59,7 +59,7 @@ function patchLambdaHandler (lambdaHandler) {
 }
 
 const lambdaTaskRoot = getEnvironmentVariable('LAMBDA_TASK_ROOT')
-const originalLambdaHandler = getEnvironmentVariable('DD_LAMBDA_HANDLER')
+const originalLambdaHandler = getValueFromEnvSources('DD_LAMBDA_HANDLER')
 
 if (originalLambdaHandler === undefined) {
   // Instrumentation is done manually.

package/packages/dd-trace/src/lambda/runtime/ritm.js

@@ -10,7 +10,7 @@
 const path = require('path')
 
 const log = require('../../log')
-const { getEnvironmentVariable } = require('../../config-helper')
+const { getEnvironmentVariable, getValueFromEnvSources } = require('../../config/helper')
 const Hook = require('../../../../datadog-instrumentations/src/helpers/hook')
 const instrumentations = require('../../../../datadog-instrumentations/src/helpers/instrumentations')
 const {
@@ -79,7 +79,7 @@ function _getLambdaFilePaths (lambdaStylePath) {
  */
 const registerLambdaHook = () => {
   const lambdaTaskRoot = getEnvironmentVariable('LAMBDA_TASK_ROOT')
-  const originalLambdaHandler = getEnvironmentVariable('DD_LAMBDA_HANDLER')
+  const originalLambdaHandler = getValueFromEnvSources('DD_LAMBDA_HANDLER')
 
   if (originalLambdaHandler !== undefined && lambdaTaskRoot !== undefined) {
     const [moduleRoot, moduleAndHandler] = _extractModuleRootAndHandler(originalLambdaHandler)

package/packages/dd-trace/src/llmobs/constants/tags.js

@@ -17,6 +17,9 @@ module.exports = {
   TRACE_ID: '_ml_obs.trace_id',
   PROPAGATED_TRACE_ID_KEY: '_dd.p.llmobs_trace_id',
   ROOT_PARENT_ID: 'undefined',
+  DEFAULT_PROMPT_NAME: 'unnamed-prompt',
+  INTERNAL_CONTEXT_VARIABLE_KEYS: '_dd_context_variable_keys',
+  INTERNAL_QUERY_VARIABLE_KEYS: '_dd_query_variable_keys',
 
   MODEL_NAME: '_ml_obs.meta.model_name',
   MODEL_PROVIDER: '_ml_obs.meta.model_provider',
@@ -24,6 +27,7 @@ module.exports = {
   INPUT_DOCUMENTS: '_ml_obs.meta.input.documents',
   INPUT_MESSAGES: '_ml_obs.meta.input.messages',
   INPUT_VALUE: '_ml_obs.meta.input.value',
+  INPUT_PROMPT: '_ml_obs.meta.input.prompt',
 
   OUTPUT_DOCUMENTS: '_ml_obs.meta.output.documents',
   OUTPUT_MESSAGES: '_ml_obs.meta.output.messages',
@@ -42,5 +46,8 @@ module.exports = {
   PROMPT_MULTIMODAL: 'prompt_multimodal',
   INSTRUMENTATION_METHOD_AUTO: 'auto',
   INSTRUMENTATION_METHOD_ANNOTATED: 'annotated',
-  INSTRUMENTATION_METHOD_UNKNOWN: 'unknown'
+  INSTRUMENTATION_METHOD_UNKNOWN: 'unknown',
+
+  ROUTING_API_KEY: '_dd.llmobs.routing.api_key',
+  ROUTING_SITE: '_dd.llmobs.routing.site'
 }

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

@@ -136,9 +136,9 @@ function handleSpanProcess (span) {
   spanProcessor.process(span)
 }
 
-function handleEvalMetricAppend (payload) {
+function handleEvalMetricAppend ({ payload, routing }) {
   try {
-    evalWriter.append(payload)
+    evalWriter.append(payload, routing)
   } catch (e) {
     log.warn(
       // eslint-disable-next-line @stylistic/max-len

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

@@ -81,6 +81,8 @@ class NoopLLMObs {
   deregisterProcessor () {}
 
   annotationContext (options, fn) { return fn() }
+
+  routingContext (options, fn) { return fn() }
 }
 
 module.exports = NoopLLMObs

package/packages/dd-trace/src/llmobs/plugins/openai/index.js

@@ -422,16 +422,15 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
     // Handle prompt tracking for reusable prompts
     if (inputs.prompt && response?.prompt) {
       const { id, version } = response.prompt // ResponsePrompt
-      // TODO: Add proper tagger API for prompt metadata
       if (id && version) {
         const normalizedVariables = normalizePromptVariables(inputs.prompt.variables)
         const chatTemplate = extractChatTemplateFromInstructions(response.instructions, normalizedVariables)
-        this._tagger._setTag(span, '_ml_obs.meta.input.prompt', {
+        this._tagger.tagPrompt(span, {
           id,
           version,
           variables: normalizedVariables,
-          chat_template: chatTemplate
-        })
+          template: chatTemplate
+        }, true)
         const tags = { [PROMPT_TRACKING_INSTRUMENTATION_METHOD]: INSTRUMENTATION_METHOD_AUTO }
         if (hasMultimodalInputs(inputs.prompt.variables)) {
           tags[PROMPT_MULTIMODAL] = 'true'

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

@@ -5,7 +5,7 @@ const { channel } = require('dc-polyfill')
 const { isTrue, isError } = require('../util')
 const tracerVersion = require('../../../../package.json').version
 const logger = require('../log')
-const { getEnvironmentVariable } = require('../config-helper')
+const { getValueFromEnvSources } = require('../config/helper')
 const Span = require('../opentracing/span')
 const { SPAN_KIND, OUTPUT_VALUE, INPUT_VALUE } = require('./constants/tags')
 const {
@@ -49,7 +49,7 @@ class LLMObs extends NoopLLMObs {
 
     logger.debug('Enabling LLMObs')
 
-    const DD_LLMOBS_ENABLED = getEnvironmentVariable('DD_LLMOBS_ENABLED')
+    const DD_LLMOBS_ENABLED = getValueFromEnvSources('DD_LLMOBS_ENABLED')
 
     if (DD_LLMOBS_ENABLED != null && !isTrue(DD_LLMOBS_ENABLED)) {
       logger.debug('LLMObs.enable() called when DD_LLMOBS_ENABLED is false. No action taken.')
@@ -62,7 +62,7 @@ class LLMObs extends NoopLLMObs {
     }
     // TODO: This will update config telemetry with the origin 'code', which is not ideal when `enable()` is called
     // based on `APM_TRACING` RC product updates.
-    this._config.configure({ llmobs })
+    this._config.updateOptions({ llmobs })
 
     // configure writers and channel subscribers
     this._llmobsModule.enable(this._config)
@@ -241,7 +241,7 @@ class LLMObs extends NoopLLMObs {
         throw new Error('LLMObs span must have a span kind specified')
       }
 
-      const { inputData, outputData, metadata, metrics, tags } = options
+      const { inputData, outputData, metadata, metrics, tags, prompt } = options
 
       if (inputData || outputData) {
         if (spanKind === 'llm') {
@@ -264,6 +264,9 @@ class LLMObs extends NoopLLMObs {
       if (tags) {
         this._tagger.tagSpanTags(span, tags)
       }
+      if (prompt) {
+        this._tagger.tagPrompt(span, prompt)
+      }
     } catch (e) {
       if (e.ddErrorTag) {
         err = e.ddErrorTag
@@ -404,7 +407,7 @@ class LLMObs extends NoopLLMObs {
       }
 
       // When OTel tracing is enabled, add source:otel tag to allow backend to wait for OTel span conversion
-      if (isTrue(getEnvironmentVariable('DD_TRACE_OTEL_ENABLED'))) {
+      if (isTrue(getValueFromEnvSources('DD_TRACE_OTEL_ENABLED'))) {
         evaluationTags.source = 'otel'
       }
 
@@ -418,7 +421,9 @@ class LLMObs extends NoopLLMObs {
         timestamp_ms: timestampMs,
         tags: Object.entries(evaluationTags).map(([key, value]) => `${key}:${value}`)
       }
-      evalMetricAppendCh.publish(payload)
+      const currentStore = storage.getStore()
+      const routing = currentStore?.routingContext
+      evalMetricAppendCh.publish({ payload, routing })
     } finally {
       telemetry.recordSubmitEvaluation(options, err)
     }
@@ -440,6 +445,28 @@ class LLMObs extends NoopLLMObs {
     return storage.run(store, fn)
   }
 
+  routingContext (options, fn) {
+    if (!this.enabled) return fn()
+    if (!options?.ddApiKey) {
+      throw new Error('ddApiKey is required for routing context')
+    }
+    const currentStore = storage.getStore()
+    if (currentStore?.routingContext) {
+      logger.warn(
+        '[LLM Observability] Nested routing context detected. Inner context will override outer context. ' +
+        'Spans created in the inner context will only be sent to the inner context.'
+      )
+    }
+    const store = {
+      ...currentStore,
+      routingContext: {
+        apiKey: options.ddApiKey,
+        site: options.ddSite
+      }
+    }
+    return storage.run(store, fn)
+  }
+
   flush () {
     if (!this.enabled) return
 

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

@@ -26,7 +26,10 @@ const {
   TAGS,
   PARENT_ID_KEY,
   SESSION_ID,
-  NAME
+  NAME,
+  INPUT_PROMPT,
+  ROUTING_API_KEY,
+  ROUTING_SITE
 } = require('./constants/tags')
 const { UNSERIALIZABLE_VALUE_TEXT } = require('./constants/text')
 const telemetry = require('./telemetry')
@@ -78,7 +81,13 @@ class LLMObsSpanProcessor {
       telemetry.incrementLLMObsSpanFinishedCount(span)
       if (formattedEvent == null) return
 
-      this.#writer.append(formattedEvent)
+      const mlObsTags = LLMObsTagger.tagMap.get(span)
+      const routing = {
+        apiKey: mlObsTags[ROUTING_API_KEY],
+        site: mlObsTags[ROUTING_SITE]
+      }
+
+      this.#writer.append(formattedEvent, routing)
     } catch (e) {
       // this should be a rare case
       // we protect against unserializable properties in the format function, and in
@@ -122,11 +131,6 @@ class LLMObsSpanProcessor {
       inputType = 'value'
     }
 
-    // Handle prompt metadata for reusable prompts
-    if (mlObsTags['_ml_obs.meta.input.prompt']) {
-      input.prompt = mlObsTags['_ml_obs.meta.input.prompt']
-    }
-
     if (spanKind === 'llm' && mlObsTags[OUTPUT_MESSAGES]) {
       llmObsSpan.output = mlObsTags[OUTPUT_MESSAGES]
       outputType = 'messages'
@@ -177,6 +181,12 @@ class LLMObsSpanProcessor {
     if (input) meta.input = input
     if (output) meta.output = output
 
+    const prompt = mlObsTags[INPUT_PROMPT]
+    if (prompt && spanKind === 'llm') {
+      // by this point, we should have logged a warning if the span kind was not llm
+      meta.input.prompt = prompt
+    }
+
     const llmObsSpanEvent = {
       trace_id: span.context().toTraceId(true),
       span_id: span.context().toSpanId(),

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

@@ -28,7 +28,15 @@ const {
   REASONING_OUTPUT_TOKENS_METRIC_KEY,
   INTEGRATION,
   DECORATOR,
-  PROPAGATED_ML_APP_KEY
+  PROPAGATED_ML_APP_KEY,
+  DEFAULT_PROMPT_NAME,
+  INTERNAL_CONTEXT_VARIABLE_KEYS,
+  INTERNAL_QUERY_VARIABLE_KEYS,
+  INPUT_PROMPT,
+  ROUTING_API_KEY,
+  ROUTING_SITE,
+  PROMPT_TRACKING_INSTRUMENTATION_METHOD,
+  INSTRUMENTATION_METHOD_ANNOTATED
 } = require('./constants/tags')
 const { storage } = require('./storage')
 
@@ -110,6 +118,18 @@ class LLMObsTagger {
     // apply annotation context name
     const annotationContextName = annotationContext?.name
     if (annotationContextName) this._setTag(span, NAME, annotationContextName)
+
+    // apply annotation context prompt
+    const annotationContextPrompt = annotationContext?.prompt
+    if (annotationContextPrompt) this.tagPrompt(span, annotationContextPrompt)
+
+    const routing = storage.getStore()?.routingContext
+    if (routing) {
+      this._setTag(span, ROUTING_API_KEY, routing.apiKey)
+      if (routing.site) {
+        this._setTag(span, ROUTING_SITE, routing.site)
+      }
+    }
   }
 
   // TODO: similarly for the following `tag` methods,
@@ -194,6 +214,160 @@ class LLMObsTagger {
     }
   }
 
+  /**
+   * Tags a prompt on an LLMObs span.
+   * @param {import('../opentracing/span')} span
+   * @param {string | Record<string, unknown>} prompt
+   * @param {boolean?} strictValidation
+   *   whether to validate the prompt against the strict schema, used for auto-instrumentation
+   */
+  tagPrompt (span, prompt, strictValidation = false) {
+    const spanKind = registry.get(span)?.[SPAN_KIND]
+    if (spanKind !== 'llm') {
+      log.warn('Dropping prompt on non-LLM span kind, annotating prompts is only supported for LLM span kinds.')
+      return
+    }
+
+    if (!prompt || typeof prompt !== 'object') {
+      this.#handleFailure('Prompt must be an object.', 'invalid_prompt')
+      return
+    }
+
+    const mlApp = registry.get(span)?.[ML_APP] // this should be defined at this point
+    const {
+      id,
+      version,
+      tags,
+      variables,
+      template,
+      contextVariables,
+      queryVariables,
+    } = prompt
+
+    if (strictValidation) {
+      if (id == null) {
+        this.#handleFailure('Prompt ID is required.', 'invalid_prompt')
+        return
+      }
+
+      if (template == null) {
+        this.#handleFailure('Prompt template is required.', 'invalid_prompt')
+        return
+      }
+    }
+
+    const finalPromptId = id ?? `${mlApp}_${DEFAULT_PROMPT_NAME}`
+    const finalCtxVariablesKeys = contextVariables ?? ['context']
+    const finalQueryVariablesKeys = queryVariables ?? ['question']
+
+    // validate prompt id
+    if (typeof finalPromptId !== 'string') {
+      this.#handleFailure('Prompt ID must be a string.', 'invalid_prompt')
+      return
+    }
+
+    // validate prompt context variables keys
+    if (Array.isArray(finalCtxVariablesKeys)) {
+      for (const key of finalCtxVariablesKeys) {
+        if (typeof key !== 'string') {
+          this.#handleFailure('Prompt context variables keys must be an array of strings.', 'invalid_prompt')
+          return
+        }
+      }
+    } else if (finalCtxVariablesKeys) {
+      this.#handleFailure('Prompt context variables keys must be an array.', 'invalid_prompt')
+      return
+    }
+
+    // validate prompt query variables keys
+    if (Array.isArray(finalQueryVariablesKeys)) {
+      for (const key of finalQueryVariablesKeys) {
+        if (typeof key !== 'string') {
+          this.#handleFailure('Prompt query variables keys must be an array of strings.', 'invalid_prompt')
+          return
+        }
+      }
+    } else if (finalQueryVariablesKeys) {
+      this.#handleFailure('Prompt query variables keys must be an array.', 'invalid_prompt')
+      return
+    }
+
+    // validate prompt version
+    if (version && typeof version !== 'string') {
+      this.#handleFailure('Prompt version must be a string.', 'invalid_prompt')
+      return
+    }
+
+    // validate prompt tags
+    if (tags && (typeof tags !== 'object' || tags instanceof Map)) {
+      this.#handleFailure('Prompt tags must be an non-Map object.', 'invalid_prompt')
+      return
+    } else if (tags) {
+      for (const [key, value] of Object.entries(tags)) {
+        if (typeof key !== 'string' || typeof value !== 'string') {
+          this.#handleFailure('Prompt tags must be an object of string key-value pairs.', 'invalid_prompt')
+          return
+        }
+      }
+    }
+
+    // validate prompt template is either string or list of messages
+    if (template && !(typeof template === 'string' || Array.isArray(template))) {
+      this.#handleFailure('Prompt template must be a string or an array of messages.', 'invalid_prompt')
+      return
+    }
+
+    if (Array.isArray(template)) {
+      for (const message of template) {
+        if (typeof message !== 'object' || !message.role || !message.content) {
+          this.#handleFailure(
+            'Prompt chat template must be an array of objects with role and content properties.', 'invalid_prompt'
+          )
+          return
+        }
+      }
+    }
+
+    // validate variables are a string-string mapping
+    if (variables && (typeof variables !== 'object' || variables instanceof Map)) {
+      this.#handleFailure('Prompt variables must be an non-Map object.', 'invalid_prompt')
+      return
+    } else if (variables) {
+      for (const [key, value] of Object.entries(variables)) {
+        if (typeof key !== 'string' || typeof value !== 'string') {
+          this.#handleFailure('Prompt variables must be an object of string key-value pairs.', 'invalid_prompt')
+          return
+        }
+      }
+    }
+
+    let finalTemplate, finalChatTemplate
+    if (typeof template === 'string') {
+      finalTemplate = template
+    } else if (Array.isArray(template)) {
+      finalChatTemplate = template.map(message => ({ role: message.role, content: message.content }))
+    }
+
+    const validatedPrompt = {}
+    if (finalPromptId) validatedPrompt.id = finalPromptId
+    if (version) validatedPrompt.version = version
+    if (variables) validatedPrompt.variables = variables
+    if (finalTemplate) validatedPrompt.template = finalTemplate
+    if (finalChatTemplate?.length) validatedPrompt.chat_template = finalChatTemplate
+    if (tags) validatedPrompt.tags = tags
+    if (finalCtxVariablesKeys) validatedPrompt[INTERNAL_CONTEXT_VARIABLE_KEYS] = finalCtxVariablesKeys
+    if (finalQueryVariablesKeys) validatedPrompt[INTERNAL_QUERY_VARIABLE_KEYS] = finalQueryVariablesKeys
+
+    const currentPrompt = registry.get(span)?.[INPUT_PROMPT]
+    if (currentPrompt) {
+      Object.assign(currentPrompt, validatedPrompt)
+    } else {
+      this._setTag(span, INPUT_PROMPT, validatedPrompt)
+    }
+
+    this.tagSpanTags(span, { [PROMPT_TRACKING_INSTRUMENTATION_METHOD]: INSTRUMENTATION_METHOD_ANNOTATED })
+  }
+
   changeKind (span, newKind) {
     this._setTag(span, SPAN_KIND, newKind)
   }