dd-trace 6.12.0 → 6.13.0

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

@@ -8,6 +8,8 @@ const request = require('./exporters/common/request')
 const log = require('./log')
 const Histogram = require('./histogram')
 const { entityId } = require('./exporters/common/docker')
+const { registerTelemetryFlusher } = require('./flush')
+const { createServerlessDeliveryTracker } = require('./serverless')
 
 const legacyStorage = storage('legacy')
 
@@ -25,6 +27,8 @@ const TYPE_HISTOGRAM = 'h'
 class DogStatsDClient {
   #lookup
   #tagsPrefix
+  #serverlessDeliveryTracker
+
   constructor (options) {
     this.#lookup = options.lookup
     if (options.metricsProxyUrl) {
@@ -41,6 +45,7 @@ class DogStatsDClient {
     this._tags = options.tags
     this.#tagsPrefix = this._tags?.length ? `|#${this._tags.join(',')}` : ''
     this._queue = []
+    this.#serverlessDeliveryTracker = createServerlessDeliveryTracker()
     this._buffer = ''
     this._offset = 0
     this._udp4 = this._socket('udp4')
@@ -67,23 +72,30 @@ class DogStatsDClient {
     this._add(stat, value, TYPE_HISTOGRAM, tags)
   }
 
-  flush () {
+  flush (done) {
     const queue = this._enqueue()
 
-    if (queue.length === 0) return
+    if (queue.length === 0) {
+      if (this.#serverlessDeliveryTracker) return this.#serverlessDeliveryTracker.waitForIdle(done)
+      return done?.()
+    }
 
     log.debug('Flushing %s metrics via %s', queue.length, this._httpOptions ? 'HTTP' : 'UDP')
 
     this._queue = []
 
-    if (this._httpOptions) {
-      this._sendHttp(queue)
-    } else {
-      this._sendUdp(queue)
+    const send = complete => {
+      if (this._httpOptions) this._sendHttp(queue, complete)
+      else this._sendUdp(queue, complete)
+    }
+    if (this.#serverlessDeliveryTracker) {
+      this.#serverlessDeliveryTracker.track(send)
+      return this.#serverlessDeliveryTracker.waitForIdle(done)
     }
+    send(done)
   }
 
-  _sendHttp (queue) {
+  _sendHttp (queue, done) {
     const buffer = Buffer.concat(queue)
     request(buffer, this._httpOptions, (err) => {
       if (err) {
@@ -95,32 +107,46 @@ class DogStatsDClient {
           // options. Either way, we can give UDP a try.
           this._httpOptions = undefined
         }
-        this._sendUdp(queue)
+        this._sendUdp(queue, done)
+      } else {
+        done?.()
       }
     })
   }
 
-  _sendUdp (queue) {
+  _sendUdp (queue, done) {
     // dgram resolves the local address via the instrumented dns.lookup when it
     // binds on first send; the noop store keeps that self-traffic off the trace.
     legacyStorage.run({ noop: true }, () => {
       if (this._family === 0) {
         this.#lookup(this._host, (error, address, family) => {
-          if (error) return log.error('DogStatsDClient: Host not found', error)
-          this._sendUdpFromQueue(queue, address, family)
+          if (error) {
+            log.error('DogStatsDClient: Host not found', error)
+            return done?.()
+          }
+          this._sendUdpFromQueue(queue, address, family, done)
         })
       } else {
-        this._sendUdpFromQueue(queue, this._host, this._family)
+        this._sendUdpFromQueue(queue, this._host, this._family, done)
       }
     })
   }
 
-  _sendUdpFromQueue (queue, address, family) {
+  _sendUdpFromQueue (queue, address, family, done) {
     const socket = family === 6 ? this._udp6 : this._udp4
+    let pending = queue.length
+    const complete = () => {
+      if (--pending === 0) done?.()
+    }
 
     for (const buffer of queue) {
       log.debug('Sending to DogStatsD: %s', buffer)
-      socket.send(buffer, 0, buffer.length, this._port, address)
+      try {
+        socket.send(buffer, 0, buffer.length, this._port, address, complete)
+      } catch (error) {
+        log.error('DogStatsDClient: UDP error sending metrics', error)
+        complete()
+      }
     }
   }
 
@@ -212,12 +238,12 @@ class MetricsAggregationClient {
     this.reset()
   }
 
-  flush () {
+  flush (done) {
     this._captureCounters()
     this._captureGauges()
     this._captureHistograms()
 
-    this._client.flush()
+    this._client.flush(done)
   }
 
   reset () {
@@ -370,6 +396,7 @@ class CustomMetrics {
     setInterval(flush, 10 * 1000).unref?.()
 
     globalThis[Symbol.for('dd-trace')].beforeExitHandlers.add(flush)
+    registerTelemetryFlusher(done => this.flush(done))
   }
 
   increment (stat, value = 1, tags) {
@@ -392,8 +419,8 @@ class CustomMetrics {
     this.#client.histogram(stat, value, CustomMetrics.tagTranslator(tags))
   }
 
-  flush () {
-    return this.#client.flush()
+  flush (done) {
+    return this.#client.flush(done)
   }
 
   /**

package/packages/dd-trace/src/encode/agentless-json.js

@@ -167,17 +167,18 @@ class AgentlessJSONEncoder {
       const metadataPrefix = metadataJson.slice(0, -1)
       const hasMetadata = metadataPrefix.length > 1 // more than just '{'
 
-      const traceParts = []
+      let tracesJson = ''
       for (const spanStrings of this._traces) {
         const spansJson = '[' + spanStrings.join(',') + ']'
+        if (tracesJson) tracesJson += ','
         if (hasMetadata) {
-          traceParts.push(metadataPrefix + ',"spans":' + spansJson + '}')
+          tracesJson += metadataPrefix + ',"spans":' + spansJson + '}'
         } else {
-          traceParts.push('{"spans":' + spansJson + '}')
+          tracesJson += '{"spans":' + spansJson + '}'
         }
       }
 
-      const payload = '{"traces":[' + traceParts.join(',') + ']}'
+      const payload = '{"traces":[' + tracesJson + ']}'
       this._reset()
       return Buffer.from(payload, 'utf8')
     } catch (err) {

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

@@ -2,12 +2,15 @@
 
 const { URL } = require('url')
 const log = require('../../log')
+const { createServerlessDeliveryTracker } = require('../../serverless')
 const Writer = require('./writer')
 
 class AgentExporter {
   #timer
+  #serverlessDeliveryTracker
 
   constructor (config, prioritySampler) {
+    this.#serverlessDeliveryTracker = createServerlessDeliveryTracker()
     this._config = config
     const { lookup, protocolVersion, stats = {}, apmTracingEnabled } = config
     this._url = config.url
@@ -23,6 +26,7 @@ class AgentExporter {
       lookup,
       protocolVersion,
       headers,
+      deliveryTracker: this.#serverlessDeliveryTracker,
     })
 
     globalThis[Symbol.for('dd-trace')].beforeExitHandlers.add(this.flush.bind(this))
@@ -54,10 +58,26 @@ class AgentExporter {
     }
   }
 
-  flush (done = () => {}) {
+  flush (done) {
     clearTimeout(this.#timer)
     this.#timer = undefined
-    this._writer.flush(done)
+
+    if (!this.#serverlessDeliveryTracker) {
+      try {
+        return this._writer.flush(done)
+      } catch (error) {
+        log.error('Failed to flush traces: %s', error.message)
+        done?.()
+        return
+      }
+    }
+
+    try {
+      this._writer.flush()
+    } catch (error) {
+      log.error('Failed to flush traces: %s', error.message)
+    }
+    this.#serverlessDeliveryTracker.waitForIdle(done)
   }
 }
 

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

@@ -39,18 +39,18 @@ class AgentWriter extends BaseWriter {
   }
 
   /**
-   * Flushes payloads, including requests already in flight during Test Optimization finalization.
-   *
+   * Performs the writer flush without registering a serverless delivery.
+   * Test Optimization owns its own request lifecycle tracking.
    * @param {(error?: Error) => void} [done]
    * @param {{ deadline?: number }} [options]
    * @returns {void}
    */
-  flush (done, options) {
+  flushDirect (done, options) {
     if (this.#requestTracker) {
       this.#requestTracker.flush(done, options)
       return
     }
-    super.flush(done, options)
+    super.flushDirect(done, options)
   }
 
   _sendPayload (data, count, done, flushOptions) {

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

@@ -10,14 +10,36 @@ const { safeJSONStringify } = require('./util')
 const firstFlushChannel = channel('dd-trace:exporter:first-flush')
 
 class Writer {
-  constructor ({ url, beforeFirstFlush }) {
+  #deliveryTracker
+
+  constructor ({ url, beforeFirstFlush, deliveryTracker }) {
     this._url = url
     this._beforeFirstFlush = beforeFirstFlush
+    this.#deliveryTracker = deliveryTracker
   }
 
   #isFirstFlush = true
 
-  flush (done = () => {}, options) {
+  /**
+   * Flushes queued telemetry, retaining delivery on supported serverless platforms.
+   * @param {(error?: Error) => void} [done]
+   * @param {{ deadline?: number }} [options]
+   * @returns {void}
+   */
+  flush (done, options) {
+    if (this.#deliveryTracker) {
+      return this.#deliveryTracker.track(callback => this.flushDirect(callback, options), done)
+    }
+    this.flushDirect(done, options)
+  }
+
+  /**
+   * Flushes queued telemetry without registering serverless delivery retention.
+   * @param {(error?: Error) => void} [done]
+   * @param {{ deadline?: number }} [options]
+   * @returns {void}
+   */
+  flushDirect (done = () => {}, options) {
     const count = this._encoder.count()
 
     if (!request.writable && options?.deadline === undefined) {

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

@@ -1,16 +1,35 @@
 'use strict'
 
+const log = require('../../log')
+const { createServerlessDeliveryTracker } = require('../../serverless')
 const { Writer } = require('./writer')
 
 class SpanStatsExporter {
+  #serverlessDeliveryTracker
+
   constructor (config) {
+    this.#serverlessDeliveryTracker = createServerlessDeliveryTracker()
     this._url = config.url
-    this._writer = new Writer({ url: this._url })
+    this._writer = new Writer({
+      url: this._url,
+      deliveryTracker: this.#serverlessDeliveryTracker,
+    })
+  }
+
+  export (payload, done) {
+    try {
+      this._writer.append(payload)
+      this._writer.flush(this.#serverlessDeliveryTracker ? undefined : done)
+    } catch (error) {
+      if (!done) throw error
+      log.error('Failed to flush span stats: %s', error.message)
+    }
+    this.#serverlessDeliveryTracker?.waitForIdle(done)
   }
 
-  export (payload) {
-    this._writer.append(payload)
-    this._writer.flush()
+  flush (done) {
+    this._writer.flush(this.#serverlessDeliveryTracker ? undefined : done)
+    this.#serverlessDeliveryTracker?.waitForIdle(done)
   }
 }
 

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

@@ -33,11 +33,12 @@ class ExternalLogger {
   }
 
   static tagString (tags) {
-    const tagArray = []
+    let tagString = ''
     for (const key in tags) {
-      tagArray.push(key + ':' + tags[key])
+      if (tagString) tagString += ','
+      tagString += key + ':' + tags[key]
     }
-    return tagArray.join(',')
+    return tagString
   }
 
   // Parses and enqueues a log

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

@@ -0,0 +1,102 @@
+'use strict'
+
+const log = require('./log')
+const { supportsServerlessTelemetryRetention } = require('./serverless')
+
+/**
+ * @typedef {(done: () => void) => void} TelemetryFlusher
+ */
+
+/** @type {Set<TelemetryFlusher>} */
+const telemetryFlushers = new Set()
+const postTraceTelemetryFlushers = new Set()
+
+/**
+ * @typedef {{
+ *   trace?: TelemetryFlusher,
+ *   spanStats?: TelemetryFlusher
+ * }} TraceFlushers
+ */
+
+/**
+ * Registers a configured telemetry pipeline so serverless lifecycle retention
+ * waits for its final export alongside trace delivery.
+ * @param {TelemetryFlusher} flusher
+ * @param {{ afterTrace?: boolean }} [options]
+ * @returns {() => void} Removes this pipeline when its provider is replaced.
+ */
+function registerTelemetryFlusher (flusher, options) {
+  if (!supportsServerlessTelemetryRetention()) return () => {}
+
+  const flushers = options?.afterTrace ? postTraceTelemetryFlushers : telemetryFlushers
+  flushers.add(flusher)
+  // Avoid retaining a replaced provider or flushing it alongside the new one.
+  return () => flushers.delete(flusher)
+}
+
+/**
+ * Coordinates the configured telemetry flushers for a serverless lifecycle.
+ *
+ * Trace-owned flushers are supplied by DatadogTracer so this module does not
+ * depend on its private implementation details.
+ * @param {() => void} [done]
+ * @param {{ timeout?: number }} [options]
+ * @param {TraceFlushers} [traceFlushers]
+ */
+function flushServerlessTelemetry (done, options, traceFlushers = {}) {
+  const { trace: traceFlusher, spanStats: spanStatsFlusher } = traceFlushers
+  // TODO: Include DSM after DataStreamsProcessor exposes a completion-aware flush API.
+  let pending = telemetryFlushers.size + postTraceTelemetryFlushers.size +
+    (typeof traceFlusher === 'function' ? 1 : 0) +
+    (typeof spanStatsFlusher === 'function' ? 1 : 0)
+  let completed = false
+  let timeout
+
+  const finish = () => {
+    if (completed) return
+    completed = true
+    clearTimeout(timeout)
+    done?.()
+  }
+  const complete = () => {
+    if (--pending === 0) finish()
+  }
+
+  if (pending === 0) return finish()
+  if (options?.timeout) {
+    timeout = setTimeout(() => {
+      log.warn('Timed out waiting for telemetry flush after %dms', options.timeout)
+      finish()
+    }, options.timeout)
+  }
+
+  const flush = (flusher, afterFlushed) => {
+    let flushed = false
+    const onFlushed = error => {
+      if (flushed) return
+      flushed = true
+      if (error) log.error('Error flushing telemetry pipeline:', error)
+      afterFlushed?.()
+      complete()
+    }
+    try {
+      flusher(onFlushed)
+    } catch (error) {
+      onFlushed(error)
+    }
+  }
+
+  if (typeof traceFlusher === 'function') {
+    flush(traceFlusher, () => {
+      for (const flusher of postTraceTelemetryFlushers) flush(flusher)
+    })
+  } else {
+    for (const flusher of postTraceTelemetryFlushers) flush(flusher)
+  }
+  if (typeof spanStatsFlusher === 'function') {
+    flush(spanStatsFlusher)
+  }
+  for (const flusher of telemetryFlushers) flush(flusher)
+}
+
+module.exports = { flushServerlessTelemetry, registerTelemetryFlusher }

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

@@ -108,6 +108,10 @@ class ExperimentsClient {
     return this.#site
   }
 
+  get projectName () {
+    return this.#projectName
+  }
+
   // Dashboard URL base for the configured site, e.g. https://app.datadoghq.com
   get appBase () {
     return `https://${appHost(this.#site)}`

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

@@ -1,8 +1,17 @@
 'use strict'
 
 const { randomUUID } = require('node:crypto')
+const snapshotPayload = require('../../../../../vendor/dist/rfdc')({ proto: false, circles: false })
 
 /** @typedef {{add?: string[], remove?: string[], replace?: string[]}} TagOperations */
+/**
+ * @typedef {object} DatasetRecordNew
+ * @property {string} [id]
+ * @property {unknown} inputData
+ * @property {unknown} [expectedOutput]
+ * @property {Record<string, unknown>} [metadata]
+ * @property {string[]} [tags]
+ */
 /**
  * @typedef {object} PendingBatch
  * @property {object} attributes
@@ -114,6 +123,9 @@ function updateFromInsertedRecord (recordId, record, payload) {
     update.expectedOutput = record.expectedOutput
   }
   if (!valuesAreEqual(record.metadata, payload.metadata)) update.metadata = record.metadata
+  if (!valuesAreEqual(record.tags, payload.tags ?? [])) {
+    update.tagOperations = { replace: [...record.tags] }
+  }
   return update
 }
 
@@ -173,6 +185,36 @@ class Dataset {
     return this
   }
 
+  /**
+   * Add multiple records to a dataset.
+   * @param {DatasetRecordNew[]} records
+   * @returns {Dataset} This dataset for chaining.
+   */
+  addRecords (records) {
+    const newRecords = []
+    const recordIds = new Set(this.#recordsById.keys())
+
+    // Construct and validate the entire batch before mutating the dataset.
+    for (const record of records) {
+      if (record.id !== undefined && (typeof record.id !== 'string' || record.id.length === 0)) {
+        throw new Error('record id must be a non-empty string')
+      }
+      const newRecord = new DatasetRecord(
+        record.inputData,
+        record.expectedOutput,
+        record.metadata,
+        record.id,
+        record.tags
+      )
+      if (recordIds.has(newRecord.id)) throw new Error(`Duplicate record id '${newRecord.id}'`)
+      recordIds.add(newRecord.id)
+      newRecords.push(newRecord)
+    }
+
+    for (const record of newRecords) this.#addRecord(record)
+    return this
+  }
+
   /**
    * Add tags to a dataset record.
    * @param {number} index Dataset record index.
@@ -336,6 +378,10 @@ class Dataset {
     return this.#projectId
   }
 
+  projectName () {
+    return this.#client.projectName
+  }
+
   version () {
     return this.#version
   }
@@ -416,7 +462,7 @@ class Dataset {
     const insertRecords = []
     const insertPayloads = new Map()
     for (const [recordId, record] of this.#newRecordsById) {
-      const payload = serializedRecord(record)
+      const payload = snapshotPayload(serializedRecord(record))
       insertRecords.push(payload)
       insertPayloads.set(recordId, payload)
     }
@@ -427,7 +473,7 @@ class Dataset {
       const tagOperations = this.#pendingTagOperations.get(recordId)
       if (tagOperations) update.tagOperations = tagOperations
       else delete update.tagOperations
-      const payload = serializedRecordUpdate(update)
+      const payload = snapshotPayload(serializedRecordUpdate(update))
       updateRecords.push(payload)
       updatePayloads.set(recordId, payload)
     }
@@ -522,6 +568,9 @@ class Dataset {
         updateFromInsertedRecord(recordId, current, payload)
       const queuedOperations = this.#pendingTagOperations.get(recordId)
       if (queuedOperations) update.tagOperations = queuedOperations
+      if (update.tagOperations) {
+        this.#pendingTagOperations.set(recordId, copyTagOperations(update.tagOperations))
+      }
       this.#updatedRecordsById.set(recordId, update)
     }