dd-trace 6.18.0 → 6.20.0

package/packages/dd-trace/src/otel-sampling.js

@@ -0,0 +1,171 @@
+'use strict'
+
+const { AUTO_KEEP } = require('../../../ext/priority')
+const knuthHash = require('./knuth-hash')
+const { SAMPLING_AGENT_DECISION, SAMPLING_RULE_DECISION } = require('./constants')
+
+const MAX_THRESHOLD = 2n ** 56n
+const MAX_ENCODABLE_THRESHOLD = MAX_THRESHOLD - 1n
+const UINT64_MASK = 2n ** 64n - 1n
+
+/**
+ * @param {unknown} value
+ * @param {number} minLength
+ * @param {number} maxLength
+ * @returns {value is string}
+ */
+function isLowerHex (value, minLength, maxLength) {
+  if (typeof value !== 'string' || value.length < minLength || value.length > maxLength) return false
+
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index)
+    if ((code < 48 || code > 57) && (code < 97 || code > 102)) return false
+  }
+
+  return true
+}
+
+/**
+ * Derives the OTel 56-bit random value from Datadog's sampling hash.
+ *
+ * @param {bigint} traceId
+ */
+function randomValueFor (traceId) {
+  return ((~knuthHash(traceId)) & UINT64_MASK) >> 8n
+}
+
+/**
+ * Converts a sample rate to an OTel 56-bit rejection threshold.
+ *
+ * @param {number} sampleRate
+ */
+function thresholdFor (sampleRate) {
+  if (sampleRate === 1) return 0n
+  if (sampleRate === 0) return MAX_ENCODABLE_THRESHOLD
+
+  const threshold = BigInt(Math.round((1 - sampleRate) * Number(MAX_THRESHOLD)))
+  if (threshold < 0n) return 0n
+  if (threshold > MAX_ENCODABLE_THRESHOLD) return MAX_ENCODABLE_THRESHOLD
+  return threshold
+}
+
+/**
+ * Formats an OTel threshold with trailing zero nibbles removed.
+ *
+ * @param {bigint} threshold
+ */
+function formatThreshold (threshold) {
+  const value = threshold.toString(16).padStart(14, '0')
+  let end = value.length
+  while (end > 0 && value.charCodeAt(end - 1) === 48) end--
+  return end === 0 ? '0' : value.slice(0, end)
+}
+
+/**
+ * Generates OTel sampling fields for a local probability decision.
+ *
+ * @param {import('./opentracing/span_context')} context
+ * @param {number} probabilityRate
+ * @returns {{ randomValue: string, threshold: string } | undefined}
+ */
+function generateFields (context, probabilityRate) {
+  const { priority } = context._sampling
+  if (priority === undefined || probabilityRate === undefined) return
+
+  const thresholdValue = thresholdFor(probabilityRate)
+  let randomValue = randomValueFor(context._traceId.toBigInt())
+  const kept = priority >= AUTO_KEEP
+
+  if (kept) {
+    if (randomValue < thresholdValue) {
+      randomValue = thresholdValue
+    }
+  } else if (randomValue >= thresholdValue) {
+    randomValue = thresholdValue > 0n ? thresholdValue - 1n : 0n
+  }
+
+  return {
+    randomValue: randomValue.toString(16).padStart(14, '0'),
+    threshold: formatThreshold(thresholdValue),
+  }
+}
+
+/**
+ * Returns the probability rate recorded by a committed Datadog sampling decision.
+ * Sampling probes deliberately leave these rate fields unset.
+ *
+ * @param {import('./opentracing/span_context')} context
+ * @returns {number | undefined}
+ */
+function getProbabilityRate (context) {
+  if (context._sampling.isProbabilityDecision === false) return
+  return (context._trace[SAMPLING_RULE_DECISION] ?? context._trace[SAMPLING_AGENT_DECISION]) || undefined
+}
+
+/**
+ * Removes malformed OTel sampling fields and returns the valid values.
+ *
+ * @param {import('./opentracing/propagation/tracestate')} state
+ * @returns {{ randomValue: string | undefined, threshold: string | undefined }}
+ */
+function sanitizeFields (state) {
+  let randomValue = state.get('rv')
+  let threshold = state.get('th')
+
+  if (!isLowerHex(randomValue, 14, 14)) {
+    state.delete('rv')
+    randomValue = undefined
+  }
+  if (!isLowerHex(threshold, 1, 14)) {
+    state.delete('th')
+    threshold = undefined
+  }
+
+  return { randomValue, threshold }
+}
+
+/**
+ * Sanitizes inherited OTel sampling fields without changing valid state.
+ *
+ * @param {import('./opentracing/propagation/tracestate')} traceState
+ */
+function normalizeOtelTraceState (traceState) {
+  if (traceState.get('ot') === undefined) return
+  traceState.forVendor('ot', sanitizeFields)
+}
+
+/**
+ * Updates the OTel tracestate member to represent the context's sampling decision.
+ *
+ * @param {import('./opentracing/span_context')} context
+ * @param {import('./opentracing/propagation/tracestate')} traceState
+ */
+function updateOtelTraceState (context, traceState) {
+  const otelMember = traceState.get('ot')
+  const probabilityRate = getProbabilityRate(context)
+  if (context._sampling.isProbabilityDecision === false) {
+    if (otelMember === undefined) return
+  } else if (probabilityRate === undefined) {
+    return
+  }
+
+  traceState.forVendor('ot', state => {
+    const { randomValue, threshold } = sanitizeFields(state)
+
+    if (context._sampling.isProbabilityDecision === false) {
+      state.delete('th')
+    } else if (randomValue === undefined && threshold === undefined) {
+      const generated = generateFields(context, probabilityRate)
+      if (generated) {
+        // Entries serialize in reverse insertion order, so add th before rv.
+        state.set('th', generated.threshold)
+        state.set('rv', generated.randomValue)
+      }
+    }
+  })
+}
+
+module.exports = {
+  normalizeOtelTraceState,
+  updateOtelTraceState,
+}

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

