dd-trace 5.100.0 → 5.102.0

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

@@ -7,6 +7,7 @@ const {
   INSTRUMENTATION_METHOD_AUTO,
   UNKNOWN_MODEL_PROVIDER,
 } = require('../../constants/tags')
+const { safeJsonParse } = require('../../util')
 const {
   extractChatTemplateFromInstructions,
   normalizePromptVariables,
@@ -183,13 +184,12 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
   _tagChatCompletion (span, inputs, response, error) {
     const { messages, model, ...parameters } = inputs
 
-    const metadata = Object.entries(parameters).reduce((obj, [key, value]) => {
-      if (!['tools', 'functions'].includes(key)) {
-        obj[key] = value
+    const metadata = {}
+    for (const key of Object.keys(parameters)) {
+      if (key !== 'tools' && key !== 'functions') {
+        metadata[key] = parameters[key]
       }
-
-      return obj
-    }, {})
+    }
 
     this._tagger.tagMetadata(span, metadata)
 
@@ -213,14 +213,14 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
       if (message.function_call) {
         const functionCallInfo = {
           name: message.function_call.name,
-          arguments: JSON.parse(message.function_call.arguments),
+          arguments: safeJsonParse(message.function_call.arguments),
         }
         outputMessages.push({ content, role, toolCalls: [functionCallInfo] })
       } else if (message.tool_calls) {
         const toolCallsInfo = []
         for (const toolCall of message.tool_calls) {
           const toolCallInfo = {
-            arguments: JSON.parse(toolCall.function.arguments),
+            arguments: safeJsonParse(toolCall.function.arguments),
             name: toolCall.function.name,
             toolId: toolCall.id,
             type: toolCall.type,
@@ -277,22 +277,12 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
             inputMessages.push({ role, content })
           }
         } else if (item.type === 'function_call') {
-          // Function call: convert to message with tool_calls
-          // Parse arguments if it's a JSON string
-          let parsedArgs = item.arguments
-          if (typeof parsedArgs === 'string') {
-            try {
-              parsedArgs = JSON.parse(parsedArgs)
-            } catch {
-              parsedArgs = {}
-            }
-          }
           inputMessages.push({
             role: 'assistant',
             toolCalls: [{
               toolId: item.call_id,
               name: item.name,
-              arguments: parsedArgs,
+              arguments: safeJsonParse(item.arguments, {}),
               type: item.type,
             }],
           })
@@ -317,12 +307,12 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
       inputMessages.push({ role: 'user', content: input })
     }
 
-    const inputMetadata = Object.entries(parameters).reduce((obj, [key, value]) => {
+    const inputMetadata = {}
+    for (const key of Object.keys(parameters)) {
       if (allowedParamKeys.has(key)) {
-        obj[key] = value
+        inputMetadata[key] = parameters[key]
       }
-      return obj
-    }, {})
+    }
 
     this._tagger.tagMetadata(span, inputMetadata)
 
@@ -354,21 +344,12 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
           })
         } else if (item.type === 'function_call') {
           // Handle function_call type (responses API tool calls)
-          let args = item.arguments
-          // Parse arguments if it's a JSON string
-          if (typeof args === 'string') {
-            try {
-              args = JSON.parse(args)
-            } catch {
-              args = {}
-            }
-          }
           outputMessages.push({
             role: 'assistant',
             toolCalls: [{
               toolId: item.call_id,
               name: item.name,
-              arguments: args,
+              arguments: safeJsonParse(item.arguments, {}),
               type: item.type,
             }],
           })
@@ -390,23 +371,12 @@ class OpenAiLLMObsPlugin extends LLMObsPlugin {
 
           // Extract tool calls if present in message.tool_calls
           if (Array.isArray(item.tool_calls)) {
-            outputMsg.toolCalls = item.tool_calls.map(tc => {
-              let args = tc.function?.arguments || tc.arguments
-              // Parse arguments if it's a JSON string
-              if (typeof args === 'string') {
-                try {
-                  args = JSON.parse(args)
-                } catch {
-                  args = {}
-                }
-              }
-              return {
-                toolId: tc.id,
-                name: tc.function?.name || tc.name,
-                arguments: args,
-                type: tc.type || 'function_call',
-              }
-            })
+            outputMsg.toolCalls = item.tool_calls.map(tc => ({
+              toolId: tc.id,
+              name: tc.function?.name || tc.name,
+              arguments: safeJsonParse(tc.function?.arguments || tc.arguments, {}),
+              type: tc.type || 'function_call',
+            }))
           }
 
           outputMessages.push(outputMsg)

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

@@ -112,16 +112,16 @@ class LLMObs extends NoopLLMObs {
     const {
       spanOptions,
       ...llmobsOptions
-    } = this._extractOptions(options)
+    } = this.#extractOptions(options)
 
     if (fn.length > 1) {
       return this._tracer.trace(name, spanOptions, (span, cb) =>
-        this._activate(span, { kind, ...llmobsOptions }, () => fn(span, cb))
+        this.#activate(span, { kind, ...llmobsOptions }, () => fn(span, cb))
       )
     }
 
     return this._tracer.trace(name, spanOptions, span =>
-      this._activate(span, { kind, ...llmobsOptions }, () => fn(span))
+      this.#activate(span, { kind, ...llmobsOptions }, () => fn(span))
     )
   }
 
@@ -142,53 +142,53 @@ class LLMObs extends NoopLLMObs {
     const {
       spanOptions,
       ...llmobsOptions
-    } = this._extractOptions(options)
+    } = this.#extractOptions(options)
 
     const llmobs = this
 
-    function wrapped () {
+    function wrapped (...args) {
       telemetry.incrementLLMObsSpanStartCount({ autoinstrumented: false, kind })
 
       const span = llmobs._tracer.scope().active()
-      const fnArgs = arguments
+      const fnArgs = args
 
       const lastArgId = fnArgs.length - 1
       const cb = fnArgs[lastArgId]
       const hasCallback = typeof cb === 'function'
 
       if (hasCallback) {
-        const scopeBoundCb = llmobs._bind(cb)
-        fnArgs[lastArgId] = function () {
+        const scopeBoundCb = llmobs.#bind(cb)
+        fnArgs[lastArgId] = function (...args) {
           // it is standard practice to follow the callback signature (err, result)
           // however, we try to parse the arguments to determine if the first argument is an error
           // if it is not, and is not undefined, we will use that for the output value
-          const maybeError = arguments[0]
-          const maybeResult = arguments[1]
+          const maybeError = args[0]
+          const maybeResult = args[1]
 
-          llmobs._autoAnnotate(
+          llmobs.#autoAnnotate(
             span,
             kind,
             getFunctionArguments(fn, fnArgs),
             isError(maybeError) || maybeError == null ? maybeResult : maybeError
           )
 
-          return scopeBoundCb.apply(this, arguments)
+          return scopeBoundCb.apply(this, args)
         }
       }
 
       try {
-        const result = llmobs._activate(span, { kind, ...llmobsOptions }, () => fn.apply(this, fnArgs))
+        const result = llmobs.#activate(span, { kind, ...llmobsOptions }, () => fn.apply(this, fnArgs))
 
         if (result && typeof result.then === 'function') {
           return result.then(
             value => {
               if (!hasCallback) {
-                llmobs._autoAnnotate(span, kind, getFunctionArguments(fn, fnArgs), value)
+                llmobs.#autoAnnotate(span, kind, getFunctionArguments(fn, fnArgs), value)
               }
               return value
             },
             err => {
-              llmobs._autoAnnotate(span, kind, getFunctionArguments(fn, fnArgs))
+              llmobs.#autoAnnotate(span, kind, getFunctionArguments(fn, fnArgs))
               throw err
             }
           )
@@ -199,12 +199,12 @@ class LLMObs extends NoopLLMObs {
         // the callback is called before the function returns (although unlikely)
         // we do not want to throw for "annotating a finished span" in this case
         if (!hasCallback) {
-          llmobs._autoAnnotate(span, kind, getFunctionArguments(fn, fnArgs), result)
+          llmobs.#autoAnnotate(span, kind, getFunctionArguments(fn, fnArgs), result)
         }
 
         return result
       } catch (e) {
-        llmobs._autoAnnotate(span, kind, getFunctionArguments(fn, fnArgs))
+        llmobs.#autoAnnotate(span, kind, getFunctionArguments(fn, fnArgs))
         throw e
       }
     }
@@ -251,7 +251,7 @@ class LLMObs extends NoopLLMObs {
         throw new Error('LLMObs span must have a span kind specified')
       }
 
-      const { inputData, outputData, metadata, metrics, tags, prompt } = options
+      const { inputData, outputData, metadata, metrics, tags, prompt, costTags } = options
 
       if (inputData || outputData) {
         if (spanKind === 'llm') {
@@ -271,9 +271,13 @@ class LLMObs extends NoopLLMObs {
       if (metrics) {
         this._tagger.tagMetrics(span, metrics)
       }
+      // Apply tags before costTags so costTags can reference tags from the same annotation.
       if (tags) {
         this._tagger.tagSpanTags(span, tags)
       }
+      if (costTags != null) {
+        this._tagger.tagCostTags(span, costTags, 'annotate')
+      }
       if (prompt) {
         this._tagger.tagPrompt(span, prompt)
       }
@@ -512,7 +516,7 @@ class LLMObs extends NoopLLMObs {
     flushCh.publish()
   }
 
-  _autoAnnotate (span, kind, input, output) {
+  #autoAnnotate (span, kind, input, output) {
     const annotations = {}
     if (input && !['llm', 'embedding'].includes(kind) && !LLMObsTagger.tagMap.get(span)?.[INPUT_VALUE]) {
       annotations.inputData = input
@@ -530,7 +534,7 @@ class LLMObs extends NoopLLMObs {
     return store?.span
   }
 
-  _activate (span, options, fn) {
+  #activate (span, options, fn) {
     const parentStore = storage.getStore()
     if (this.enabled) storage.enterWith({ ...parentStore, span })
 
@@ -563,22 +567,20 @@ class LLMObs extends NoopLLMObs {
   }
 
   // bind function to active LLMObs span
-  _bind (fn) {
+  #bind (fn) {
     if (typeof fn !== 'function') return fn
 
     const llmobs = this
     const activeSpan = llmobs._active()
 
-    const bound = function () {
-      return llmobs._activate(activeSpan, null, () => {
-        return fn.apply(this, arguments)
+    return function (...args) {
+      return llmobs.#activate(activeSpan, null, () => {
+        return fn.apply(this, args)
       })
     }
-
-    return bound
   }
 
-  _extractOptions (options) {
+  #extractOptions (options) {
     const {
       modelName,
       modelProvider,

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

@@ -14,6 +14,8 @@ const {
   MODEL_NAME,
   MODEL_PROVIDER,
   METADATA,
+  COST_TAGS,
+  TOOL_DEFINITIONS,
   INPUT_MESSAGES,
   INPUT_VALUE,
   INTEGRATION,
@@ -37,10 +39,16 @@ const telemetry = require('./telemetry')
 const LLMObsTagger = require('./tagger')
 
 class LLMObservabilitySpan {
-  constructor () {
+  /**
+   * @param {string} kind span kind
+   */
+  constructor (kind) {
     this.input = []
     this.output = []
 
+    /** @type {string} */
+    this.kind = kind
+
     this._tags = {}
   }
 
@@ -113,7 +121,6 @@ class LLMObsSpanProcessor {
   }
 
   format (span) {
-    const llmObsSpan = new LLMObservabilitySpan()
     let inputType, outputType
 
     const spanTags = span.context()._tags
@@ -130,15 +137,31 @@ class LLMObsSpanProcessor {
       meta.model_provider = (mlObsTags[MODEL_PROVIDER] || 'custom').toLowerCase()
     }
 
-    if (mlObsTags[METADATA]) {
-      this.#addObject(mlObsTags[METADATA], meta.metadata = {})
+    if (mlObsTags[METADATA] || mlObsTags[COST_TAGS]) {
+      const metadata = {}
+      if (mlObsTags[METADATA]) this.#addObject(mlObsTags[METADATA], metadata)
+      // Only seed `metadata._dd` when there's something to put in it (currently cost_tags). Mirrors
+      // dd-trace-py and the cross-language wire format enforced by system-tests — metadata-only
+      // spans must not carry an empty `_dd: {}` block.
+      if (mlObsTags[COST_TAGS]) {
+        this.#getDdMetadata(metadata).cost_tags = mlObsTags[COST_TAGS]
+      }
+      meta.metadata = metadata
+    }
+
+    if (mlObsTags[TOOL_DEFINITIONS]) {
+      meta.tool_definitions = []
+      this.#addObject(mlObsTags[TOOL_DEFINITIONS], meta.tool_definitions)
     }
 
+    const llmObsSpan = new LLMObservabilitySpan(spanKind)
+
     if (spanKind === 'llm' && mlObsTags[INPUT_MESSAGES]) {
       llmObsSpan.input = mlObsTags[INPUT_MESSAGES]
       inputType = 'messages'
     } else if (spanKind === 'embedding' && mlObsTags[INPUT_DOCUMENTS]) {
-      input.documents = mlObsTags[INPUT_DOCUMENTS]
+      llmObsSpan.input = mlObsTags[INPUT_DOCUMENTS].map(doc => ({ content: doc.text, role: '' }))
+      inputType = 'documents'
     } else if (mlObsTags[INPUT_VALUE]) {
       llmObsSpan.input = [{ role: '', content: mlObsTags[INPUT_VALUE] }]
       inputType = 'value'
@@ -148,7 +171,8 @@ class LLMObsSpanProcessor {
       llmObsSpan.output = mlObsTags[OUTPUT_MESSAGES]
       outputType = 'messages'
     } else if (spanKind === 'retrieval' && mlObsTags[OUTPUT_DOCUMENTS]) {
-      output.documents = mlObsTags[OUTPUT_DOCUMENTS]
+      llmObsSpan.output = mlObsTags[OUTPUT_DOCUMENTS].map(doc => ({ content: doc.text, role: '' }))
+      outputType = 'documents'
     } else if (mlObsTags[OUTPUT_VALUE]) {
       llmObsSpan.output = [{ role: '', content: mlObsTags[OUTPUT_VALUE] }]
       outputType = 'value'
@@ -180,6 +204,11 @@ class LLMObsSpanProcessor {
         input.messages = processedSpan.input
       } else if (inputType === 'value') {
         input.value = processedSpan.input[0].content
+      } else if (inputType === 'documents') {
+        input.documents = processedSpan.input.map((processedDocument, processedDocumentIdx) => ({
+          ...mlObsTags[INPUT_DOCUMENTS][processedDocumentIdx],
+          text: processedDocument.content,
+        }))
       }
     }
 
@@ -188,6 +217,11 @@ class LLMObsSpanProcessor {
         output.messages = processedSpan.output
       } else if (outputType === 'value') {
         output.value = processedSpan.output[0].content
+      } else if (outputType === 'documents') {
+        output.documents = processedSpan.output.map((processedDocument, processedDocumentIdx) => ({
+          ...mlObsTags[OUTPUT_DOCUMENTS][processedDocumentIdx],
+          text: processedDocument.content,
+        }))
       }
     }
 
@@ -259,6 +293,18 @@ class LLMObsSpanProcessor {
     add(obj, carrier)
   }
 
+  /**
+   * Returns `metadata._dd`, normalizing it to a fresh object if missing or invalid.
+   * @param {Record<string, unknown>} metadata
+   * @returns {Record<string, unknown>}
+   */
+  #getDdMetadata (metadata) {
+    if (!metadata._dd || typeof metadata._dd !== 'object' || Array.isArray(metadata._dd)) {
+      metadata._dd = {}
+    }
+    return metadata._dd
+  }
+
   #getTags (span, mlApp, sessionId, error) {
     let tags = {
       ...this.#config.parsedDdTags,

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

@@ -12,7 +12,9 @@ const {
   INPUT_DOCUMENTS,
   OUTPUT_VALUE,
   METADATA,
+  COST_TAGS,
   METRICS,
+  TOOL_DEFINITIONS,
   PARENT_ID_KEY,
   INPUT_MESSAGES,
   OUTPUT_MESSAGES,
@@ -41,6 +43,7 @@ const {
   INSTRUMENTATION_METHOD_ANNOTATED,
 } = require('./constants/tags')
 const { storage } = require('./storage')
+const { validateCostTags } = require('./util')
 
 // global registry of LLMObs spans
 // maps LLMObs spans to their annotations
@@ -120,6 +123,11 @@ class LLMObsTagger {
     const tags = annotationContext?.tags
     if (tags) this.tagSpanTags(span, tags)
 
+    // apply after tags so only keys present at span start are accepted.
+    if (annotationContext?.costTags != null) {
+      this.tagCostTags(span, annotationContext.costTags, 'annotation_context')
+    }
+
     // apply annotation context name
     const annotationContextName = annotationContext?.name
     if (annotationContextName) this._setTag(span, NAME, annotationContextName)
@@ -159,6 +167,14 @@ class LLMObsTagger {
     this.#tagText(span, outputData, OUTPUT_VALUE)
   }
 
+  tagToolDefinitions (span, toolDefinitions) {
+    if (Array.isArray(toolDefinitions) && toolDefinitions.length > 0) {
+      this._setTag(span, TOOL_DEFINITIONS, toolDefinitions)
+    } else {
+      this.#handleFailure('Tool definitions must be a non-empty array.', 'invalid_tool_definitions')
+    }
+  }
+
   tagMetadata (span, metadata) {
     const existingMetadata = registry.get(span)?.[METADATA]
     if (existingMetadata) {
@@ -225,6 +241,32 @@ class LLMObsTagger {
     }
   }
 
+  /**
+   * Validates and tags cost tag keys on an LLMObs span. Cost tag references are validated against
+   * the span's already-applied tags, which are read from the registry.
+   * @param {import('../opentracing/span')} span
+   * @param {unknown} costTags Raw user-provided cost tags; validated here.
+   * @param {'annotate' | 'annotation_context'} source
+   */
+  tagCostTags (span, costTags, source) {
+    const spanTags = registry.get(span)?.[TAGS] || {}
+    const validatedCostTags = validateCostTags(span, costTags, source, spanTags)
+    if (!validatedCostTags.length) return
+
+    // Might consider switching to a `Set` if per-span cost tag cardinality grows large enough that
+    // this `.includes`/`.push` merge becomes a hot spot
+    const currentCostTags = registry.get(span)?.[COST_TAGS]
+    if (currentCostTags) {
+      for (const costTag of validatedCostTags) {
+        if (!currentCostTags.includes(costTag)) {
+          currentCostTags.push(costTag)
+        }
+      }
+    } else {
+      this._setTag(span, COST_TAGS, validatedCostTags)
+    }
+  }
+
   /**
    * Tags a prompt on an LLMObs span.
    * @param {import('../opentracing/span')} span

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

@@ -6,6 +6,7 @@ const telemetryMetrics = require('../telemetry/metrics')
 const {
   SPAN_KIND,
   MODEL_PROVIDER,
+  ML_APP,
   PARENT_ID_KEY,
   SESSION_ID,
   ROOT_PARENT_ID,
@@ -123,6 +124,32 @@ function recordLLMObsAnnotate (span, err, value = 1) {
   llmobsMetrics.count('annotations', tags).inc(value)
 }
 
+function recordCostTagsAnnotated (span, source, value = 1) {
+  const mlObsTags = LLMObsTagger.tagMap.get(span) || {}
+  const tags = {
+    span_kind: mlObsTags[SPAN_KIND] || 'N/A',
+    source,
+    ml_app: mlObsTags[ML_APP] || 'N/A',
+    model_provider: mlObsTags[MODEL_PROVIDER] || 'N/A',
+  }
+
+  llmobsMetrics.count('cost_tags.annotated', tags).inc(value)
+}
+
+function recordCostTagsSubmitted (span, count, source, state, reason = 'none') {
+  const mlObsTags = LLMObsTagger.tagMap.get(span) || {}
+  const tags = {
+    span_kind: mlObsTags[SPAN_KIND] || 'N/A',
+    source,
+    ml_app: mlObsTags[ML_APP] || 'N/A',
+    model_provider: mlObsTags[MODEL_PROVIDER] || 'N/A',
+    state,
+    reason,
+  }
+
+  llmobsMetrics.count('cost_tags.submitted', tags).inc(count)
+}
+
 function recordUserFlush (err, value = 1) {
   const tags = { error: Number(!!err) }
   if (err) tags.error_type = err
@@ -167,6 +194,8 @@ module.exports = {
   recordLLMObsSpanSize,
   recordDroppedPayload,
   recordLLMObsAnnotate,
+  recordCostTagsAnnotated,
+  recordCostTagsSubmitted,
   recordUserFlush,
   recordExportSpan,
   recordSubmitEvaluation,

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

@@ -1,14 +1,26 @@
 'use strict'
 
+const log = require('../log')
 const { SPAN_KINDS } = require('./constants/tags')
 
+// LLM I/O is overwhelmingly ASCII (English prompts and code). Walk once
+// looking for the first non-ASCII char; if there is none, hand the input
+// straight back. Otherwise pick up the slow path from the byte that needed
+// escaping. ~5x faster on typical prompt strings than the per-char `+=`
+// loop the function used to do unconditionally.
 function encodeUnicode (str = '') {
-  let result = ''
-  for (let i = 0; i < str.length; i++) {
-    const code = str.charCodeAt(i)
-    result += code > 127 ? String.raw`\u${code.toString(16).padStart(4, '0')}` : str[i]
+  for (let index = 0; index < str.length; index++) {
+    if (str.charCodeAt(index) > 127) {
+      let result = str.slice(0, index)
+      // eslint-disable-next-line sonarjs/updated-loop-counter -- inner loop continues from outer position
+      for (; index < str.length; index++) {
+        const code = str.charCodeAt(index)
+        result += code > 127 ? String.raw`\u${code.toString(16).padStart(4, '0')}` : str[index]
+      }
+      return result
+    }
   }
-  return result
+  return str
 }
 
 function validateKind (kind) {
@@ -22,6 +34,57 @@ function validateKind (kind) {
   return kind
 }
 
+/**
+ * Validates cost tag keys and records telemetry for the annotation source.
+ * @param {import('../opentracing/span')} span
+ * @param {unknown} costTags
+ * @param {string} source
+ * @param {Record<string, unknown>} spanTags
+ * @returns {string[]}
+ */
+function validateCostTags (span, costTags, source, spanTags) {
+  // Lazy-required to avoid the `index.js -> telemetry -> tagger -> util` module cycle.
+  const telemetry = require('./telemetry')
+
+  telemetry.recordCostTagsAnnotated(span, source)
+
+  if (!Array.isArray(costTags)) {
+    log.warn('costTags must be an array of strings. Ignoring value.')
+    telemetry.recordCostTagsSubmitted(span, 1, source, 'error', 'non_list')
+    return []
+  }
+
+  const validatedCostTags = new Set()
+  let nonStringEntries = 0
+  let missingSpanTags = 0
+
+  for (const costTag of costTags) {
+    if (typeof costTag !== 'string') {
+      log.warn('costTags entries must be strings. Skipping entry %s.', costTag)
+      nonStringEntries++
+      continue
+    }
+    if (!Object.hasOwn(spanTags, costTag)) {
+      log.warn('costTags entry "%s" must reference a key present in span tags. Skipping entry.', costTag)
+      missingSpanTags++
+      continue
+    }
+    validatedCostTags.add(costTag)
+  }
+
+  if (nonStringEntries) {
+    telemetry.recordCostTagsSubmitted(span, nonStringEntries, source, 'error', 'non_string_entry')
+  }
+  if (missingSpanTags) {
+    telemetry.recordCostTagsSubmitted(span, missingSpanTags, source, 'error', 'missing_span_tag')
+  }
+  if (validatedCostTags.size) {
+    telemetry.recordCostTagsSubmitted(span, validatedCostTags.size, source, 'success')
+  }
+
+  return [...validatedCostTags]
+}
+
 // extracts the argument names from a function string
 function parseArgumentNames (str) {
   const result = []
@@ -174,9 +237,22 @@ function spanHasError (span) {
   return !!(tags.error || tags['error.type'])
 }
 
+// LLM SDKs stream tool-call argument JSON across SSE chunks; a malformed
+// accumulation would otherwise throw straight into the chunk subscriber.
+function safeJsonParse (value, fallback) {
+  if (typeof value !== 'string') return value
+  try {
+    return JSON.parse(value)
+  } catch {
+    return fallback === undefined ? value : fallback
+  }
+}
+
 module.exports = {
   encodeUnicode,
+  validateCostTags,
   validateKind,
   getFunctionArguments,
+  safeJsonParse,
   spanHasError,
 }