dd-trace 6.3.0 → 6.5.0

package/packages/dd-trace/src/exporters/common/client-library-headers.js

@@ -0,0 +1,21 @@
+'use strict'
+
+const { VERSION } = require('../../../../../version')
+
+const LANGUAGE = 'nodejs'
+
+/**
+ * Returns the canonical client-library identification headers.
+ *
+ * @param {string} [language] - Client library language name.
+ * @param {string} [version] - Client library version.
+ * @returns {Record<string, string>} Client library identification headers.
+ */
+function getClientLibraryHeaders (language = LANGUAGE, version = VERSION) {
+  return {
+    'DD-Client-Library-Language': language,
+    'DD-Client-Library-Version': version,
+  }
+}
+
+module.exports = { getClientLibraryHeaders }

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

@@ -6,12 +6,11 @@
 const { Readable } = require('stream')
 const http = require('http')
 const https = require('https')
-const net = require('net')
 const zlib = require('zlib')
 
 const { storage } = require('../../../../datadog-core')
 const log = require('../../log')
-const { parseUrl } = require('./url')
+const { isLoopbackHost, parseUrl } = require('./url')
 const docker = require('./docker')
 const { httpAgent, httpsAgent } = require('./agents')
 const {
@@ -27,21 +26,11 @@ const maxActiveBufferSize = 1024 * 1024 * 64
 
 let activeBufferSize = 0
 
-/**
- * @param {string} hostname Host as resolved by {@link parseUrl}; IPv6 is unbracketed (`::1`).
- */
-function isLoopbackHost (hostname) {
-  // The 127.0.0.0/8 block is loopback, but only when the host is an actual IPv4 literal: a
-  // hostname like `127.evil.com` shares the prefix yet resolves anywhere, so net.isIPv4 gates it.
-  return hostname === 'localhost' ||
-    hostname === '::1' ||
-    (hostname.startsWith('127.') && net.isIPv4(hostname))
-}
-
 /**
  * @param {Buffer|string|Readable|Array<Buffer|string>} data
  * @param {object} options
- * @param {(error: Error|null, result: string, statusCode: number) => void} callback
+ * @param {(error: Error|null, result?: string|null, statusCode?: number,
+ *   headers?: import('node:http').IncomingHttpHeaders) => void} callback
  */
 function request (data, options, callback) {
   if (!options.headers) {
@@ -106,34 +95,50 @@ function request (data, options, callback) {
 
   options.agent = isSecure ? httpsAgent : httpAgent
 
-  const onResponse = (res, finalize) => {
+  /**
+   * @param {import('node:http').IncomingMessage} res
+   * @param {(error: Error|null, result?: string|null, statusCode?: number,
+   *   headers?: import('node:http').IncomingHttpHeaders) => void} complete
+   * @param {(error: Error) => void} handleError
+   */
+  const onResponse = (res, complete, handleError) => {
     markEndpointReached(options)
 
     const chunks = []
 
     res.setTimeout(timeout)
 
+    res.once('aborted', () => {
+      handleError(Object.assign(new Error('Response aborted'), { code: 'ECONNRESET' }))
+    })
+    res.once('error', handleError)
+    res.once('timeout', () => {
+      const error = Object.assign(new Error('Response timed out'), { code: 'ETIMEDOUT' })
+      res.destroy(error)
+      handleError(error)
+    })
+
     res.on('data', chunk => {
       chunks.push(chunk)
     })
 
     res.once('end', () => {
-      finalize()
       const buffer = Buffer.concat(chunks)
 
       if (res.statusCode >= 200 && res.statusCode <= 299) {
-        const isGzip = res.headers['content-encoding'] === 'gzip'
+        const contentEncoding = res.headers['content-encoding']
+        const isGzip = typeof contentEncoding === 'string' && contentEncoding.toLowerCase() === 'gzip'
         if (isGzip) {
           zlib.gunzip(buffer, (err, result) => {
             if (err) {
               log.error('Could not gunzip response: %s', err.message)
-              callback(null, '', res.statusCode, res.headers)
+              complete(null, '', res.statusCode, res.headers)
             } else {
-              callback(null, result.toString(), res.statusCode, res.headers)
+              complete(null, result.toString(), res.statusCode, res.headers)
             }
           })
         } else {
-          callback(null, buffer.toString(), res.statusCode, res.headers)
+          complete(null, buffer.toString(), res.statusCode, res.headers)
         }
       } else {
         let errorMessage = ''
@@ -154,7 +159,7 @@ function request (data, options, callback) {
         const error = new log.NoTransmitError(errorMessage)
         error.status = res.statusCode
 
-        callback(error, null, res.statusCode, res.headers)
+        complete(error, null, res.statusCode, res.headers)
       }
     })
   }
@@ -162,6 +167,7 @@ function request (data, options, callback) {
   // Retries always run via setTimeout so the AsyncLocalStorage store survives
   // the gap before socket.connect(); ALS.run() does not call ALS.enterWith()
   // outside AsyncContextFrame, so a synchronous re-entry would lose the store.
+  /** @param {number} attemptIndex */
   const attempt = attemptIndex => {
     if (!request.writable) {
       log.debug('Maximum number of active requests reached: payload is discarded.')
@@ -172,28 +178,51 @@ function request (data, options, callback) {
 
     legacyStorage.run({ noop: true }, () => {
       let finished = false
+      let settled = false
       const finalize = () => {
         if (finished) return
         finished = true
         activeBufferSize -= options.headers['Content-Length'] ?? 0
       }
 
-      const req = client.request(options, (res) => onResponse(res, finalize))
-
-      req.once('close', finalize)
-      req.once('timeout', finalize)
-
-      req.once('error', error => {
+      /**
+       * @param {Error | null} error
+       * @param {string | null} [result]
+       * @param {number} [statusCode]
+       * @param {import('node:http').IncomingHttpHeaders} [headers]
+       */
+      const complete = (error, result, statusCode, headers) => {
+        if (settled) return
+        settled = true
         finalize()
-        if (attemptIndex < getMaxAttempts(options) && isRetriableNetworkError(error)) {
+        callback(error, result, statusCode, headers)
+      }
+
+      /**
+       * @param {Error} error
+       */
+      const handleError = (error) => {
+        if (settled) return
+
+        if (options.retry !== false &&
+            attemptIndex < getMaxAttempts(options) &&
+            isRetriableNetworkError(error)) {
+          settled = true
+          finalize()
           // Unref so a pending retry never keeps the host process alive past
           // its natural exit point; long-running apps still retry because the
           // event loop is held open by their own work.
           setTimeout(attempt, getRetryDelay(options, attemptIndex), attemptIndex + 1).unref?.()
         } else {
-          callback(error)
+          complete(error)
         }
-      })
+      }
+
+      const req = client.request(options, (res) => onResponse(res, complete, handleError))
+
+      req.once('close', finalize)
+      req.once('timeout', finalize)
+      req.once('error', handleError)
 
       req.setTimeout(timeout, () => {
         try {

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

@@ -1,7 +1,21 @@
 'use strict'
 
+const net = require('node:net')
+
 const { urlToHttpOptions } = require('./url-to-http-options-polyfill')
 
+/**
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+function isLoopbackHost (hostname) {
+  // Gate the 127/8 prefix on an IPv4 literal so names such as 127.example.com cannot pass.
+  return hostname === 'localhost' ||
+    hostname === '::1' ||
+    hostname === '[::1]' ||
+    (hostname.startsWith('127.') && net.isIPv4(hostname))
+}
+
 /**
  * Convert an agent/intake URL into Node http(s) request options.
  *
@@ -31,4 +45,4 @@ function parseUrl (urlObjOrString) {
   return url
 }
 
-module.exports = { parseUrl }
+module.exports = { isLoopbackHost, parseUrl }

package/packages/dd-trace/src/feature-registry.js

@@ -0,0 +1,29 @@
+'use strict'
+
+/**
+ * @typedef {{ enable: (config: import('./config/config-base')) => void, disable: () => void }} FeatureModule
+ * @typedef {new (tracer: import('./tracer'), config: import('./config/config-base')) => object} FeatureProvider
+ */
+
+/**
+ * @typedef {object} Feature
+ * @property {string} name
+ * @property {object} noop
+ * @property {() => FeatureModule} factory
+ * @property {(config: import('./config/config-base')) => boolean} isEnabled
+ * @property {() => FeatureProvider} provider
+ * @property {(rc: import('./remote_config'), config: import('./config/config-base'),
+ *   proxy: import('./proxy')) => void} [remoteConfig]
+ */
+
+/** @type {{ [name: string]: Feature }} */
+const features = {}
+
+/**
+ * @param {Feature} feature
+ */
+function registerFeature (feature) {
+  features[feature.name] = feature
+}
+
+module.exports = { features, registerFeature }

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

@@ -4,6 +4,7 @@ module.exports = {
   SPAN_KINDS: ['llm', 'agent', 'workflow', 'task', 'tool', 'embedding', 'retrieval'],
   SPAN_KIND: '_ml_obs.meta.span.kind',
   SESSION_ID: '_ml_obs.session_id',
+  SESSION_ID_TRACE_DEFAULT_KEY: '_ml_obs.trace_session_id',
   DECORATOR: '_ml_obs.decorator',
   INTEGRATION: '_ml_obs.integration',
   METADATA: '_ml_obs.meta.metadata',

package/packages/dd-trace/src/llmobs/experiments/client.js

@@ -0,0 +1,113 @@
+'use strict'
+
+// Control-plane HTTP client for LLM Obs Experiments. Uses the global `fetch`,
+// so this module adds no new dependency; credentials and site come from config.
+
+const API_BASE_PATH = '/api/v2/llm-obs/v1'
+
+// Control-plane host for a Datadog site, e.g.
+//   datadoghq.com        -> api.datadoghq.com
+//   us3.datadoghq.com    -> api.us3.datadoghq.com
+//   datad0g.com (staging)-> api.datad0g.com
+function apiHost (site) {
+  return `api.${site}`
+}
+
+// Web-app host for dashboard URLs. Single-level sites (datadoghq.com,
+// ddog-gov.com) are served from the `app.` subdomain; regional sites
+// (us3.datadoghq.com, ap1.datadoghq.com) are used as-is.
+function appHost (site) {
+  return site.split('.').length === 2 ? `app.${site}` : site
+}
+
+class ExperimentsClient {
+  #apiKey
+  #appKey
+  #site
+  #projectName
+  #timeout
+  #cachedProjectId
+
+  constructor ({ apiKey, appKey, site, projectName, timeout = 30_000 } = {}) {
+    this.#apiKey = apiKey
+    this.#appKey = appKey
+    this.#site = site
+    this.#projectName = projectName
+    this.#timeout = timeout
+    this.#cachedProjectId = null
+  }
+
+  // Whether the client has everything it needs to talk to the control plane.
+  get configured () {
+    return Boolean(this.#apiKey && this.#appKey && this.#site)
+  }
+
+  get site () {
+    return this.#site
+  }
+
+  // Dashboard URL base for the configured site, e.g. https://app.datadoghq.com
+  get appBase () {
+    return `https://${appHost(this.#site)}`
+  }
+
+  // Resolve the configured project's id (get-or-create), cached.
+  ensureProjectId () {
+    return this.getOrCreateProject(this.#projectName)
+  }
+
+  // Low-level request. Builds https://api.<site><path>, attaches both keys, and
+  // returns the parsed JSON body. Throws with status + body on a non-2xx.
+  async request (method, path, body) {
+    const url = `https://${apiHost(this.#site)}${path}`
+    const headers = {
+      'DD-API-KEY': this.#apiKey,
+      'DD-APPLICATION-KEY': this.#appKey,
+    }
+
+    let payload
+    if (body !== undefined) {
+      payload = JSON.stringify(body)
+      headers['Content-Type'] = 'application/json'
+    }
+
+    let response
+    try {
+      response = await fetch(url, {
+        method,
+        headers,
+        body: payload,
+        signal: AbortSignal.timeout(this.#timeout),
+      })
+    } catch (err) {
+      throw new Error(`${method} ${path} failed: ${err.message}`)
+    }
+
+    const text = await response.text()
+    if (!response.ok) {
+      throw new Error(`${method} ${path} failed: HTTP ${response.status} ${text}`)
+    }
+    return text ? JSON.parse(text) : {}
+  }
+
+  // Resolve the project id for `name`, creating it if absent. The create
+  // endpoint is get-or-create on name, so repeated calls return the same id.
+  // Cached after the first resolution.
+  async getOrCreateProject (name) {
+    if (this.#cachedProjectId) return this.#cachedProjectId
+
+    let response
+    try {
+      response = await this.request('POST', `${API_BASE_PATH}/projects`, {
+        data: { type: 'projects', attributes: { name } },
+      })
+    } catch (err) {
+      throw new Error(`Failed to create or get project '${name}': ${err.message}`)
+    }
+
+    this.#cachedProjectId = response?.data?.id ?? null
+    return this.#cachedProjectId
+  }
+}
+
+module.exports = { ExperimentsClient, apiHost, appHost, API_BASE_PATH }

package/packages/dd-trace/src/llmobs/experiments/dataset.js

@@ -0,0 +1,154 @@
+'use strict'
+
+const { API_BASE_PATH } = require('./client')
+
+// Immutable dataset record: { input, expectedOutput?, metadata? }.
+class DatasetRecord {
+  constructor (input, expectedOutput = null, metadata = {}) {
+    this.input = input
+    this.expectedOutput = expectedOutput ?? null
+    this.metadata = metadata ?? {}
+  }
+}
+
+// A local buffer of dataset records, created remotely and pushed on first run
+// (or eagerly via push()). Pushes are incremental.
+class Dataset {
+  #client
+  #name
+  #description
+  #records
+  #recordIds
+  #id
+  #projectId
+  #pushedCount
+
+  constructor (client, name, description = '') {
+    this.#client = client
+    this.#name = name
+    this.#description = description
+    this.#records = []
+    this.#recordIds = []
+    this.#id = null
+    this.#projectId = null
+    this.#pushedCount = 0
+  }
+
+  // Build a Dataset that already exists remotely (used by pullDataset).
+  static fromExisting (client, name, description, id, projectId, records, recordIds) {
+    const dataset = new Dataset(client, name, description)
+    dataset.#id = id
+    dataset.#projectId = projectId
+    dataset.#records.push(...records)
+    dataset.#recordIds.push(...recordIds)
+    dataset.#pushedCount = records.length
+    return dataset
+  }
+
+  // Append a record. Accepts a DatasetRecord or (input, expectedOutput?, metadata?).
+  addRecord (recordOrInput, expectedOutput, metadata) {
+    const record = recordOrInput instanceof DatasetRecord
+      ? recordOrInput
+      : new DatasetRecord(recordOrInput, expectedOutput, metadata)
+    this.#records.push(record)
+    return this
+  }
+
+  name () {
+    return this.#name
+  }
+
+  records () {
+    return [...this.#records]
+  }
+
+  recordIds () {
+    return [...this.#recordIds]
+  }
+
+  id () {
+    return this.#id
+  }
+
+  projectId () {
+    return this.#projectId
+  }
+
+  // Dashboard URL for this dataset, or null until pushed/pulled.
+  url () {
+    if (this.#id === null) return null
+    return `${this.#client.appBase}/llm/datasets/${this.#id}`
+  }
+
+  // Eagerly create the dataset (if needed) and push any unpushed records.
+  async push () {
+    const projectId = await this.#client.ensureProjectId()
+    return this.ensureCreatedAndPushed(projectId)
+  }
+
+  // Create the remote dataset if needed, then push records added since the last
+  // push. Idempotent and incremental. Resolves to { pushedCount, totalCount } for
+  // the records attempted in this call, so callers can confirm the push landed.
+  async ensureCreatedAndPushed (projectId) {
+    if (this.#id === null) {
+      let response
+      try {
+        response = await this.#client.request('POST', `${API_BASE_PATH}/${projectId}/datasets`, {
+          data: { type: 'datasets', attributes: { name: this.#name, description: this.#description } },
+        })
+      } catch (err) {
+        throw new Error(`Failed to create dataset '${this.#name}': ${err.message}`)
+      }
+      this.#id = response?.data?.id ?? null
+      this.#projectId = projectId
+    }
+
+    if (this.#pushedCount >= this.#records.length) return { pushedCount: 0, totalCount: 0 }
+
+    const pending = this.#records.slice(this.#pushedCount)
+    const records = pending.map((rec) => {
+      const out = { input: rec.input }
+      if (rec.expectedOutput !== null && rec.expectedOutput !== undefined) {
+        out.expected_output = rec.expectedOutput
+      }
+      if (rec.metadata && Object.keys(rec.metadata).length > 0) {
+        out.metadata = rec.metadata
+      }
+      return out
+    })
+
+    let response
+    try {
+      response = await this.#client.request(
+        'POST',
+        `${API_BASE_PATH}/${projectId}/datasets/${this.#id}/records`,
+        { data: { type: 'datasets', attributes: { records } } }
+      )
+    } catch (err) {
+      throw new Error(`Failed to push records to dataset '${this.#name}': ${err.message}`)
+    }
+
+    // The append-records response returns created records under a top-level
+    // `records` field, not the usual `data` envelope.
+    const created = response?.records
+    let pushedCount = 0
+    if (Array.isArray(created)) {
+      for (const node of created) {
+        const recordId = String(node?.id ?? '')
+        if (recordId !== '') pushedCount++
+        this.#recordIds.push(recordId)
+      }
+      for (let i = created.length; i < pending.length; i++) this.#recordIds.push('')
+    } else {
+      for (let i = 0; i < pending.length; i++) this.#recordIds.push('')
+    }
+
+    // Advance by the snapshotted pending count, not the live records length,
+    // so records added while this push was in flight aren't skipped by the next push.
+    this.#pushedCount += pending.length
+
+    return { pushedCount, totalCount: pending.length }
+  }
+}
+
+module.exports = { Dataset, DatasetRecord }