dd-trace 5.67.0 → 5.69.0

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

@@ -0,0 +1,191 @@
+'use strict'
+
+const pkg = require('./pkg')
+const { GRPC_CLIENT_ERROR_STATUSES, GRPC_SERVER_ERROR_STATUSES } = require('./constants')
+const { getEnvironmentVariables } = require('./config-helper')
+
+// eslint-disable-next-line @stylistic/max-len
+const qsRegex = String.raw`(?:p(?:ass)?w(?:or)?d|pass(?:_?phrase)?|secret|(?:api_?|private_?|public_?|access_?|secret_?)key(?:_?id)?|token|consumer_?(?:id|key|secret)|sign(?:ed|ature)?|auth(?:entication|orization)?)(?:(?:\s|%20)*(?:=|%3D)[^&]+|(?:"|%22)(?:\s|%20)*(?::|%3A)(?:\s|%20)*(?:"|%22)(?:%2[^2]|%[^2]|[^"%])+(?:"|%22))|bearer(?:\s|%20)+[a-z0-9\._\-]+|token(?::|%3A)[a-z0-9]{13}|gh[opsu]_[0-9a-zA-Z]{36}|ey[I-L](?:[\w=-]|%3D)+\.ey[I-L](?:[\w=-]|%3D)+(?:\.(?:[\w.+\/=-]|%3D|%2F|%2B)+)?|[\-]{5}BEGIN(?:[a-z\s]|%20)+PRIVATE(?:\s|%20)KEY[\-]{5}[^\-]+[\-]{5}END(?:[a-z\s]|%20)+PRIVATE(?:\s|%20)KEY|ssh-rsa(?:\s|%20)*(?:[a-z0-9\/\.+]|%2F|%5C|%2B){100,}`
+// eslint-disable-next-line @stylistic/max-len
+const defaultWafObfuscatorKeyRegex = String.raw`(?i)pass|pw(?:or)?d|secret|(?:api|private|public|access)[_-]?key|token|consumer[_-]?(?:id|key|secret)|sign(?:ed|ature)|bearer|authorization|jsessionid|phpsessid|asp\.net[_-]sessionid|sid|jwt`
+// eslint-disable-next-line @stylistic/max-len
+const defaultWafObfuscatorValueRegex = String.raw`(?i)(?:p(?:ass)?w(?:or)?d|pass(?:[_-]?phrase)?|secret(?:[_-]?key)?|(?:(?:api|private|public|access)[_-]?)key(?:[_-]?id)?|(?:(?:auth|access|id|refresh)[_-]?)?token|consumer[_-]?(?:id|key|secret)|sign(?:ed|ature)?|auth(?:entication|orization)?|jsessionid|phpsessid|asp\.net(?:[_-]|-)sessionid|sid|jwt)(?:\s*=([^;&]+)|"\s*:\s*("[^"]+"|\d+))|bearer\s+([a-z0-9\._\-]+)|token\s*:\s*([a-z0-9]{13})|gh[opsu]_([0-9a-zA-Z]{36})|ey[I-L][\w=-]+\.(ey[I-L][\w=-]+(?:\.[\w.+\/=-]+)?)|[\-]{5}BEGIN[a-z\s]+PRIVATE\sKEY[\-]{5}([^\-]+)[\-]{5}END[a-z\s]+PRIVATE\sKEY|ssh-rsa\s*([a-z0-9\/\.+]{100,})`
+
+const {
+  AWS_LAMBDA_FUNCTION_NAME,
+  FUNCTION_NAME,
+  K_SERVICE,
+  WEBSITE_SITE_NAME
+} = getEnvironmentVariables()
+
+const service = AWS_LAMBDA_FUNCTION_NAME ||
+  FUNCTION_NAME || // Google Cloud Function Name set by deprecated runtimes
+  K_SERVICE || // Google Cloud Function Name set by newer runtimes
+  WEBSITE_SITE_NAME || // set by Azure Functions
+  pkg.name ||
+  'node'
+
+module.exports = {
+  apmTracingEnabled: true,
+  'appsec.apiSecurity.enabled': true,
+  'appsec.apiSecurity.sampleDelay': 30,
+  'appsec.apiSecurity.endpointCollectionEnabled': true,
+  'appsec.apiSecurity.endpointCollectionMessageLimit': 300,
+  'appsec.blockedTemplateGraphql': undefined,
+  'appsec.blockedTemplateHtml': undefined,
+  'appsec.blockedTemplateJson': undefined,
+  'appsec.enabled': undefined,
+  'appsec.eventTracking.mode': 'identification',
+  'appsec.extendedHeadersCollection.enabled': false,
+  'appsec.extendedHeadersCollection.redaction': true,
+  'appsec.extendedHeadersCollection.maxHeaders': 50,
+  'appsec.obfuscatorKeyRegex': defaultWafObfuscatorKeyRegex,
+  'appsec.obfuscatorValueRegex': defaultWafObfuscatorValueRegex,
+  'appsec.rasp.enabled': true,
+  'appsec.rasp.bodyCollection': false,
+  'appsec.rateLimit': 100,
+  'appsec.rules': undefined,
+  'appsec.sca.enabled': null,
+  'appsec.stackTrace.enabled': true,
+  'appsec.stackTrace.maxDepth': 32,
+  'appsec.stackTrace.maxStackTraces': 2,
+  'appsec.wafTimeout': 5e3, // µs
+  baggageMaxBytes: 8192,
+  baggageMaxItems: 64,
+  baggageTagKeys: 'user.id,session.id,account.id',
+  clientIpEnabled: false,
+  clientIpHeader: null,
+  'crashtracking.enabled': true,
+  'codeOriginForSpans.enabled': true,
+  'codeOriginForSpans.experimental.exit_spans.enabled': false,
+  dbmPropagationMode: 'disabled',
+  'dogstatsd.hostname': '127.0.0.1',
+  'dogstatsd.port': '8125',
+  dsmEnabled: false,
+  'dynamicInstrumentation.enabled': false,
+  'dynamicInstrumentation.probeFile': undefined,
+  'dynamicInstrumentation.redactedIdentifiers': [],
+  'dynamicInstrumentation.redactionExcludedIdentifiers': [],
+  'dynamicInstrumentation.uploadIntervalSeconds': 1,
+  env: undefined,
+  'experimental.aiguard.enabled': false,
+  'experimental.aiguard.endpoint': undefined,
+  'experimental.aiguard.maxMessagesLength': 16,
+  'experimental.aiguard.maxContentSize': 512 * 1024,
+  'experimental.aiguard.timeout': 10_000, // ms
+  'experimental.enableGetRumData': false,
+  'experimental.exporter': undefined,
+  flushInterval: 2000,
+  flushMinSpans: 1000,
+  gitMetadataEnabled: true,
+  graphqlErrorExtensions: [],
+  'grpc.client.error.statuses': GRPC_CLIENT_ERROR_STATUSES,
+  'grpc.server.error.statuses': GRPC_SERVER_ERROR_STATUSES,
+  headerTags: [],
+  'heapSnapshot.count': 0,
+  'heapSnapshot.destination': '',
+  'heapSnapshot.interval': 3600,
+  hostname: '127.0.0.1',
+  'iast.dbRowsToTaint': 1,
+  'iast.deduplicationEnabled': true,
+  'iast.enabled': false,
+  'iast.maxConcurrentRequests': 2,
+  'iast.maxContextOperations': 2,
+  'iast.redactionEnabled': true,
+  'iast.redactionNamePattern': null,
+  'iast.redactionValuePattern': null,
+  'iast.requestSampling': 30,
+  'iast.securityControlsConfiguration': null,
+  'iast.telemetryVerbosity': 'INFORMATION',
+  'iast.stackTrace.enabled': true,
+  injectionEnabled: [],
+  instrumentationSource: 'manual',
+  injectForce: null,
+  isAzureFunction: false,
+  isCiVisibility: false,
+  isEarlyFlakeDetectionEnabled: false,
+  isFlakyTestRetriesEnabled: false,
+  flakyTestRetriesCount: 5,
+  isGCPFunction: false,
+  isGitUploadEnabled: false,
+  isIntelligentTestRunnerEnabled: false,
+  isManualApiEnabled: false,
+  'langchain.spanCharLimit': 128,
+  'langchain.spanPromptCompletionSampleRate': 1,
+  'llmobs.agentlessEnabled': undefined,
+  'llmobs.enabled': false,
+  'llmobs.mlApp': undefined,
+  ciVisibilityTestSessionName: '',
+  ciVisAgentlessLogSubmissionEnabled: false,
+  legacyBaggageEnabled: true,
+  isTestDynamicInstrumentationEnabled: false,
+  isServiceUserProvided: false,
+  testManagementAttemptToFixRetries: 20,
+  isTestManagementEnabled: false,
+  isImpactedTestsEnabled: false,
+  logInjection: true,
+  lookup: undefined,
+  inferredProxyServicesEnabled: false,
+  memcachedCommandEnabled: false,
+  middlewareTracingEnabled: true,
+  openAiLogsEnabled: false,
+  'openai.spanCharLimit': 128,
+  peerServiceMapping: {},
+  plugins: true,
+  port: '8126',
+  'profiling.enabled': undefined,
+  'profiling.exporters': 'agent',
+  'profiling.sourceMap': true,
+  'profiling.longLivedThreshold': undefined,
+  protocolVersion: '0.4',
+  queryStringObfuscation: qsRegex,
+  'remoteConfig.enabled': true,
+  'remoteConfig.pollInterval': 5, // seconds
+  reportHostname: false,
+  'runtimeMetrics.enabled': false,
+  'runtimeMetrics.eventLoop': true,
+  'runtimeMetrics.gc': true,
+  runtimeMetricsRuntimeId: false,
+  sampleRate: undefined,
+  'sampler.rateLimit': 100,
+  'sampler.rules': [],
+  'sampler.spanSamplingRules': [],
+  scope: undefined,
+  service,
+  serviceMapping: {},
+  site: 'datadoghq.com',
+  spanAttributeSchema: 'v0',
+  spanComputePeerService: false,
+  spanLeakDebug: 0,
+  spanRemoveIntegrationFromService: false,
+  startupLogs: false,
+  'stats.enabled': false,
+  tags: {},
+  tagsHeaderMaxLength: 512,
+  'telemetry.debug': false,
+  'telemetry.dependencyCollection': true,
+  'telemetry.enabled': true,
+  'telemetry.heartbeatInterval': 60_000,
+  'telemetry.logCollection': true,
+  'telemetry.metrics': true,
+  traceEnabled: true,
+  traceId128BitGenerationEnabled: true,
+  traceId128BitLoggingEnabled: true,
+  tracePropagationExtractFirst: false,
+  tracePropagationBehaviorExtract: 'continue',
+  'tracePropagationStyle.inject': ['datadog', 'tracecontext', 'baggage'],
+  'tracePropagationStyle.extract': ['datadog', 'tracecontext', 'baggage'],
+  'tracePropagationStyle.otelPropagators': false,
+  traceWebsocketMessagesEnabled: false,
+  traceWebsocketMessagesInheritSampling: true,
+  traceWebsocketMessagesSeparateTraces: true,
+  tracing: true,
+  url: undefined,
+  version: pkg.version,
+  instrumentation_config_id: undefined,
+  'vertexai.spanCharLimit': 128,
+  'vertexai.spanPromptCompletionSampleRate': 1,
+  'trace.aws.addSpanPointers': true,
+  'trace.dynamoDb.tablePrimaryKeys': undefined,
+  'trace.nativeSpanEvents': false
+}

