dd-trace 6.16.0 → 6.18.0

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

@@ -102,6 +102,7 @@ const TEST_STATUS = 'test.status'
 const TEST_FINAL_STATUS = 'test.final_status'
 const TEST_PARAMETERS = 'test.parameters'
 const TEST_SKIP_REASON = 'test.skip_reason'
+const TEST_SESSION_EMPTY_REASON = 'test.session.empty_reason'
 const TEST_IS_RUM_ACTIVE = 'test.is_rum_active'
 const TEST_CODE_OWNERS = 'test.codeowners'
 const TEST_SOURCE_FILE = 'test.source.file'
@@ -445,7 +446,6 @@ function addTestOptimizationRequest (requestPromises, responseNames, responseNam
  *
  * @param {string} testSuite
  * @param {string|undefined} testSuiteExecutionId
- * @returns {string}
  */
 function getTestSuiteExecutionKey (testSuite, testSuiteExecutionId) {
   return testSuiteExecutionId ? `${testSuite}\0${testSuiteExecutionId}` : testSuite
@@ -471,9 +471,11 @@ module.exports = {
   TEST_FINAL_STATUS,
   TEST_PARAMETERS,
   TEST_SKIP_REASON,
+  TEST_SESSION_EMPTY_REASON,
   TEST_IS_RUM_ACTIVE,
   setRumTestCorrelation,
   setRumTestTags,
+  setExpectedEmptyTestSessionTags,
   TEST_SOURCE_FILE,
   TEST_FAILURE_SCREENSHOT_UPLOADED,
   TEST_FAILURE_SCREENSHOT_UPLOAD_ERROR,
@@ -868,7 +870,6 @@ function finishAllTraceSpans (span) {
  * @param {import('../../opentracing/span')} testSpan
  * @param {boolean|undefined} isRumActive
  * @param {string} [browserVersion]
- * @returns {void}
  */
 function setRumTestTags (testSpan, isRumActive, browserVersion) {
   if (isRumActive) {
@@ -879,6 +880,29 @@ function setRumTestTags (testSpan, isRumActive, browserVersion) {
   }
 }
 
+/**
+ * Marks a successful test session that did not execute any tests.
+ *
+ * @param {import('../../opentracing/span')} testSessionSpan
+ * @param {import('../../opentracing/span')|undefined} testModuleSpan
+ * @param {'zero_tests'|'all_tests_skipped'|'zero_test_shard'|'test_discovery'} emptyReason
+ */
+function setExpectedEmptyTestSessionTags (testSessionSpan, testModuleSpan, emptyReason) {
+  const skipReason = emptyReason === 'test_discovery'
+    ? 'Test discovery only (--list)'
+    : emptyReason === 'zero_test_shard'
+      ? 'No tests were assigned to this shard'
+      : emptyReason === 'all_tests_skipped' ? 'All tests were skipped' : 'No tests were detected'
+
+  for (const span of [testSessionSpan, testModuleSpan]) {
+    if (!span) continue
+
+    span.setTag(TEST_STATUS, 'skip')
+    span.setTag(TEST_SKIP_REASON, skipReason)
+    span.setTag(TEST_SESSION_EMPTY_REASON, emptyReason)
+  }
+}
+
 /**
  * @param {RumTestCorrelationContext} context
  * @param {import('../../opentracing/span')|undefined} activeSpan
@@ -942,7 +966,6 @@ function getTestCommonTags (name, suite, version, testFramework) {
  *
  * @param {string | undefined} testSuiteAbsolutePath
  * @param {string} sourceRoot
- * @returns {string}
  */
 function getTestSuitePath (testSuiteAbsolutePath, sourceRoot) {
   if (!testSuiteAbsolutePath) {
@@ -1069,7 +1092,6 @@ const codeOwnersPerEntries = new WeakMap()
 
 /**
  * @param {string} character
- * @returns {string}
  */
 function escapeRegexCharacter (character) {
   return character.replaceAll(/[|\\{}()[\]^$+*?.]/g, String.raw`\$&`)
@@ -1077,7 +1099,6 @@ function escapeRegexCharacter (character) {
 
 /**
  * @param {string} pattern
- * @returns {boolean}
  */
 function hasUnescapedWildcard (pattern) {
   for (let i = 0; i < pattern.length; i++) {
@@ -1093,7 +1114,6 @@ function hasUnescapedWildcard (pattern) {
 
 /**
  * @param {string} pattern
- * @returns {string}
  */
 function codeOwnersPatternToRegexSource (pattern) {
   let source = ''
@@ -1172,7 +1192,6 @@ function setCodeOwnersPatternRegex (entry) {
  *
  * @param {RegExp|null} regex
  * @param {string} filename
- * @returns {boolean}
  */
 function isCodeOwnersPatternMatch (regex, filename) {
   if (!regex || !filename) {
@@ -1551,7 +1570,6 @@ function applySkippedCoverageToFileCoverage (fileCoverage, skippedBitmap) {
  * @param {object} coverage
  * @param {object} skippedCoverage
  * @param {string} [rootDir]
- * @returns {boolean}
  */
 function applySkippedCoverageToCoverage (coverage, skippedCoverage, rootDir) {
   const skippedCoverageByFilename = getSkippedCoverageByFilename(skippedCoverage)
@@ -1616,7 +1634,6 @@ function fromCoverageMapToCoverage (coverageMap) {
 
 /**
  * @param {number} code
- * @returns {boolean}
  */
 function isAsciiDigit (code) {
   return code >= 0x30 && code <= 0x39
@@ -2042,7 +2059,6 @@ function getModifiedFilesFromDiff (diff) {
  *
  * @param {string | undefined} testSuite
  * @param {string} testName
- * @returns {string}
  */
 function getTestOptimizationIdentity (testSuite, testName) {
   return JSON.stringify([testSuite, testName])
@@ -2053,7 +2069,6 @@ function getTestOptimizationIdentity (testSuite, testName) {
  *
  * @param {string | undefined} testSuite
  * @param {string} testName
- * @returns {string}
  */
 function formatTestOptimizationName (testSuite, testName) {
   return testSuite ? `${testSuite} › ${testName}` : testName
@@ -2063,7 +2078,6 @@ function formatTestOptimizationName (testSuite, testName) {
  * Replaces characters that could make one test occupy multiple CI log lines.
  *
  * @param {string} value
- * @returns {string}
  */
 function sanitizeTestOptimizationName (value) {
   return stripVTControlCharacters(value)
@@ -2077,7 +2091,6 @@ function sanitizeTestOptimizationName (value) {
  *
  * @param {string} value
  * @param {number} maxLength
- * @returns {string}
  */
 function truncateTestOptimizationNameStart (value, maxLength) {
   if (value.length <= maxLength) return value
@@ -2093,7 +2106,6 @@ function truncateTestOptimizationNameStart (value, maxLength) {
  *
  * @param {string} value
  * @param {number} maxLength
- * @returns {string}
  */
 function truncateTestOptimizationNameMiddle (value, maxLength) {
   if (value.length <= maxLength) return value
@@ -2112,7 +2124,6 @@ function truncateTestOptimizationNameMiddle (value, maxLength) {
  *
  * @param {string | undefined} testSuite
  * @param {string} testName
- * @returns {string}
  */
 function formatTestOptimizationDisplayName (testSuite, testName) {
   const sanitizedSuite = testSuite ? sanitizeTestOptimizationName(testSuite) : ''
@@ -2136,7 +2147,6 @@ function formatTestOptimizationDisplayName (testSuite, testName) {
  * Renders a bounded bullet list for Test Optimization summaries.
  *
  * @param {Array<{ text: string, suffix?: string }>} items
- * @returns {string}
  */
 function formatTestOptimizationList (items) {
   const shown = items.slice(0, MAX_TEST_OPTIMIZATION_SUMMARY_ITEMS)
@@ -2299,7 +2309,6 @@ function collectAttemptToFixExecutionFromTraceSpan (span, attemptToFixExecutions
  *
  * @param {{ meta?: Record<string, string> }} span
  * @param {TestManagementExecutions} executions
- * @returns {void}
  */
 function collectTestManagementExecutionFromTraceSpan (span, executions) {
   const meta = span.meta
@@ -2405,7 +2414,6 @@ function addAttemptToFixResultLine (lines, result) {
  *
  * @param {AttemptToFixExecutions} attemptToFixExecutions
  * @param {boolean} [includeTestNames]
- * @returns {string}
  */
 function formatAttemptToFixSummary (attemptToFixExecutions, includeTestNames = true) {
   if (attemptToFixExecutions.size === 0) return ''
@@ -2458,7 +2466,6 @@ function formatAttemptToFixSummary (attemptToFixExecutions, includeTestNames = t
  *
  * @param {TestManagementExecutions} executions
  * @param {boolean} [includeTestNames]
- * @returns {string}
  */
 function formatTestManagementSummary (executions, includeTestNames = true) {
   if (executions.size === 0) return ''
@@ -2509,7 +2516,6 @@ function formatTestManagementSummary (executions, includeTestNames = true) {
  * Formats the dynamic-name warning section of the Test Optimization summary.
  *
  * @param {Set<string>} newTestsWithDynamicNames
- * @returns {string}
  */
 function formatDynamicNamesSummary (newTestsWithDynamicNames) {
   if (newTestsWithDynamicNames.size === 0) return ''

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

@@ -19,7 +19,6 @@ const SPECIAL_CHARACTER_SEGMENT = /[%&'()*+,:=@]/
 /**
  * Extract full URL from HTTP request
  * @param {import('http').IncomingMessage} req
- * @returns {string} Full URL
  */
 function extractURL (req) {
   const headers = req.headers
@@ -42,7 +41,6 @@ function getProtocol (req) {
  *
  * @param {object} config
  * @param {string} url
- * @returns {string} obfuscated URL
  */
 function obfuscateQs (config, url) {
   const { queryStringObfuscation } = config
@@ -114,7 +112,6 @@ function getQsObfuscator (config) {
  * @param {string} base `scheme://host[:port]`
  * @param {string} [pathname] raw request path, may include `?query`
  * @param {string} strippedUrl `base` + query-stripped path (used when there is no query)
- * @returns {string}
  */
 function buildClientHttpUrl (config, base, pathname, strippedUrl) {
   if (pathname?.includes('?')) {
@@ -133,7 +130,6 @@ function buildClientHttpUrl (config, base, pathname, strippedUrl) {
  * - Cross tracers compatibility
  *
  * @param {string} url
- * @returns {string} Url path
  */
 function extractPathFromUrl (url) {
   if (!url) return '/'
@@ -146,7 +142,6 @@ function extractPathFromUrl (url) {
  * Calculate http.endpoint from URL path
  *
  * @param {string} url
- * @returns {string} The normalized endpoint
  */
 function calculateHttpEndpoint (url) {
   const path = extractPathFromUrl(url)

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

@@ -86,7 +86,6 @@ class PrioritySampler {
 
   /**
    * @param {DatadogSpan} span
-   * @returns {boolean} True if the trace should be sampled based on priority.
    */
   isSampled (span) {
     const priority = this._getPriorityFromAuto(span)
@@ -99,7 +98,6 @@ class PrioritySampler {
    *
    * @param {DatadogSpan} span
    * @param {boolean} [auto] - Whether to use automatic sampling if no manual tags are present.
-   * @returns {void}
    */
   sample (span, auto = true) {
     if (!span) return
@@ -131,7 +129,6 @@ class PrioritySampler {
    * Updates agent-provided sampling rates keyed by `service:,env:`.
    *
    * @param {Record<string, number>} rates
-   * @returns {void}
    */
   update (rates) {
     const samplers = {}
@@ -151,7 +148,6 @@ class PrioritySampler {
    * Validates that a sampling priority value is one of the allowed constants.
    *
    * @param {SamplingPriority|undefined} samplingPriority
-   * @returns {boolean}
    */
   validate (samplingPriority) {
     switch (samplingPriority) {
@@ -277,7 +273,6 @@ class PrioritySampler {
    * records the effective rate on the trace.
    *
    * @param {DatadogSpanContext} context
-   * @returns {boolean}
    */
   _isSampledByRateLimit (context) {
     // TODO: Change underscored properties to private ones.
@@ -316,7 +311,6 @@ class PrioritySampler {
    * Tags the trace with a decision maker when priority is keep, or removes it otherwise.
    *
    * @param {DatadogSpan} span
-   * @returns {void}
    */
   #addDecisionMaker (span) {
     const context = span.context()

package/packages/dd-trace/src/process-tags/index.js

@@ -16,7 +16,6 @@ const ENTRYPOINT_PATH = require.main?.filename || ''
  * Sanitize a process tag value
  *
  * @param {string} value
- * @returns {string}
  */
 function sanitize (value) {
   return String(value)

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

@@ -1,42 +1,139 @@
 'use strict'
 
-const { profiler } = require('./profiling')
+const dc = require('dc-polyfill')
 
-globalThis[Symbol.for('dd-trace')].beforeExitHandlers.add(() => { profiler.stop() })
+const log = require('./log')
 
-module.exports = {
-  /**
-   * @param {import('./config/config-base')} config - Tracer configuration
-   */
-  start (config) {
+const configUpdateChannel = dc.channel('datadog:config:update')
+
+/** @type {import('./profiling/ssi-heuristics').SSIHeuristics | undefined} */
+let activeSSIHeuristics
+
+/** @type {import('./profiling') | undefined} */
+let profilingModule
+
+function getProfilingModule () {
+  profilingModule ??= require('./profiling')
+  return profilingModule
+}
+
+// The profiling engine can stop itself (e.g. a collection error) without going through stop(), so
+// read its state directly rather than caching a flag that could drift out of sync. Checking
+// `profilingModule` first avoids forcing the profiling engine (and its native crashtracker binding)
+// to load just to read this.
+function isStarted () {
+  return profilingModule !== undefined && profilingModule.profiler.enabled
+}
+
+/** @type {typeof import('./profiling/ssi-heuristics') | undefined} */
+let ssiHeuristicsModule
+
+function getSSIHeuristicsModule () {
+  ssiHeuristicsModule ??= require('./profiling/ssi-heuristics')
+  return ssiHeuristicsModule
+}
+
+function disableSSIHeuristics () {
+  if (!activeSSIHeuristics) return
+  activeSSIHeuristics.disable()
+  activeSSIHeuristics = undefined
+}
+
+/**
+ * @param {import('./config/config-base')} config - Tracer configuration
+ */
+function start (config) {
+  try {
     // Forward the full tracer config to the profiling layer.
     // Profiling code is responsible for deriving the specific options it needs.
-    return profiler.start(config)
-  },
-
-  stop () {
-    profiler.stop()
-  },
-
-  /**
-   * Declares the set of custom label keys that will be used with
-   * `runWithLabels`.
-   *
-   * @param {Iterable<string>} keys - Custom label key names
-   */
-  setCustomLabelKeys: (keys) => {
-    profiler.setCustomLabelKeys(keys)
-  },
-
-  /**
-   * Runs a function with custom profiling labels attached to wall profiler samples.
-   *
-   * @param {Record<string, string | number>} labels - Custom labels to attach
-   * @param {function(): T} fn - Function to execute with the labels
-   * @returns {T} The return value of fn
-   * @template T
-   */
-  runWithLabels: (labels, fn) => {
-    return profiler.runWithLabels(labels, fn)
-  },
+    return getProfilingModule().profiler.start(config)
+  } catch (error) {
+    log.error(
+      'Error starting profiler. For troubleshooting tips, see <https://dtdg.co/nodejs-profiler-troubleshooting>',
+      error
+    )
+    return false
+  }
+}
+
+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.
+  if (profilingModule === undefined) return
+
+  try {
+    profilingModule.profiler.stop()
+  } catch (error) {
+    log.error(
+      'Error stopping profiler. For troubleshooting tips, see <https://dtdg.co/nodejs-profiler-troubleshooting>',
+      error
+    )
+  }
+}
+
+/**
+ * Declares the set of custom label keys that will be used with
+ * `runWithLabels`.
+ *
+ * @param {Iterable<string>} keys - Custom label key names
+ */
+function setCustomLabelKeys (keys) {
+  getProfilingModule().profiler.setCustomLabelKeys(keys)
 }
+
+/**
+ * Runs a function with custom profiling labels attached to wall profiler samples.
+ *
+ * @param {Record<string, string | number>} labels - Custom labels to attach
+ * @param {function(): T} fn - Function to execute with the labels
+ * @returns {T} The return value of fn
+ * @template T
+ */
+function runWithLabels (labels, fn) {
+  return getProfilingModule().profiler.runWithLabels(labels, fn)
+}
+
+configUpdateChannel.subscribe((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
+    // fires after this publish can't start the profiler behind this decision's back.
+    disableSSIHeuristics()
+    // Leave an already-running profiler alone; otherwise an unrelated remote-config publish
+    // (e.g. an unrelated sampling-rate change) would restart it on every update.
+    if (!isStarted()) start(config)
+  } else if (enabled === 'false') {
+    disableSSIHeuristics()
+    stop()
+  } else if (enabled === 'auto') {
+    if (!isStarted() && !activeSSIHeuristics) {
+      // 'auto' defers the start decision to SSI heuristics. A running profiler already reflects a
+      // decision that was made (by SSI or a prior unconditional enablement), so leave it alone
+      // rather than stopping and re-enabling it on every subsequent config publication. Also guard
+      // against creating another active instance; each SSIHeuristics instance owns listeners and a
+      // timer until the heuristic makes its decision or is explicitly disabled.
+      const { SSIHeuristics } = getSSIHeuristicsModule()
+      const heuristics = new SSIHeuristics(config)
+      activeSSIHeuristics = heuristics
+      heuristics.start()
+      heuristics.onTriggered(() => {
+        // Explicit true/false publishes disable the heuristics, so reaching this callback guarantees
+        // the latest valid published value is still 'auto'.
+        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
+        // started; it only tears down the completed heuristic.
+        heuristics.disable()
+        if (activeSSIHeuristics === heuristics) activeSSIHeuristics = undefined
+      })
+    }
+  } else {
+    // Invalid config should preserve the last valid profiling decision, not accidentally behave
+    // like 'auto' or crash the customer application.
+    log.warn('Unexpected DD_PROFILING_ENABLED value: %o', enabled)
+  }
+})
+
+globalThis[Symbol.for('dd-trace')].beforeExitHandlers.add(stop)
+
+module.exports = { isStarted, start, stop, setCustomLabelKeys, runWithLabels }

package/packages/dd-trace/src/profiling/exporters/event_serializer.js

@@ -15,7 +15,6 @@ const processTags = require('../../process-tags')
  * profile event.
  *
  * @param {string} [enabled] - config.profiling.DD_PROFILING_ENABLED ('true' | 'false' | 'auto')
- * @returns {string}
  */
 function getActivation (enabled) {
   if (enabled === 'auto') return 'auto'

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

@@ -61,9 +61,12 @@ class Profiler extends EventEmitter {
   #exporters
   #flushInterval
   #lastStart
+  #pendingStart
   #profileSeq = 0
   #profilers
   #spanFinishListener
+  #startFailed = false
+  #stopping
   #systemInfoReport
   #currentSnapshotTags
   #timer
@@ -175,48 +178,72 @@ class Profiler extends EventEmitter {
    */
   start (config) {
     if (this.enabled) return true
-    this.#enabled = true
-
-    const { tags: snapshotTags, exporters, flushInterval, profilers, uploadCompression, systemInfoReport } =
-      buildProfilingRuntime(config)
-    this.#config = config
-    this.#exporters = exporters
-    this.#flushInterval = flushInterval
-    this.#profilers = profilers
-    this.#currentSnapshotTags = snapshotTags
-    this.#uploadCompression = uploadCompression
-    this.#systemInfoReport = systemInfoReport
-    if (this.#customLabelKeys.size > 0) {
-      this.#applyCustomLabelKeys()
-    }
-
-    this._setInterval()
-    // Log errors if the source map finder fails, but don't prevent the rest
-    // of the profiler from running without source maps.
-    let mapper
-    const { setLogger, SourceMapper } = require('@datadog/pprof')
-    setLogger(pprofLogger)
-
-    if (config.DD_PROFILING_SOURCE_MAP) {
-      mapper = new SourceMapper(config.DD_PROFILING_DEBUG_SOURCE_MAPS)
-      mapper.loadDirectory(process.cwd())
-        .then(() => {
-          if (config.DD_PROFILING_DEBUG_SOURCE_MAPS) {
-            const count = mapper.infoMap.size
-            // eslint-disable-next-line eslint-rules/eslint-log-printf-style
-            log.debug(() => {
-              return count === 0
-                ? 'Found no source maps'
-                : `Found source maps for following files: [${[...mapper.infoMap.keys()].join(', ')}]`
-            })
-          }
-        })
-        .catch((error) => {
-          log.error(error)
-        })
+    // Initialization failures such as an unavailable native pprof binding are not expected to
+    // recover within the lifetime of this process. Preserve that decision without pretending the
+    // profiler is running or retrying setup on every subsequent config publication.
+    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.
+    if (this.#stopping) {
+      this.#pendingStart = config
+      return true
     }
 
     try {
+      const { tags: snapshotTags, exporters, flushInterval, profilers, uploadCompression, systemInfoReport } =
+        buildProfilingRuntime(config)
+      this.#config = config
+      this.#exporters = exporters
+      this.#flushInterval = flushInterval
+      this.#profilers = profilers
+      this.#currentSnapshotTags = snapshotTags
+      // A restart is installed only after the prior shutdown collection settles, so any endpoint
+      // counts left behind by a collection that produced no encodable profiles belong to the old run.
+      this.#endpointCounts.clear()
+      // Compression is initialized lazily and cached for a profiling run. A restarted profiler
+      // must derive it again from the newly built runtime instead of retaining the prior method
+      // or options.
+      this.#compressionFn = undefined
+      this.#compressionFnInitialized = false
+      this.#compressionOptions = undefined
+      this.#uploadCompression = uploadCompression
+      this.#systemInfoReport = systemInfoReport
+      if (this.#customLabelKeys.size > 0) {
+        this.#applyCustomLabelKeys()
+      }
+
+      this._setInterval()
+      // Log errors if the source map finder fails, but don't prevent the rest
+      // of the profiler from running without source maps.
+      let mapper
+      const { setLogger, SourceMapper } = require('@datadog/pprof')
+      setLogger(pprofLogger)
+
+      if (config.DD_PROFILING_SOURCE_MAP) {
+        mapper = new SourceMapper(config.DD_PROFILING_DEBUG_SOURCE_MAPS)
+        mapper.loadDirectory(process.cwd())
+          .then(() => {
+            if (config.DD_PROFILING_DEBUG_SOURCE_MAPS) {
+              const count = mapper.infoMap.size
+              // eslint-disable-next-line eslint-rules/eslint-log-printf-style
+              log.debug(() => {
+                return count === 0
+                  ? 'Found no source maps'
+                  : `Found source maps for following files: [${[...mapper.infoMap.keys()].join(', ')}]`
+              })
+            }
+          })
+          .catch((error) => {
+            log.error(error)
+          })
+      }
+
+      // Setup above does not start any sampler runtime resources. From this point onward, #stop()
+      // can safely clean up a partial start because #profilers and the rest of the runtime exist.
+      this.#enabled = true
       const start = new Date()
       const nearOOMCallback = this.#nearOOMExport.bind(this)
       for (const profiler of profilers) {
@@ -236,7 +263,17 @@ class Profiler extends EventEmitter {
       this._capture(this._timeoutInterval, start)
     } catch (error) {
       log.error(error)
-      this.#stop()
+      this.#startFailed = true
+      if (this.enabled) {
+        try {
+          this.#stop()
+        } catch (stopError) {
+          // A cleanup failure must not leave the public running state stuck at true or escape into
+          // the customer application.
+          this.#enabled = false
+          log.error(stopError)
+        }
+      }
       return false
     }
 
@@ -258,11 +295,34 @@ class Profiler extends EventEmitter {
   }
 
   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
     // once collect returns, profilers can be safely stopped
-    this._collect(snapshotKinds.ON_SHUTDOWN, false)
+    this.#stopping = this._collect(snapshotKinds.ON_SHUTDOWN, false)
+      .catch(error => {
+        // _collect() contains its own failures, but its cleanup can still throw. Nothing awaits
+        // this shutdown chain, so consume and log that failure instead of leaking a rejection.
+        log.error(error)
+      })
+      .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)
+          }
+        }
+      })
     this.#stop()
   }