dd-trace 6.16.0 → 6.18.0

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

@@ -207,7 +207,6 @@ class DogStatsDClient {
   /**
    * @param {boolean|(() => void)} [forceTelemetry] - Whether to ignore the telemetry interval, or completion callback
    * @param {() => void} [done] - Called after serverless deliveries complete
-   * @returns {void}
    */
   flush (forceTelemetry = false, done) {
     if (typeof forceTelemetry === 'function') {
@@ -238,7 +237,6 @@ class DogStatsDClient {
   /**
    * @param {boolean} force - Whether to ignore the telemetry interval
    * @param {((send: (done?: () => void) => void) => void)} [track] - Tracks a non-serverless delivery
-   * @returns {void}
    */
   #flushTelemetry (force, track) {
     const telemetry = this.telemetry
@@ -291,7 +289,6 @@ class DogStatsDClient {
    * @param {DogStatsDBufferState} state - Payload state to flush
    * @param {boolean} recordTelemetry - Whether to record the transport outcome
    * @param {((send: (done?: () => void) => void) => void)} [track] - Tracks a non-serverless delivery
-   * @returns {void}
    */
   #flush (state, recordTelemetry, track) {
     const queue = this._enqueue(state)
@@ -314,7 +311,6 @@ class DogStatsDClient {
 
   /**
    * @param {number} bytes - Number of bytes sent
-   * @returns {void}
    */
   #recordSent (bytes) {
     const telemetry = this.telemetry
@@ -326,7 +322,6 @@ class DogStatsDClient {
   /**
    * @param {number} bytes - Number of bytes dropped
    * @param {number} [packets] - Number of packets dropped
-   * @returns {void}
    */
   #recordDropped (bytes, packets = 1) {
     const telemetry = this.telemetry
@@ -341,7 +336,6 @@ class DogStatsDClient {
    * @param {Buffer[]} queue - The metrics to send
    * @param {boolean} recordTelemetry - Whether to record the transport outcome
    * @param {() => void} [done] - Called after delivery completes
-   * @returns {void}
    * @memberof DogStatsDClient
    */
   _sendHttp (queue, recordTelemetry, done) {
@@ -375,7 +369,6 @@ class DogStatsDClient {
    * @param {Buffer[]} queue - The metrics to send
    * @param {boolean} recordTelemetry - Whether to record the transport outcome
    * @param {() => void} [done] - Called after delivery completes
-   * @returns {void}
    * @memberof DogStatsDClient
    */
   _sendUdp (queue, recordTelemetry, done) {
@@ -411,7 +404,6 @@ class DogStatsDClient {
    * @param {number} family - The family of the address
    * @param {boolean} recordTelemetry - Whether to record the transport outcome
    * @param {() => void} [done] - Called after every packet completes
-   * @returns {void}
    * @memberof DogStatsDClient
    */
   _sendUdpFromQueue (queue, address, family, recordTelemetry, done) {
@@ -457,7 +449,6 @@ class DogStatsDClient {
    * @param {string[]} tags - The metric tags
    * @param {string} [tagsPrefix] - Serialized global tags
    * @param {DogStatsDBufferState} [state] - Payload state receiving the metric
-   * @returns {void}
    * @memberof DogStatsDClient
    */
   _add (stat, value, type, tags, tagsPrefix = this.#tagsPrefix, state = this.#metrics) {
@@ -482,7 +473,6 @@ class DogStatsDClient {
    * @param {string} stat - Telemetry metric name
    * @param {number} value - Telemetry metric value
    * @param {string} [typeLabel] - Submitted or aggregated metric type
-   * @returns {void}
    */
   #addTelemetry (stat, value, typeLabel) {
     const tags = typeLabel === undefined ? undefined : [`metrics_type:${typeLabel}`]
@@ -496,7 +486,6 @@ class DogStatsDClient {
    *
    * @param {string} message - The message to write
    * @param {DogStatsDBufferState} [state] - Payload state receiving the message
-   * @returns {void}
    * @memberof DogStatsDClient
    */
   _write (message, state = this.#metrics) {
@@ -605,7 +594,6 @@ class MetricsAggregationClient {
   /**
    * @param {boolean|(() => void)} [forceTelemetry] - Whether to ignore the telemetry interval, or completion callback
    * @param {() => void} [done] - Called after serverless deliveries complete
-   * @returns {void}
    */
   flush (forceTelemetry = false, done) {
     if (typeof forceTelemetry === 'function') {
@@ -680,9 +668,6 @@ class MetricsAggregationClient {
     this.count(name, -count, tags)
   }
 
-  /**
-   * @returns {number} Number of gauge contexts flushed
-   */
   _captureGauges () {
     let metrics = 0
     const contexts = this._captureTree(this._gauges, (node, name, tags) => {
@@ -696,9 +681,6 @@ class MetricsAggregationClient {
     return contexts
   }
 
-  /**
-   * @returns {number} Number of counter contexts flushed
-   */
   _captureCounters () {
     let metrics = 0
     const contexts = this._captureTree(this._counters, (node, name, tags) => {
@@ -712,9 +694,6 @@ class MetricsAggregationClient {
     return contexts
   }
 
-  /**
-   * @returns {number} Number of histogram contexts flushed
-   */
   _captureHistograms () {
     let metrics = 0
     const contexts = this._captureTree(this._histograms, (node, name, tags) => {
@@ -740,7 +719,6 @@ class MetricsAggregationClient {
   /**
    * @param {Map<string, MetricNode>} tree - Metric context tree
    * @param {CaptureMetric} fn - Called for every context with submissions
-   * @returns {number} Number of contexts with submissions
    */
   _captureTree (tree, fn) {
     let contexts = 0
@@ -757,7 +735,6 @@ class MetricsAggregationClient {
    * @param {string} name - Metric name
    * @param {string[]} tags - Current metric tags
    * @param {CaptureMetric} fn - Called for every context with submissions
-   * @returns {number} Number of contexts with submissions
    */
   _captureNode (node, name, tags, fn) {
     let contexts = 0

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

@@ -74,13 +74,11 @@ class CrossPayloadAgentEncoder extends AgentEncoder {
     return super.makePayload()
   }
 
-  /** @returns {void} */
   reset () {
     this.#prepareReset()
     super.reset()
   }
 
-  /** @returns {void} */
   #prepareReset () {
     const crossPayloadState = this.#crossPayloadState
     if (crossPayloadState !== undefined && !prepareCrossPayloadReset(crossPayloadState)) {
@@ -129,7 +127,6 @@ function markPayloadString (crossPayloadState, value) {
 
 /**
  * @param {ReturnType<typeof createCrossPayloadState>} crossPayloadState
- * @returns {boolean}
  */
 function prepareCrossPayloadReset (crossPayloadState) {
   const learning = crossPayloadState.learningPayloadCount < CROSS_PAYLOAD_LEARNING_PAYLOAD_LIMIT

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

@@ -136,7 +136,6 @@ function formatSpanWithLegacyEvents (span) {
  * replacer hooks).
  *
  * @param {Array<{ name: unknown, startTime: number, attributes?: object }>} spanEvents
- * @returns {string}
  */
 function stringifySpanEvents (spanEvents) {
   let result = '['
@@ -200,7 +199,6 @@ function stringifyAttributeValue (value) {
  * conversion (which is what `JSON.stringify` calls internally).
  *
  * @param {number} value
- * @returns {string}
  */
 function jsonNumber (value) {
   if (Number.isFinite(value)) return String(value)
@@ -215,7 +213,6 @@ function jsonNumber (value) {
  * lone surrogates, etc.).
  *
  * @param {string} value
- * @returns {string}
  */
 function escapeJsonString (value) {
   for (let index = 0; index < value.length; index++) {
@@ -649,7 +646,6 @@ class AgentEncoder {
    * @param {number} offset
    * @param {Buffer} keyPrefix Precomputed `[key, 0xCF]`.
    * @param {{ toBuffer: () => Uint8Array | number[] }} identifier
-   * @returns {number}
    */
   #writeIdAt (target, offset, keyPrefix, identifier) {
     target.set(keyPrefix, offset)
@@ -871,7 +867,6 @@ class AgentEncoder {
    * @param {MsgpackChunk} bytes
    * @param {string} key
    * @param {unknown} value
-   * @returns {boolean}
    */
   #emitAttribute (bytes, key, value) {
     if (typeof value === 'string') {
@@ -911,7 +906,6 @@ class AgentEncoder {
    * @param {MsgpackChunk} bytes
    * @param {string} key
    * @param {Array<unknown>} array
-   * @returns {boolean}
    */
   #emitArrayAttribute (bytes, key, array) {
     const sectionStart = bytes.length
@@ -946,7 +940,6 @@ class AgentEncoder {
    * @param {MsgpackChunk} bytes
    * @param {string} key
    * @param {unknown} value
-   * @returns {boolean}
    */
   #emitArrayItem (bytes, key, value) {
     if (typeof value === 'string') {

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

@@ -173,7 +173,6 @@ class AgentEncoder extends BaseEncoder {
    * @param {Uint8Array} target
    * @param {number} offset
    * @param {number} index
-   * @returns {number}
    */
   #writeIndexAt (target, offset, index) {
     target[offset] = 0xCE
@@ -192,7 +191,6 @@ class AgentEncoder extends BaseEncoder {
    * @param {Uint8Array} target
    * @param {number} offset
    * @param {{ toBuffer: () => Uint8Array | number[] }} identifier
-   * @returns {number}
    */
   #writeIdAt (target, offset, identifier) {
     target[offset] = 0xCF

package/packages/dd-trace/src/encode/tags-processors.js

@@ -53,7 +53,6 @@ function truncateSpanTestOpt (span) {
  * the formatter no longer reshapes events, it hands the raw array through.
  *
  * @param {{ startTime: number }} event
- * @returns {number}
  */
 function eventTimeNano (event) {
   return Math.round(event.startTime * 1e6)

package/packages/dd-trace/src/evp_proxy/constants.js

@@ -1,6 +1,8 @@
 'use strict'
 
 module.exports = {
+  EVP_ORIGIN_HEADER_NAME: 'DD-EVP-ORIGIN',
+  EVP_ORIGIN_VERSION_HEADER_NAME: 'DD-EVP-ORIGIN-VERSION',
   EVP_PROXY_PATH_V2: '/evp_proxy/v2',
   EVP_PROXY_PATH_V4: '/evp_proxy/v4',
   EVP_SUBDOMAIN_HEADER_NAME: 'X-Datadog-EVP-Subdomain',

package/packages/dd-trace/src/evp_proxy/direct.js

@@ -3,6 +3,8 @@
 const { createSiteUrl } = require('../exporters/common/url')
 const log = require('../log')
 
+let invalidSiteWarningLogged = false
+
 /**
  * @typedef {object} DirectEVPRoute
  * @property {URL} url - Direct intake URL
@@ -21,21 +23,23 @@ const log = require('../log')
  */
 function createDirectEVPRoute (config, intake) {
   const apiKey = config.DD_API_KEY
-  if (!apiKey || !config.site) return
-
-  try {
-    const url = createSiteUrl(config.site, intake)
-    if (url === undefined) throw new Error('Invalid direct EVP intake URL')
+  if (!apiKey) return
 
-    return {
-      url,
-      basePath: '',
-      headers: {
-        'DD-API-KEY': apiKey,
-      },
+  const url = createSiteUrl(config.site, intake)
+  if (url === undefined) {
+    if (!invalidSiteWarningLogged) {
+      invalidSiteWarningLogged = true
+      log.warn('Feature Flags direct event delivery is disabled because DD_SITE is invalid.')
     }
-  } catch (error) {
-    log.debug('Unable to configure direct EVP intake: %s', error.message)
+    return
+  }
+
+  return {
+    url,
+    basePath: '',
+    headers: {
+      'DD-API-KEY': apiKey,
+    },
   }
 }
 

package/packages/dd-trace/src/evp_proxy/discovery.js

@@ -2,7 +2,7 @@
 
 const { fetchAgentInfo } = require('../agent/info')
 const log = require('../log')
-const { stripTrailingSlashes } = require('./path')
+const { joinAgentURLPath, stripTrailingSlashes } = require('./path')
 
 /**
  * Receiver discovery contract
@@ -25,13 +25,13 @@ const { stripTrailingSlashes } = require('./path')
  * serverless-init image or deployment type.
  *
  * This module only discovers a candidate route. A missing or unresponsive
- * `/info` endpoint returns an error through the shared request timeout and
- * retry policy. A valid response without a compatible path returns no route.
+ * `/info` endpoint returns an error after the request's bounded retry policy.
+ * Callers can disable retries to make discovery a single attempt. A valid
+ * response without a compatible path returns no route.
  * Discovery sends no events, so the caller can safely select direct intake
  * after either result. The caller also owns later delivery failures. Exposure
- * delivery uses retries and can therefore produce duplicates. After local
- * retries fail, the caller can retry through direct intake and use that route
- * for future batches.
+ * delivery decides whether a failed batch can be replayed and which route
+ * future batches use.
  *
  * Reference implementations:
  *
@@ -62,17 +62,17 @@ function selectEVPProxyPath (agentInfo, { supportedPaths, requiredHeaders = [] }
   }
 
   const allowedHeaders = agentInfo.evp_proxy_allowed_headers
-  if (allowedHeaders !== undefined) {
+  if (requiredHeaders.length > 0 || allowedHeaders !== undefined) {
     if (!Array.isArray(allowedHeaders)) return
 
     const normalizedHeaders = new Set()
     for (const header of allowedHeaders) {
       if (typeof header === 'string') {
-        normalizedHeaders.add(header.toLowerCase())
+        normalizedHeaders.add(header.trim().toLowerCase())
       }
     }
 
-    if (requiredHeaders.some(header => !normalizedHeaders.has(header.toLowerCase()))) {
+    if (requiredHeaders.some(header => !normalizedHeaders.has(header.trim().toLowerCase()))) {
       return
     }
   }
@@ -105,8 +105,8 @@ function selectEVPProxyPath (agentInfo, { supportedPaths, requiredHeaders = [] }
  * @param {string[]} options.supportedPaths - Supported paths in preference order
  * @param {string[]} [options.requiredHeaders] - Headers that the proxy must forward unchanged to intake. Each
  * header must appear in `evp_proxy_allowed_headers`. Do not include routing headers that the Agent consumes.
+ * @param {boolean} [options.retry] - Set false to disable the request's default bounded retries
  * @param {(error: Error|null, route?: {url: URL, basePath: string}) => void} callback - Result callback
- * @returns {void}
  */
 function discoverEVPProxy (url, options, callback) {
   fetchAgentInfo(url, (error, agentInfo) => {
@@ -122,7 +122,10 @@ function discoverEVPProxy (url, options, callback) {
     }
 
     log.debug('EVP proxy route %s discovered through the configured local receiver', basePath)
-    callback(null, { url, basePath })
+    callback(null, { url, basePath: joinAgentURLPath(url, basePath) })
+  }, {
+    path: joinAgentURLPath(url, '/info'),
+    retry: options.retry,
   })
 }
 

package/packages/dd-trace/src/evp_proxy/path.js

@@ -4,7 +4,6 @@ const LEADING_SLASHES = /^\/+/
 
 /**
  * @param {string} value
- * @returns {string}
  */
 function stripTrailingSlashes (value) {
   let end = value.length
@@ -17,15 +16,28 @@ function stripTrailingSlashes (value) {
  *
  * This utility does not perform EVP proxy discovery.
  *
- * @param {string} basePath - EVP proxy base path
- * @param {string} endpoint - Product intake endpoint
- * @returns {string} Joined request path
+ * @param {...string} paths - URL path components
  */
-function joinEVPProxyPath (basePath, endpoint) {
-  const normalizedBasePath = stripTrailingSlashes(basePath)
-  const normalizedEndpoint = endpoint.replace(LEADING_SLASHES, '')
+function joinEVPProxyPath (...paths) {
+  let joined = ''
+  for (const path of paths) {
+    const normalized = stripTrailingSlashes(path).replace(LEADING_SLASHES, '')
+    if (normalized) joined += `/${normalized}`
+  }
 
-  return `${normalizedBasePath}/${normalizedEndpoint}`
+  return joined || '/'
 }
 
-module.exports = { joinEVPProxyPath, stripTrailingSlashes }
+/**
+ * Joins an HTTP Agent URL path prefix with an EVP proxy path.
+ * Unix URL pathnames identify the socket itself and are not HTTP path prefixes.
+ *
+ * @param {URL} url - Configured Agent URL
+ * @param {...string} paths - EVP path components
+ */
+function joinAgentURLPath (url, ...paths) {
+  const prefix = url.protocol === 'http:' || url.protocol === 'https:' ? url.pathname : ''
+  return joinEVPProxyPath(prefix, ...paths)
+}
+
+module.exports = { joinAgentURLPath, joinEVPProxyPath, stripTrailingSlashes }

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

@@ -44,7 +44,6 @@ class AgentWriter extends BaseWriter {
    * Test Optimization owns its own request lifecycle tracking.
    * @param {(error?: Error) => void} [done]
    * @param {{ deadline?: number }} [options]
-   * @returns {void}
    */
   flushDirect (done, options) {
     if (this.#requestTracker) {

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

@@ -63,7 +63,6 @@ class AgentlessExporter {
   /**
    * Sets the intake URL.
    * @param {string} urlString - The new intake URL
-   * @returns {boolean} True if URL was set successfully
    */
   setUrl (urlString) {
     try {

package/packages/dd-trace/src/exporters/agentless/intake.js

@@ -25,7 +25,6 @@ const INTAKE_PATH = '/api/v2/spans'
  * reattach the TLD, e.g. 'us2.ddog-gov.com' -> 'https://browser-intake-us2-ddog-gov.com'.
  *
  * @param {string} [site] - The Datadog site, e.g. 'us3.datadoghq.com'. Defaults to 'datadoghq.com'.
- * @returns {string} The intake origin, without a path.
  */
 function computeIntakeUrl (site = 'datadoghq.com') {
   const normalized = site.toLowerCase()

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

@@ -117,9 +117,6 @@ class AgentlessWriter extends BaseWriter {
     }
   }
 
-  /**
-   * @returns {string} The full agentless intake endpoint.
-   */
   #endpoint () {
     const endpoint = new URL(this._url)
     endpoint.pathname = INTAKE_PATH

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

@@ -45,7 +45,6 @@ class FinalFlushRequestTracker {
    *
    * @param {(error?: Error) => void} [done]
    * @param {{ deadline?: number }} [options]
-   * @returns {void}
    */
   flush (done, options) {
     if (options?.deadline === undefined) {
@@ -112,7 +111,6 @@ class FinalFlushRequestTracker {
    * @param {RequestOptions} options
    * @param {(error: Error|null, result?: string|null, statusCode?: number,
    *   headers?: import('node:http').IncomingHttpHeaders) => void} callback
-   * @returns {void}
    */
   send (request, data, options, callback) {
     const controller = new AbortController()
@@ -141,7 +139,6 @@ class FinalFlushRequestTracker {
 
   /**
    * @param {PendingRequest} pendingRequest
-   * @returns {void}
    */
   #dropRequest (pendingRequest) {
     this.#pendingRequests.delete(pendingRequest)
@@ -155,7 +152,6 @@ class FinalFlushRequestTracker {
   /**
    * @param {FinalFlush} finalFlush
    * @param {PendingRequest} pendingRequest
-   * @returns {void}
    */
   #attachRequest (finalFlush, pendingRequest) {
     finalFlush.requests.add(pendingRequest)
@@ -165,7 +161,6 @@ class FinalFlushRequestTracker {
 
   /**
    * @param {PendingRequest} pendingRequest
-   * @returns {void}
    */
   #updateRequestDeadline (pendingRequest) {
     let deadline = 0
@@ -177,7 +172,6 @@ class FinalFlushRequestTracker {
 
   /**
    * @param {FinalFlush} finalFlush
-   * @returns {void}
    */
   #finishFinalFlush (finalFlush) {
     if (!this.#finalFlushes.has(finalFlush) || !finalFlush.writerDone || finalFlush.requests.size !== 0) return

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

@@ -170,6 +170,7 @@ function request (data, options, callback) {
         }
         const error = new log.NoTransmitError(errorMessage)
         error.status = res.statusCode
+        if (options.includeErrorResponseBody) error.responseBody = responseData
 
         complete(error, null, res.statusCode, res.headers)
       }

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

@@ -5,9 +5,11 @@ const { format } = require('node:url')
 
 const { urlToHttpOptions } = require('./url-to-http-options-polyfill')
 
+const DEFAULT_SITE = 'datadoghq.com'
+const DNS_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/
+
 /**
  * @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.
@@ -20,7 +22,6 @@ function isLoopbackHost (hostname) {
 /**
  * @param {string|undefined} protocol
  * @param {string|undefined} hostname
- * @returns {boolean}
  */
 function canSendApiKey (protocol, hostname) {
   return protocol === 'https:' || protocol === 'unix:' ||
@@ -33,7 +34,11 @@ function canSendApiKey (protocol, hostname) {
  * @returns {URL | undefined}
  */
 function createSiteUrl (site, intake) {
-  const hostname = `${intake === undefined ? '' : `${intake}.`}${site}`.toLowerCase()
+  const normalizedSite = normalizeSite(site)
+  if (normalizedSite === undefined) return
+
+  const hostname = `${intake === undefined ? '' : `${intake}.`}${normalizedSite}`
+  if (hostname.length > 253) return
 
   try {
     const url = new URL(format({
@@ -55,6 +60,30 @@ function createSiteUrl (site, intake) {
   } catch {}
 }
 
+/**
+ * Normalizes a Datadog site as a DNS suffix.
+ *
+ * @param {string | undefined} site
+ * @returns {string | undefined}
+ */
+function normalizeSite (site) {
+  if (site === undefined) return DEFAULT_SITE
+  if (typeof site !== 'string') return
+  for (let index = 0; index < site.length; index++) {
+    if (site.charCodeAt(index) > 127) return
+  }
+
+  const normalized = site.trim().toLowerCase() || DEFAULT_SITE
+  if (normalized.length > 253) return
+
+  const labels = normalized.split('.')
+  for (const label of labels) {
+    if (!DNS_LABEL.test(label)) return
+  }
+
+  return normalized
+}
+
 /**
  * Convert an agent/intake URL into Node http(s) request options.
  *
@@ -82,4 +111,4 @@ function parseUrl (urlObjOrString) {
   return url
 }
 
-module.exports = { canSendApiKey, createSiteUrl, isLoopbackHost, parseUrl }
+module.exports = { canSendApiKey, createSiteUrl, isLoopbackHost, normalizeSite, parseUrl }

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

@@ -27,7 +27,6 @@ class Writer {
    * 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) {
@@ -40,7 +39,6 @@ class Writer {
    * Flushes queued telemetry without registering serverless delivery retention.
    * @param {(error?: Error) => void} [done]
    * @param {{ deadline?: number }} [options]
-   * @returns {void}
    */
   flushDirect (done = noop, options) {
     const count = this._encoder.count()

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

@@ -36,7 +36,6 @@ class Identifier {
 
   /**
    * @param {number} [radix]
-   * @returns {string}
    */
   toString (radix = 16) {
     if (radix === 16) {
@@ -50,9 +49,6 @@ class Identifier {
     return toNumberString(this.#buffer, radix)
   }
 
-  /**
-   * @returns {bigint}
-   */
   toBigInt () {
     this.#bigInt ??= Buffer.from(this.#buffer).readBigUInt64BE(0)
     return this.#bigInt
@@ -75,9 +71,6 @@ class Identifier {
     return this.#buffer.slice(-8)
   }
 
-  /**
-   * @returns {string}
-   */
   toJSON () {
     return this.toString()
   }
@@ -88,7 +81,6 @@ class Identifier {
    * only this identifier's hex representation.
    *
    * @param {string | undefined} traceIdHigh - 16-char hex of the upper 64 bits, or undefined
-   * @returns {string}
    */
   toTraceIdHex (traceIdHigh) {
     if (traceIdHigh && this.#buffer.length <= 8) {
@@ -99,7 +91,6 @@ class Identifier {
 
   /**
    * @param {Identifier} other
-   * @returns {boolean}
    */
   equals (other) {
     // Big-endian suffix compare: when buffers differ in length, only the
@@ -182,7 +173,6 @@ function fromString (str, raddix) {
 /**
  * @param {number[] | Uint8Array} buffer
  * @param {number} [radix]
- * @returns {string}
  */
 function toNumberString (buffer, radix) {
   let high = readInt32(buffer, buffer.length - 8)
@@ -233,7 +223,6 @@ function pseudoRandom () {
 /**
  * @param {number[] | Uint8Array} buffer
  * @param {number} offset
- * @returns {number}
  */
 function readInt32 (buffer, offset) {
   return (buffer[offset + 0] * 16_777_216) +