package/packages/dd-trace/src/crashtracking/crashtracker.js

@@ -5,6 +5,7 @@ const libdatadog = require('@datadog/libdatadog')
 const binding = libdatadog.load('crashtracker')
 
 const log = require('../log')
+const defaults = require('../config_defaults')
 const { URL } = require('url')
 const pkg = require('../../../../package.json')
 
@@ -49,7 +50,7 @@ class Crashtracker {
 
   // TODO: Send only configured values when defaults are fixed.
   #getConfig (config) {
-    const { hostname = '127.0.0.1', port = 8126 } = config
+    const { hostname = defaults.hostname, port = defaults.port } = config
     const url = config.url || new URL(`http://${hostname}:${port}`)
 
     return {

package/packages/dd-trace/src/datastreams/fnv.js

@@ -1,7 +1,7 @@
 'use strict'
 
-const FNV_64_PRIME = BigInt('0x100000001B3')
-const FNV1_64_INIT = BigInt('0xCBF29CE484222325')
+const FNV_64_PRIME = 0x1_00_00_00_01_B3n
+const FNV1_64_INIT = 0xCB_F2_9C_E4_84_22_23_25n
 
 function fnv (data, hvalInit, fnvPrime, fnvSize) {
   let hval = hvalInit

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

@@ -11,7 +11,14 @@ const {
 // plugins instead of having dedicated DSM plugins that are themselves
 // lazy loaded.
 //
-// TODO: Remove this when DSM has been moved to dedicaed plugins.
+// TODO: Remove this when DSM has been moved to dedicated plugins.
+/**
+ * @template T extends new (...args: any[]) => any
+ * @param {() => T} classGetter
+ * @param {string[]} methods
+ * @param {string[]} staticMethods
+ * @returns {T}
+ */
 function lazyClass (classGetter, methods = [], staticMethods = []) {
   let constructorArgs
   let ActiveClass
@@ -50,22 +57,34 @@ function lazyClass (classGetter, methods = [], staticMethods = []) {
   return LazyClass
 }
 
+/**
+ * @type {typeof import('./pathway').DsmPathwayCodec}
+ */
 const DsmPathwayCodec = lazyClass(() => require('./pathway').DsmPathwayCodec, [], [
   'encode',
   'decode'
 ])
 
+/**
+ * @type {typeof import('./checkpointer').DataStreamsCheckpointer}
+ */
 const DataStreamsCheckpointer = lazyClass(() => require('./checkpointer').DataStreamsCheckpointer, [
   'setProduceCheckpoint',
   'setConsumeCheckpoint'
 ])
 
+/**
+ * @type {typeof import('./manager').DataStreamsManager}
+ */
 const DataStreamsManager = lazyClass(() => require('./manager').DataStreamsManager, [
   'setCheckpoint',
   'decodeDataStreamsContext'
 ])
 
 // TODO: Are all those methods actually public?
+/**
+ * @type {typeof import('./processor').DataStreamsProcessor}
+ */
 const DataStreamsProcessor = lazyClass(() => require('./processor').DataStreamsProcessor, [
   'onInterval',
   'bucketFromTimestamp',
@@ -79,6 +98,9 @@ const DataStreamsProcessor = lazyClass(() => require('./processor').DataStreamsP
   'getSchema'
 ])
 
+/**
+ * @type {typeof import('./schemas/schema_builder').SchemaBuilder}
+ */
 const SchemaBuilder = lazyClass(() => require('./schemas/schema_builder').SchemaBuilder, [
   'build',
   'addProperty',

package/packages/dd-trace/src/datastreams/writer.js

@@ -5,6 +5,7 @@ const log = require('../log')
 const request = require('../exporters/common/request')
 const { URL, format } = require('url')
 const { MsgpackEncoder } = require('../msgpack')
+const defaults = require('../config_defaults')
 const zlib = require('zlib')
 
 const msgpack = new MsgpackEncoder()
@@ -31,10 +32,10 @@ function makeRequest (data, url, cb) {
 
 class DataStreamsWriter {
   constructor (config) {
-    const { hostname = '127.0.0.1', port = 8126, url } = config
+    const { hostname = defaults.hostname, port = defaults.port, url } = config
     this._url = url || new URL(format({
       protocol: 'http:',
-      hostname: hostname || 'localhost',
+      hostname,
       port
     }))
   }

package/packages/dd-trace/src/debugger/devtools_client/config.js

@@ -3,6 +3,7 @@
 const { workerData: { config: parentConfig, parentThreadId, configPort } } = require('node:worker_threads')
 const { format } = require('node:url')
 const log = require('./log')
+const defaults = require('../../config_defaults')
 
 const config = module.exports = {
   ...parentConfig,
@@ -20,7 +21,7 @@ configPort.on('messageerror', (err) =>
 function updateUrl (updates) {
   config.url = updates.url || format({
     protocol: 'http:',
-    hostname: updates.hostname || 'localhost',
+    hostname: updates.hostname || defaults.hostname,
     port: updates.port
   })
 }

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

@@ -7,6 +7,7 @@ const isIP = require('net').isIP
 const log = require('./log')
 const { URL, format } = require('url')
 const Histogram = require('./histogram')
+const defaults = require('./config_defaults')
 
 const MAX_BUFFER_SIZE = 1024 // limit from the agent
 
@@ -28,9 +29,9 @@ class DogStatsDClient {
       }
     }
 
-    this._host = options.host || 'localhost'
+    this._host = options.host || defaults['dogstatsd.hostname']
     this._family = isIP(this._host)
-    this._port = options.port || 8125
+    this._port = options.port || defaults['dogstatsd.port']
     this._prefix = options.prefix || ''
     this._tags = options.tags || []
     this._queue = []
@@ -182,7 +183,7 @@ class DogStatsDClient {
     } else if (config.port) {
       clientConfig.metricsProxyUrl = new URL(format({
         protocol: 'http:',
-        hostname: config.hostname || 'localhost',
+        hostname: config.hostname || defaults.hostname,
         port: config.port
       }))
     }

package/packages/dd-trace/src/encode/0.4.js

@@ -4,7 +4,6 @@ const { truncateSpan, normalizeSpan } = require('./tags-processors')
 const { Chunk, MsgpackEncoder } = require('../msgpack')
 const log = require('../log')
 const { isTrue } = require('../util')
-const coalesce = require('koalas')
 const { memoize } = require('../log/utils')
 const { getEnvironmentVariable } = require('../config-helper')
 
@@ -32,10 +31,7 @@ class AgentEncoder {
     this._stringBytes = new Chunk()
     this._writer = writer
     this._reset()
-    this._debugEncoding = isTrue(coalesce(
-      getEnvironmentVariable('DD_TRACE_ENCODING_DEBUG'),
-      false
-    ))
+    this._debugEncoding = isTrue(getEnvironmentVariable('DD_TRACE_ENCODING_DEBUG'))
     this._config = this._writer?._config
   }
 

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

@@ -19,6 +19,7 @@ module.exports = function getExporter (name) {
     case exporters.CUCUMBER_WORKER:
     case exporters.MOCHA_WORKER:
     case exporters.PLAYWRIGHT_WORKER:
+    case exporters.VITEST_WORKER:
       return require('./ci-visibility/exporters/test-worker')
     default: {
       const inAWSLambda = getEnvironmentVariable('AWS_LAMBDA_FUNCTION_NAME') !== undefined

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

@@ -3,16 +3,17 @@
 const { URL, format } = require('url')
 const log = require('../../log')
 const Writer = require('./writer')
+const defaults = require('../../config_defaults')
 
 class AgentExporter {
   #timer
 
   constructor (config, prioritySampler) {
     this._config = config
-    const { url, hostname, port, lookup, protocolVersion, stats = {}, apmTracingEnabled } = config
+    const { url, hostname = defaults.hostname, port, lookup, protocolVersion, stats = {}, apmTracingEnabled } = config
     this._url = url || new URL(format({
       protocol: 'http:',
-      hostname: hostname || 'localhost',
+      hostname,
       port
     }))
 

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

@@ -42,7 +42,7 @@ class Writer extends BaseWriter {
       startupLog({ agentError: err })
 
       if (err) {
-        log.error('Error sending payload to the agent (status code: %s)', err.status, err)
+        log.errorWithoutTelemetry('Error sending payload to the agent (status code: %s)', err.status, err)
         done()
         return
       }

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

@@ -3,6 +3,7 @@
 const { URL, format } = require('url')
 
 const request = require('./request')
+const defaults = require('../../config_defaults')
 const { incrementCountMetric, TELEMETRY_EVENTS_ENQUEUED_FOR_SERIALIZATION } = require('../../ci-visibility/telemetry')
 
 function fetchAgentInfo (url, callback) {
@@ -29,10 +30,10 @@ function fetchAgentInfo (url, callback) {
 class AgentInfoExporter {
   constructor (tracerConfig) {
     this._config = tracerConfig
-    const { url, hostname, port } = this._config
+    const { url, hostname = defaults.hostname, port } = this._config
     this._url = url || new URL(format({
       protocol: 'http:',
-      hostname: hostname || 'localhost',
+      hostname,
       port
     }))
     this._traceBuffer = []

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

@@ -106,11 +106,12 @@ function request (data, options, callback) {
         } catch {
           // ignore error
         }
+
         const responseData = buffer.toString()
         if (responseData) {
           errorMessage += ` Response from the endpoint: "${responseData}"`
         }
-        const error = new Error(errorMessage)
+        const error = new log.NoTransmitError(errorMessage)
         error.status = res.statusCode
 
         callback(error, null, res.statusCode)

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

@@ -3,13 +3,14 @@
 const { URL, format } = require('url')
 
 const { Writer } = require('./writer')
+const defaults = require('../../config_defaults')
 
 class SpanStatsExporter {
   constructor (config) {
-    const { hostname = '127.0.0.1', port = 8126, tags, url } = config
+    const { hostname = defaults.hostname, port = defaults.port, tags, url } = config
     this._url = url || new URL(format({
       protocol: 'http:',
-      hostname: hostname || 'localhost',
+      hostname,
       port
     }))
     this._writer = new Writer({ url: this._url, tags })

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

@@ -32,6 +32,8 @@ module.exports = {
   INPUT_TOKENS_METRIC_KEY: 'input_tokens',
   OUTPUT_TOKENS_METRIC_KEY: 'output_tokens',
   TOTAL_TOKENS_METRIC_KEY: 'total_tokens',
+  CACHE_READ_INPUT_TOKENS_METRIC_KEY: 'cache_read_input_tokens',
+  CACHE_WRITE_INPUT_TOKENS_METRIC_KEY: 'cache_write_input_tokens',
 
   DROPPED_IO_COLLECTION_ERROR: 'dropped_io'
 }

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

@@ -17,7 +17,8 @@ const {
   getModelMetadata,
   getGenerationMetadata,
   getToolNameFromTags,
-  getToolCallResultContent
+  getToolCallResultContent,
+  getLlmObsSpanName
 } = require('./util')
 
 const SPAN_NAME_TO_KIND_MAPPING = {
@@ -79,26 +80,32 @@ class VercelAILLMObsPlugin extends BaseLLMObsPlugin {
    * We use the tool description as the next best identifier for a tool.
    *
    * @param {string} toolDescription
-   * @returns {string}
+   * @returns {string | undefined}
    */
   findToolName (toolDescription) {
     for (const availableTool of this.#availableTools) {
       const description = availableTool.description
-      if (description === toolDescription) {
+      if (description === toolDescription && availableTool.id) {
         return availableTool.id
       }
     }
   }
 
+  /**
+   * @override
+   */
   getLLMObsSpanRegisterOptions (ctx) {
     const span = ctx.currentStore?.span
     const operation = getOperation(span)
     const kind = SPAN_NAME_TO_KIND_MAPPING[operation]
     if (!kind) return
 
-    return { kind, name: operation }
+    return { kind, name: getLlmObsSpanName(operation, ctx.attributes['ai.telemetry.functionId']) }
   }
 
+  /**
+   * @override
+   */
   setLLMObsTags (ctx) {
     const span = ctx.currentStore?.span
     if (!span) return
@@ -211,6 +218,10 @@ class VercelAILLMObsPlugin extends BaseLLMObsPlugin {
     this._tagger.tagMetadata(span, metadata)
   }
 
+  /**
+   * @param {import('../../../opentracing/span')} span
+   * @param {Record<string, unknown>} tags
+   */
   setLLMOperationTags (span, tags) {
     const toolsForModel = tags['ai.prompt.tools']?.map(getJsonStringValue)
 

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

@@ -34,7 +34,7 @@ function getSpanTags (ctx) {
  * getOperation(span) // 'doGenerate'
  *
  * @param {import('../../../opentracing/span')} span
- * @returns {string}
+ * @returns {string | undefined}
  */
 function getOperation (span) {
   const name = span._name
@@ -45,8 +45,9 @@ function getOperation (span) {
 
 /**
  * Get the LLM token usage from the span tags
- * @param {Record<string, string>} tags
- * @returns {{inputTokens: number, outputTokens: number, totalTokens: number}}
+ * @template T extends {inputTokens: number, outputTokens: number, totalTokens: number}
+ * @param {T} tags
+ * @returns {Pick<T, 'inputTokens' | 'outputTokens' | 'totalTokens'>}
  */
 function getUsage (tags) {
   const usage = {}
@@ -64,9 +65,10 @@ function getUsage (tags) {
 
 /**
  * Safely JSON parses a string value with a default fallback
+ * @template T typeof defaultValue
  * @param {string} str
- * @param {any} defaultValue
- * @returns {Record<string, any> | string | Array<any>}
+ * @param {T} defaultValue
+ * @returns {Record<string, unknown> | string | Array<unknown> | null | T}
  */
 function getJsonStringValue (str, defaultValue) {
   let maybeValue = defaultValue
@@ -81,7 +83,7 @@ function getJsonStringValue (str, defaultValue) {
 
 /**
  * Get the model metadata from the span tags (top_p, top_k, temperature, etc.)
- * @param {import('../../../opentracing/span')} span
+ * @param {Record<string, unknown>} tags
  * @returns {Record<string, string> | null}
  */
 function getModelMetadata (tags) {
@@ -167,6 +169,16 @@ function getToolCallResultContent (content) {
   }
 }
 
+/**
+ * Computes the LLM Observability `ai` span name
+ * @param {string} operation
+ * @param {string} functionId
+ * @returns {string}
+ */
+function getLlmObsSpanName (operation, functionId) {
+  return functionId ? `${functionId}.${operation}` : operation
+}
+
 module.exports = {
   getSpanTags,
   getOperation,
@@ -175,5 +187,6 @@ module.exports = {
   getModelMetadata,
   getGenerationMetadata,
   getToolNameFromTags,
-  getToolCallResultContent
+  getToolCallResultContent,
+  getLlmObsSpanName
 }