@@ -15,7 +15,6 @@ const plugins = {
   get '@supabase/postgrest-js' () { return require('../../../datadog-plugin-supabase/src') },
   get '@supabase/realtime-js' () { return require('../../../datadog-plugin-supabase/src') },
   get '@supabase/storage-js' () { return require('../../../datadog-plugin-supabase/src') },
-  get '@supabase/supabase-js' () { return require('../../../datadog-plugin-supabase/src') },
   get 'durable-functions' () { return require('../../../datadog-plugin-azure-durable-functions/src') },
   get '@azure/service-bus' () { return require('../../../datadog-plugin-azure-service-bus/src') },
   get '@cucumber/cucumber' () { return require('../../../datadog-plugin-cucumber/src') },

package/packages/dd-trace/src/plugins/util/test.js

@@ -2025,6 +2025,10 @@ function getModifiedFilesFromDiff (diff) {
     if (lineMatch && currentFile) {
       const start = Number(lineMatch.groups.start)
       const count = lineMatch.groups.count ? Number(lineMatch.groups.count) : 1
+      if (count === 0) {
+        // Keep the surviving line before a deletion so line-based consumers can match its scope.
+        result[currentFile].push(start)
+      }
       for (let j = 0; j < count; j++) {
         result[currentFile].push(start + j)
       }

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

@@ -26,8 +26,10 @@ const {
   SAMPLING_MECHANISM_AGENT,
   SAMPLING_MECHANISM_RULE,
   SAMPLING_MECHANISM_MANUAL,
+  SAMPLING_MECHANISM_APPSEC,
   SAMPLING_MECHANISM_REMOTE_USER,
   SAMPLING_MECHANISM_REMOTE_DYNAMIC,
+  SAMPLING_MECHANISM_AI_GUARD,
   SAMPLING_RULE_DECISION,
   SAMPLING_LIMIT_DECISION,
   SAMPLING_AGENT_DECISION,
@@ -39,6 +41,17 @@ const DEFAULT_KEY = 'service:,env:'
 
 const defaultSampler = new Sampler(AUTO_KEEP)
 
+/**
+ * Returns whether a product has already force-kept the trace.
+ *
+ * @param {import('./opentracing/span_context')} context
+ */
+function isProductForceKeep (context) {
+  const { priority, mechanism } = context._sampling
+  return priority === USER_KEEP &&
+    (mechanism === SAMPLING_MECHANISM_APPSEC || mechanism === SAMPLING_MECHANISM_AI_GUARD)
+}
+
 /**
  * PrioritySampler is responsible for determining whether a span should be sampled
  * based on various rules, rate limits, and priorities. It supports manual and
@@ -114,10 +127,10 @@ class PrioritySampler {
     const tag = this._getPriorityFromTags(context.getTags(), context)
 
     if (this.validate(tag)) {
-      context._sampling.priority = tag
       context._sampling.mechanism = SAMPLING_MECHANISM_MANUAL
+      this._recordDecision(context, tag)
     } else if (auto) {
-      context._sampling.priority = this._getPriorityFromAuto(root)
+      this.decideFromAuto(root)
     } else {
       return
     }
@@ -125,6 +138,22 @@ class PrioritySampler {
     this.#addDecisionMaker(root)
   }
 
+  /**
+   * Applies manual sampling tags from a supplied tag collection using their defined precedence.
+   *
+   * @param {DatadogSpan} span
+   * @param {Record<string, unknown>} tags
+   */
+  setPriorityFromTags (span, tags) {
+    if (!span) return
+
+    const context = this._getContext(span)
+    if (isProductForceKeep(context)) return
+
+    const priority = this._getPriorityFromTags(tags, context)
+    if (this.validate(priority)) this.setPriority(span, priority)
+  }
+
   /**
    * Updates agent-provided sampling rates keyed by `service:,env:`.
    *
@@ -179,14 +208,13 @@ class PrioritySampler {
       return // noop span
     }
 
-    context._sampling.priority = samplingPriority
-
     const mechanism = product?.mechanism ?? SAMPLING_MECHANISM_MANUAL
     context._sampling.mechanism = mechanism
+    this._recordDecision(context, samplingPriority)
 
     log.trace(span, samplingPriority, mechanism)
 
-    this.#addDecisionMaker(root)
+    this.#addDecisionMaker(root, product === undefined)
   }
 
   /**
@@ -201,6 +229,23 @@ class PrioritySampler {
       : /** @type {DatadogSpanContext} */ (span)
   }
 
+  /**
+   * Evaluates and records an automatic sampling decision.
+   *
+   * @param {DatadogSpan} span
+   * @returns {SamplingPriority}
+   */
+  decideFromAuto (span) {
+    const context = this._getContext(span)
+    const rule = this.#findRule(span)
+    const priority = rule
+      ? this.#getPriorityByRule(context, rule, true)
+      : this.#getPriorityByAgent(context, true)
+
+    context._sampling.priority = priority
+    return priority
+  }
+
   /**
    * Computes priority using rules and agent rates when no manual tag is present.
    *
@@ -212,27 +257,25 @@ class PrioritySampler {
     const rule = this.#findRule(span)
 
     return rule
-      ? this.#getPriorityByRule(context, rule)
-      : this.#getPriorityByAgent(context)
+      ? this.#getPriorityByRule(context, rule, false)
+      : this.#getPriorityByAgent(context, false)
   }
 
   /**
-   * Computes priority from manual sampling tags if present.
-   * Included for compatibility with {@link import('./standalone/tracesource_priority_sampler')._getPriorityFromTags}
+   * Converts one sampling tag into a user priority.
    *
-   * @param {Record<string, unknown>} tags
+   * @param {string} key
+   * @param {unknown} value
    * @param {DatadogSpanContext} _context
    * @returns {SamplingPriority|undefined}
    */
-  _getPriorityFromTags (tags, _context) {
-    if (Object.hasOwn(tags, MANUAL_KEEP) && tags[MANUAL_KEEP] !== false) {
+  _getPriorityFromTag (key, value, _context) {
+    if (key === MANUAL_KEEP && value !== false) {
       return USER_KEEP
-    } else if (Object.hasOwn(tags, MANUAL_DROP) && tags[MANUAL_DROP] !== false) {
+    } else if (key === MANUAL_DROP && value !== false) {
       return USER_REJECT
-    }
-    const rawPriority = tags[SAMPLING_PRIORITY]
-    if (rawPriority !== undefined) {
-      const priority = Math.trunc(rawPriority)
+    } else if (key === SAMPLING_PRIORITY && (typeof value === 'number' || typeof value === 'string')) {
+      const priority = Math.trunc(/** @type {number} */ (value))
 
       if (priority === 1 || priority === 2) {
         return USER_KEEP
@@ -242,30 +285,85 @@ class PrioritySampler {
     }
   }
 
+  /**
+   * Computes priority from manual sampling tags if present.
+   * Calls the overridable single-tag conversion so specialized samplers retain their filtering rules.
+   *
+   * @param {Record<string, unknown>} tags
+   * @param {DatadogSpanContext} _context
+   * @returns {SamplingPriority|undefined}
+   */
+  _getPriorityFromTags (tags, _context) {
+    if (!Object.hasOwn(tags, MANUAL_KEEP) && !Object.hasOwn(tags, MANUAL_DROP)) {
+      const priority = tags[SAMPLING_PRIORITY]
+      if (priority !== undefined) return this._getPriorityFromTag(SAMPLING_PRIORITY, priority, _context)
+      return
+    }
+
+    return this.#getPriorityFromManualTags(tags, _context)
+  }
+
+  /**
+   * Computes priority when at least one manual keep/drop tag is present.
+   * Value checks cover the common case; own-property checks preserve undefined-valued manual tags.
+   *
+   * @param {Record<string, unknown>} tags
+   * @param {DatadogSpanContext} context
+   * @returns {SamplingPriority|undefined}
+   */
+  #getPriorityFromManualTags (tags, context) {
+    const manualKeep = tags[MANUAL_KEEP]
+    if (manualKeep !== undefined || Object.hasOwn(tags, MANUAL_KEEP)) {
+      const priority = this._getPriorityFromTag(MANUAL_KEEP, manualKeep, context)
+      if (priority !== undefined) return priority
+    }
+
+    const manualDrop = tags[MANUAL_DROP]
+    if (manualDrop !== undefined || Object.hasOwn(tags, MANUAL_DROP)) {
+      const priority = this._getPriorityFromTag(MANUAL_DROP, manualDrop, context)
+      if (priority !== undefined) return priority
+    }
+    const priority = tags[SAMPLING_PRIORITY]
+    if (priority !== undefined) return this._getPriorityFromTag(SAMPLING_PRIORITY, priority, context)
+  }
+
   /**
    * Applies a matching rule and rate limit to compute the sampling priority.
    *
    * @param {DatadogSpanContext} context
    * @param {import('./sampling_rule')} rule
+   * @param {boolean} recordDecision
    * @returns {SamplingPriority}
    */
-  #getPriorityByRule (context, rule) {
-    context._trace[SAMPLING_RULE_DECISION] = rule.sampleRate
+  #getPriorityByRule (context, rule, recordDecision) {
+    if (recordDecision) context._trace[SAMPLING_RULE_DECISION] = rule.sampleRate
     context._trace.tags[SAMPLING_KNUTH_RATE] = formatKnuthRate(rule.sampleRate)
-    context._sampling.mechanism = SAMPLING_MECHANISM_RULE
-    if (rule.provenance === 'customer') {
-      context._sampling.mechanism = SAMPLING_MECHANISM_REMOTE_USER
-    } else if (rule.provenance === 'dynamic') {
-      context._sampling.mechanism = SAMPLING_MECHANISM_REMOTE_DYNAMIC
+    if (recordDecision) {
+      context._sampling.mechanism = SAMPLING_MECHANISM_RULE
+      if (rule.provenance === 'customer') {
+        context._sampling.mechanism = SAMPLING_MECHANISM_REMOTE_USER
+      } else if (rule.provenance === 'dynamic') {
+        context._sampling.mechanism = SAMPLING_MECHANISM_REMOTE_DYNAMIC
+      }
     }
 
     if (rule.discard) {
       context._sampling.discard = true
     }
 
-    return rule.sample(context) && this._isSampledByRateLimit(context)
-      ? USER_KEEP
-      : USER_REJECT
+    const sampled = rule.sample(context, true)
+    if (sampled !== true) {
+      if (recordDecision && sampled === undefined) this._recordDecisionMetadata(context)
+      return USER_REJECT
+    }
+
+    if (!this._isSampledByRateLimit(context)) {
+      // The limiter makes only rejected traces non-probabilistic; allowed traces retain the rule probability.
+      if (recordDecision) this._recordDecisionMetadata(context)
+      return USER_REJECT
+    }
+
+    return USER_KEEP
   }
 
   /**
@@ -287,39 +385,63 @@ class PrioritySampler {
    * Computes priority using agent-provided sampling rates.
    *
    * @param {DatadogSpanContext} context
+   * @param {boolean} recordDecision
    * @returns {SamplingPriority}
    */
-  #getPriorityByAgent (context) {
+  #getPriorityByAgent (context, recordDecision) {
     const key = `service:${context.getTag(SERVICE_NAME)},env:${this._env}`
     // TODO: Change underscored properties to private ones.
     const sampler = this._samplers[key] || this._samplers[DEFAULT_KEY]
 
     const rate = sampler.rate()
-    context._trace[SAMPLING_AGENT_DECISION] = rate
+    if (recordDecision) context._trace[SAMPLING_AGENT_DECISION] = rate
 
     if (sampler === defaultSampler) {
-      context._sampling.mechanism = SAMPLING_MECHANISM_DEFAULT
+      if (recordDecision) context._sampling.mechanism = SAMPLING_MECHANISM_DEFAULT
     } else {
       context._trace.tags[SAMPLING_KNUTH_RATE] = formatKnuthRate(rate)
-      context._sampling.mechanism = SAMPLING_MECHANISM_AGENT
+      if (recordDecision) context._sampling.mechanism = SAMPLING_MECHANISM_AGENT
     }
 
     return sampler.isSampled(context) ? AUTO_KEEP : AUTO_REJECT
   }
 
+  /**
+   * Records that a sampling decision does not represent a probability.
+   *
+   * @param {DatadogSpanContext} context
+   */
+  _recordDecisionMetadata (context) {
+    context._sampling.isProbabilityDecision = false
+  }
+
+  /**
+   * Records a local non-probability sampling decision.
+   *
+   * @param {DatadogSpanContext} context
+   * @param {SamplingPriority} priority
+   * @returns {SamplingPriority}
+   */
+  _recordDecision (context, priority) {
+    context._sampling.priority = priority
+    this._recordDecisionMetadata(context)
+    return priority
+  }
+
   /**
    * Tags the trace with a decision maker when priority is keep, or removes it otherwise.
    *
    * @param {DatadogSpan} span
+   * @param {boolean} [overwrite]
    */
-  #addDecisionMaker (span) {
+  #addDecisionMaker (span, overwrite = false) {
     const context = span.context()
     const trace = context._trace
     const priority = context._sampling.priority
     const mechanism = context._sampling.mechanism
 
     if (priority >= AUTO_KEEP) {
-      if (!trace.tags[DECISION_MAKER_KEY]) {
+      if (overwrite || !trace.tags[DECISION_MAKER_KEY]) {
         trace.tags[DECISION_MAKER_KEY] = `-${mechanism}`
       }
     } else if (trace.tags[DECISION_MAKER_KEY] !== undefined) {

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

@@ -12,8 +12,21 @@ let activeSSIHeuristics
 /** @type {import('./profiling') | undefined} */
 let profilingModule
 
+/**
+ * Configuration published while the profiler was finishing a shutdown export, waiting for that
+ * export to settle before it is acted on.
+ *
+ * @type {import('./config/config-base') | undefined}
+ */
+let deferredConfig
+
 function getProfilingModule () {
-  profilingModule ??= require('./profiling')
+  if (profilingModule === undefined) {
+    profilingModule = require('./profiling')
+    // The profiling layer never restarts itself; it only reports that a shutdown export has
+    // settled, which is when a configuration deferred during that window gets its decision.
+    profilingModule.profiler.on('stopped', applyDeferredConfig)
+  }
   return profilingModule
 }
 
@@ -25,6 +38,12 @@ function isStarted () {
   return profilingModule !== undefined && profilingModule.profiler.enabled
 }
 
+// A stopped profiler still exports one final profile, and until that settles it reports neither
+// the state a decision would be based on nor any willingness to start again.
+function isStopping () {
+  return profilingModule !== undefined && profilingModule.profiler.isStopping()
+}
+
 /** @type {typeof import('./profiling/ssi-heuristics') | undefined} */
 let ssiHeuristicsModule
 
@@ -57,8 +76,11 @@ function start (config) {
 }
 
 function stop () {
-  // A stop command for a profiler that has never been loaded is already satisfied. Once loaded,
-  // always forward it so the profiling layer can also cancel a restart queued during shutdown.
+  // An explicit stop is the latest desired state, so it retracts a configuration still waiting
+  // for an in-flight shutdown to settle.
+  deferredConfig = undefined
+
+  // A stop command for a profiler that has never been loaded is already satisfied.
   if (profilingModule === undefined) return
 
   try {
@@ -93,7 +115,17 @@ function runWithLabels (labels, fn) {
   return getProfilingModule().profiler.runWithLabels(labels, fn)
 }
 
-configUpdateChannel.subscribe((config) => {
+function applyDeferredConfig () {
+  const config = deferredConfig
+  if (config === undefined) return
+  deferredConfig = undefined
+  applyConfig(config)
+}
+
+/**
+ * @param {import('./config/config-base')} config - Tracer configuration
+ */
+function applyConfig (config) {
   const enabled = config.profiling.DD_PROFILING_ENABLED
   if (enabled === 'true') {
     // A non-auto value means the SSI heuristics no longer get a say; disable them so a trigger that
@@ -118,7 +150,9 @@ configUpdateChannel.subscribe((config) => {
       heuristics.start()
       heuristics.onTriggered(() => {
         // Explicit true/false publishes disable the heuristics, so reaching this callback guarantees
-        // the latest valid published value is still 'auto'.
+        // the latest valid published value is still 'auto'. A heuristic is only ever created for a
+        // profiler that is neither running nor stopping, and nothing can start that profiler behind
+        // an active heuristic's back, so this start can not collide with a shutdown in flight.
         if (!isStarted()) start(config)
         // The heuristic has made its decision, so release all of its listeners and timer before
         // dropping the module-level reference. This does not stop the profiler that was just
@@ -132,6 +166,18 @@ configUpdateChannel.subscribe((config) => {
     // like 'auto' or crash the customer application.
     log.warn('Unexpected DD_PROFILING_ENABLED value: %o', enabled)
   }
+}
+
+configUpdateChannel.subscribe((config) => {
+  // A shutdown export in flight makes every decision here unsafe: the profiler can not be
+  // started, and it does not yet report the state the auto branch would branch on. Defer instead,
+  // keeping only the latest configuration, exactly as a sequence of updates outside such a window
+  // would have left it.
+  if (isStopping()) {
+    deferredConfig = config
+    return
+  }
+  applyConfig(config)
 })
 
 globalThis[Symbol.for('dd-trace')].beforeExitHandlers.add(stop)

package/packages/dd-trace/src/profiling/profiler.js

@@ -61,7 +61,6 @@ class Profiler extends EventEmitter {
   #exporters
   #flushInterval
   #lastStart
-  #pendingStart
   #profileSeq = 0
   #profilers
   #spanFinishListener
@@ -87,6 +86,14 @@ class Profiler extends EventEmitter {
     return this.#enabled
   }
 
+  /**
+   * True while a stop()'s final collection is still encoding and exporting. The profiler no
+   * longer samples, but it also can not be started again until that settles and 'stopped' fires.
+   */
+  isStopping () {
+    return this.#stopping !== undefined
+  }
+
   /**
    * Declares the set of custom label keys that will be used with
    * {@link runWithLabels}. This is used for profile upload metadata and
@@ -184,12 +191,12 @@ class Profiler extends EventEmitter {
     if (this.#startFailed) return false
 
     // A prior stop()'s shutdown collection may still be encoding/exporting via #tags,
-    // #exporters and #endpointCounts. Wait for it to finish before this start() overwrites
-    // that shared state out from under it. Record the desired config rather than chaining
-    // straight onto #stopping, so a stop() arriving before it settles can cancel this restart.
+    // #exporters and #endpointCounts, which this start() would overwrite out from under it.
+    // Refuse rather than queue: the caller owns the decision of what to do once the shutdown
+    // settles, and by then its configuration may no longer be the one requested here. This is
+    // thrown outside the setup try/catch below so it does not count as a permanent start failure.
     if (this.#stopping) {
-      this.#pendingStart = config
-      return true
+      throw new Error('Cannot start the profiler while a shutdown collection is still in flight')
     }
 
     try {
@@ -294,11 +301,12 @@ class Profiler extends EventEmitter {
     this._timeoutInterval = this.#flushInterval
   }
 
+  /**
+   * Stops the profiler after collecting and exporting one final profile. That export outlives
+   * this call: {@link isStopping} returns true and start() throws until it settles, at which
+   * point a 'stopped' event is emitted.
+   */
   stop () {
-    // A stop() always reflects the latest desired state, so it cancels any restart queued by a
-    // start() that arrived while a prior shutdown collection was still in flight.
-    this.#pendingStart = undefined
-
     if (!this.enabled) return
 
     // collect and export current profiles
@@ -311,16 +319,12 @@ class Profiler extends EventEmitter {
       })
       .finally(() => {
         this.#stopping = undefined
-        if (this.#pendingStart) {
-          const config = this.#pendingStart
-          this.#pendingStart = undefined
-          // Unlike the synchronous entry point, nothing awaits this promise, so a throw here would
-          // become an unhandled rejection instead of a caught error.
-          try {
-            this.start(config)
-          } catch (error) {
-            log.error(error)
-          }
+        // Nothing awaits this promise, so a listener throwing here would become an unhandled
+        // rejection instead of reaching whoever requested the stop.
+        try {
+          this.emit('stopped')
+        } catch (error) {
+          log.error(error)
         }
       })
     this.#stop()