dd-trace 5.81.0 → 5.83.0

package/packages/dd-trace/src/{config_stable.js → config/stable.js}

@@ -2,7 +2,7 @@
 
 const os = require('os')
 const fs = require('fs')
-const { getEnvironmentVariable } = require('../../dd-trace/src/config-helper')
+const { getEnvironmentVariable } = require('./helper')
 
 class StableConfig {
   constructor () {
@@ -11,14 +11,10 @@ class StableConfig {
     this.fleetEntries = {}
     this.wasm_loaded = false
 
-    const { localConfigPath, fleetConfigPath } = this._getStableConfigPaths()
-    if (!fs.existsSync(localConfigPath) && !fs.existsSync(fleetConfigPath)) {
-      // Bail out early if files don't exist to avoid unnecessary library loading
-      return
-    }
+    const { localConfigPath, fleetConfigPath } = this.#getStableConfigPaths()
 
-    const localConfig = this._readConfigFromPath(localConfigPath)
-    const fleetConfig = this._readConfigFromPath(fleetConfigPath)
+    const localConfig = this.#readConfigFromPath(localConfigPath)
+    const fleetConfig = this.#readConfigFromPath(fleetConfigPath)
     if (!localConfig && !fleetConfig) {
       // Bail out early if files are empty or we can't read them to avoid unnecessary library loading
       return
@@ -47,7 +43,7 @@ class StableConfig {
       // eslint-disable-next-line eslint-rules/eslint-process-env
       configurator.set_envp(Object.entries(process.env).map(([key, value]) => `${key}=${value}`))
       configurator.set_args(process.argv)
-      configurator.get_configuration(localConfig.toString(), fleetConfig.toString()).forEach((entry) => {
+      configurator.get_configuration(localConfig, fleetConfig).forEach((entry) => {
         if (entry.source === 'local_stable_config') {
           this.localEntries[entry.name] = entry.value
         } else if (entry.source === 'fleet_stable_config') {
@@ -59,43 +55,35 @@ class StableConfig {
     }
   }
 
-  _readConfigFromPath (path) {
+  #readConfigFromPath (path) {
     try {
       return fs.readFileSync(path, 'utf8')
     } catch (err) {
       if (err.code !== 'ENOENT') {
         this.warnings.push(`Error reading config file at ${path}. ${err.code}: ${err.message}`)
       }
-      return '' // Always return a string to avoid undefined.toString() errors
+      return '' // Always return a string for configurator.get_configuration()
     }
   }
 
-  _getStableConfigPaths () {
-    let localConfigPath = ''
-    let fleetConfigPath = ''
-    switch (os.type().toLowerCase()) {
-      case 'linux':
-        localConfigPath = '/etc/datadog-agent/application_monitoring.yaml'
-        fleetConfigPath = '/etc/datadog-agent/managed/datadog-agent/stable/application_monitoring.yaml'
-        break
+  #getStableConfigPaths () {
+    // TODO(BridgeAR): Remove these environment variables once we have a proper way to test the stable config.
+    // Allow overriding the paths for testing
+    let localConfigPath = getEnvironmentVariable('DD_TEST_LOCAL_CONFIG_PATH')
+    let fleetConfigPath = getEnvironmentVariable('DD_TEST_FLEET_CONFIG_PATH')
+    switch (os.platform()) {
       case 'darwin':
-        localConfigPath = '/opt/datadog-agent/etc/application_monitoring.yaml'
-        fleetConfigPath = '/opt/datadog-agent/etc/managed/datadog-agent/stable/application_monitoring.yaml'
+        localConfigPath ??= '/opt/datadog-agent/etc/application_monitoring.yaml'
+        fleetConfigPath ??= '/opt/datadog-agent/etc/managed/datadog-agent/stable/application_monitoring.yaml'
         break
       case 'win32':
-        localConfigPath = String.raw`C:\ProgramData\Datadog\application_monitoring.yaml`
-        fleetConfigPath = String.raw`C:\ProgramData\Datadog\managed\datadog-agent\stable\application_monitoring.yaml`
+        localConfigPath ??= String.raw`C:\ProgramData\Datadog\application_monitoring.yaml`
+        fleetConfigPath ??= String.raw`C:\ProgramData\Datadog\managed\datadog-agent\stable\application_monitoring.yaml`
         break
       default:
-        break
-    }
-
-    // Allow overriding the paths for testing
-    if (getEnvironmentVariable('DD_TEST_LOCAL_CONFIG_PATH') !== undefined) {
-      localConfigPath = getEnvironmentVariable('DD_TEST_LOCAL_CONFIG_PATH')
-    }
-    if (getEnvironmentVariable('DD_TEST_FLEET_CONFIG_PATH') !== undefined) {
-      fleetConfigPath = getEnvironmentVariable('DD_TEST_FLEET_CONFIG_PATH')
+        // Linux and other platforms as fallback
+        localConfigPath ??= '/etc/datadog-agent/application_monitoring.yaml'
+        fleetConfigPath ??= '/etc/datadog-agent/managed/datadog-agent/stable/application_monitoring.yaml'
     }
 
     return { localConfigPath, fleetConfigPath }

package/packages/dd-trace/src/{supported-configurations.json → config/supported-configurations.json}

@@ -37,6 +37,7 @@
     "DD_APPSEC_STACK_TRACE_ENABLED": ["A"],
     "DD_APPSEC_TRACE_RATE_LIMIT": ["A"],
     "DD_APPSEC_WAF_TIMEOUT": ["A"],
+    "DD_AZURE_RESOURCE_GROUP": ["A"],
     "DD_CIVISIBILITY_AGENTLESS_ENABLED": ["A"],
     "DD_CIVISIBILITY_AGENTLESS_URL": ["A"],
     "DD_CIVISIBILITY_AUTO_INSTRUMENTATION_PROVIDER": ["A"],
@@ -92,6 +93,7 @@
     "DD_GIT_TAG": ["A"],
     "DD_GIT_PULL_REQUEST_BASE_BRANCH": ["A"],
     "DD_GIT_PULL_REQUEST_BASE_BRANCH_SHA": ["A"],
+    "DD_GIT_COMMIT_HEAD_SHA": ["A"],
     "DD_GRPC_CLIENT_ERROR_STATUSES": ["A"],
     "DD_GRPC_SERVER_ERROR_STATUSES": ["A"],
     "DD_HEAP_SNAPSHOT_COUNT": ["A"],
@@ -111,6 +113,7 @@
     "DD_IAST_TELEMETRY_VERBOSITY": ["A"],
     "DD_INJECT_FORCE": ["A"],
     "DD_INJECTION_ENABLED": ["A"],
+    "DD_ENABLE_NX_SERVICE_NAME": ["A"],
     "DD_INSTRUMENTATION_CONFIG_ID": ["A"],
     "DD_INSTRUMENTATION_INSTALL_ID": ["A"],
     "DD_INSTRUMENTATION_INSTALL_TIME": ["A"],
@@ -162,6 +165,7 @@
     "DD_RUNTIME_METRICS_GC_ENABLED": ["A"],
     "DD_RUNTIME_METRICS_FLUSH_INTERVAL": ["A"],
     "DD_RUNTIME_METRICS_RUNTIME_ID_ENABLED": ["A"],
+    "DD_TRACE_GCP_PUBSUB_PUSH_ENABLED": ["A"],
     "DD_SERVICE_MAPPING": ["A"],
     "DD_SERVICE": ["A"],
     "DD_SITE": ["A"],
@@ -243,6 +247,7 @@
     "DD_TRACE_BAGGAGE_TAG_KEYS": ["A"],
     "DD_TRACE_BEAUTIFUL_LOGS": ["A"],
     "DD_TRACE_BLUEBIRD_ENABLED": ["A"],
+    "DD_TRACE_BULLMQ_ENABLED": ["A"],
     "DD_TRACE_BODY_PARSER_ENABLED": ["A"],
     "DD_TRACE_BSON_ENABLED": ["A"],
     "DD_TRACE_BUNYAN_ENABLED": ["A"],

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

@@ -50,8 +50,13 @@ module.exports = {
   GRPC_SERVER_ERROR_STATUSES: [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16],
   DYNAMODB_PTR_KIND: 'aws.dynamodb.item',
   S3_PTR_KIND: 'aws.s3.object',
+  WEBSOCKET_PTR_KIND: 'websocket',
   SPAN_POINTER_DIRECTION: Object.freeze({
     UPSTREAM: 'u',
     DOWNSTREAM: 'd'
+  }),
+  SPAN_POINTER_DIRECTION_NAME: Object.freeze({
+    UPSTREAM: 'span-pointer-up',
+    DOWNSTREAM: 'span-pointer-down'
   })
 }

package/packages/dd-trace/src/crashtracking/crashtracker.js

@@ -1,13 +1,15 @@
 'use strict'
 
+const { URL } = require('url')
+
 // Load binding first to not import other modules if it throws
 const libdatadog = require('@datadog/libdatadog')
 const binding = libdatadog.load('crashtracker')
 
 const log = require('../log')
-const defaults = require('../config_defaults')
-const { URL } = require('url')
+const defaults = require('../config/defaults')
 const pkg = require('../../../../package.json')
+const processTags = require('../process-tags')
 
 class Crashtracker {
   #started = false
@@ -77,6 +79,13 @@ class Crashtracker {
   #getMetadata (config) {
     const tags = Object.keys(config.tags).map(key => `${key}:${config.tags[key]}`)
 
+    // Add process tags to the tags array
+    for (const [key, value] of processTags.tags) {
+      if (value !== undefined) {
+        tags.push(`${key}:${value}`)
+      }
+    }
+
     return {
       library_name: pkg.name,
       library_version: pkg.version,

package/packages/dd-trace/src/datastreams/checkpointer.js

@@ -13,7 +13,7 @@ class DataStreamsCheckpointer {
    * @param {string} type - The type of the checkpoint, usually the streaming technology being used.
    *                       Examples include kafka, kinesis, sns etc.
    * @param {string} target - The target of data. This can be a topic, exchange or stream name.
-   * @param {Object} carrier - The carrier object to inject context into.
+   * @param {object} carrier - The carrier object to inject context into.
    */
   setProduceCheckpoint (type, target, carrier) {
     if (!this.config.dsmEnabled) return
@@ -33,7 +33,7 @@ class DataStreamsCheckpointer {
    * @param {string} type - The type of the checkpoint, usually the streaming technology being used.
    *                       Examples include kafka, kinesis, sns etc.
    * @param {string} source - The source of data. This can be a topic, exchange or stream name.
-   * @param {Object} carrier - The carrier object to extract context from.
+   * @param {object} carrier - The carrier object to extract context from.
    * @param {boolean} [manualCheckpoint=true] - Whether this checkpoint was manually set. Keep true if manually
    *                                           instrumenting. Manual instrumentation always overrides automatic
    *                                           instrumentation in the case a call is both manually and automatically

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

@@ -13,7 +13,7 @@ const {
 //
 // TODO: Remove this when DSM has been moved to dedicated plugins.
 /**
- * @template T extends new (...args: any[]) => any
+ * @template T extends new (...args: unknown[]) => unknown
  * @param {() => T} classGetter
  * @param {string[]} methods
  * @param {string[]} staticMethods

package/packages/dd-trace/src/datastreams/pathway.js

@@ -4,10 +4,10 @@
 // other languages use FNV1
 // this inconsistency is ok because hashes do not need to be consistent across services
 const crypto = require('crypto')
-const { encodeVarint, decodeVarint } = require('./encoding')
 const { LRUCache } = require('../../../../vendor/dist/lru-cache')
 const log = require('../log')
 const pick = require('../../../datadog-core/src/utils/src/pick')
+const { encodeVarint, decodeVarint } = require('./encoding')
 
 const cache = new LRUCache({ max: 500 })
 
@@ -44,7 +44,7 @@ function computeHash (service, env, edgeTags, parentHash) {
 }
 
 /**
- * @param {Object} dataStreamsContext
+ * @param {object} dataStreamsContext
  * @param {Buffer} dataStreamsContext.hash
  * @param {number} dataStreamsContext.pathwayStartNs
  * @param {number} dataStreamsContext.edgeStartNs
@@ -59,7 +59,7 @@ function encodePathwayContext (dataStreamsContext) {
 }
 
 /**
- * @param {Object} dataStreamsContext
+ * @param {object} dataStreamsContext
  * @param {Buffer} dataStreamsContext.hash
  * @param {number} dataStreamsContext.pathwayStartNs
  * @param {number} dataStreamsContext.edgeStartNs
@@ -72,7 +72,7 @@ function encodePathwayContextBase64 (dataStreamsContext) {
 
 /**
  * @param {Buffer} pathwayContext
- * @returns {Object}
+ * @returns {object}
  */
 function decodePathwayContext (pathwayContext) {
   if (pathwayContext == null || pathwayContext.length < 8) {
@@ -111,11 +111,11 @@ const DsmPathwayCodec = {
   // we use a class for encoding / decoding in case we update our encoding/decoding. A class will make updates easier
   // instead of using individual functions.
   /**
-   * @param {Object} dataStreamsContext
+   * @param {object} dataStreamsContext
    * @param {Buffer} dataStreamsContext.hash
    * @param {number} dataStreamsContext.pathwayStartNs
    * @param {number} dataStreamsContext.edgeStartNs
-   * @param {Object} carrier
+   * @param {object} carrier
    */
   encode (dataStreamsContext, carrier) {
     if (!dataStreamsContext || !dataStreamsContext.hash) {
@@ -127,7 +127,7 @@ const DsmPathwayCodec = {
   },
 
   /**
-   * @param {Object} carrier
+   * @param {object} carrier
    * @returns {ReturnType<typeof decodePathwayContext>|undefined}
    */
   decode (carrier) {

package/packages/dd-trace/src/datastreams/processor.js

@@ -4,14 +4,14 @@ const os = require('os')
 const pkg = require('../../../../package.json')
 
 const { LogCollapsingLowestDenseDDSketch } = require('../../../../vendor/dist/@datadog/sketches-js')
+const { PATHWAY_HASH } = require('../../../../ext/tags')
+const log = require('../log')
 const { DsmPathwayCodec } = require('./pathway')
 const { DataStreamsWriter } = require('./writer')
 const { computePathwayHash } = require('./pathway')
 const { getAmqpMessageSize, getHeadersSize, getMessageSize, getSizeOrZero } = require('./size')
-const { PATHWAY_HASH } = require('../../../../ext/tags')
 const { SchemaBuilder } = require('./schemas/schema_builder')
 const { SchemaSampler } = require('./schemas/schema_sampler')
-const log = require('../log')
 
 const ENTRY_PARENT_HASH = Buffer.from('0000000000000000', 'hex')
 
@@ -156,7 +156,7 @@ class DataStreamsProcessor {
       this.timer = setInterval(this.onInterval.bind(this), flushInterval)
       this.timer.unref()
     }
-    process.once('beforeExit', () => this.onInterval())
+    globalThis[Symbol.for('dd-trace')].beforeExitHandlers.add(this.onInterval.bind(this))
   }
 
   onInterval () {

package/packages/dd-trace/src/datastreams/writer.js

@@ -1,12 +1,12 @@
 'use strict'
 
+const { URL, format } = require('url')
+const zlib = require('zlib')
 const pkg = require('../../../../package.json')
 const log = require('../log')
 const request = require('../exporters/common/request')
-const { URL, format } = require('url')
 const { MsgpackEncoder } = require('../msgpack')
-const defaults = require('../config_defaults')
-const zlib = require('zlib')
+const defaults = require('../config/defaults')
 
 const msgpack = new MsgpackEncoder()
 

package/packages/dd-trace/src/debugger/config.js

@@ -8,6 +8,7 @@ module.exports = function getDebuggerConfig (config) {
     hostname: config.hostname,
     logLevel: config.logLevel,
     port: config.port,
+    propagateProcessTags: config.propagateProcessTags,
     repositoryUrl: config.repositoryUrl,
     runtimeId: config.tags['runtime-id'],
     service: config.service,

package/packages/dd-trace/src/debugger/devtools_client/condition.js

@@ -206,7 +206,7 @@ function isTypedArray (variable) {
 }
 
 function isInstanceOfCoreType (type, variable, fallback = `${variable} instanceof ${type}`) {
-  return `(process[Symbol.for('datadog:node:util:types')]?.is${type}?.(${variable}) ?? ${fallback})`
+  return `(globalThis[Symbol.for('dd-trace')].utilTypes?.is${type}?.(${variable}) ?? ${fallback})`
 }
 
 function getSize (variable) {

package/packages/dd-trace/src/debugger/devtools_client/config.js

@@ -2,8 +2,8 @@
 
 const { workerData: { config: parentConfig, parentThreadId, configPort } } = require('node:worker_threads')
 const { format } = require('node:url')
+const defaults = require('../../config/defaults')
 const log = require('./log')
-const defaults = require('../../config_defaults')
 
 const config = module.exports = {
   ...parentConfig,

package/packages/dd-trace/src/debugger/devtools_client/index.js

@@ -1,6 +1,9 @@
 'use strict'
 
 const { randomUUID } = require('crypto')
+const { version } = require('../../../../../package.json')
+const { NODE_MAJOR } = require('../../../../../version')
+const processTags = require('../../process-tags')
 const { breakpointToProbes } = require('./state')
 const session = require('./session')
 const { getLocalStateForCallFrame } = require('./snapshot')
@@ -10,8 +13,6 @@ const { ackEmitting } = require('./status')
 const config = require('./config')
 const { MAX_SNAPSHOTS_PER_SECOND_GLOBALLY } = require('./defaults')
 const log = require('./log')
-const { version } = require('../../../../../package.json')
-const { NODE_MAJOR } = require('../../../../../version')
 
 require('./remote_config')
 
@@ -215,6 +216,10 @@ session.on('Debugger.paused', async ({ params }) => {
       language: 'javascript'
     }
 
+    if (config.propagateProcessTags.enabled) {
+      snapshot[processTags.DYNAMIC_INSTRUMENTATION_FIELD_NAME] = processTags.tagsObject
+    }
+
     if (probe.captureSnapshot) {
       if (captureErrors?.length > 0) {
         // There was an error collecting the snapshot for this probe, let's not try again

package/packages/dd-trace/src/debugger/devtools_client/send.js

@@ -3,13 +3,13 @@
 const { hostname: getHostname } = require('os')
 const { stringify } = require('querystring')
 
-const config = require('./config')
-const JSONBuffer = require('./json-buffer')
 const request = require('../../exporters/common/request')
 const { GIT_COMMIT_SHA, GIT_REPOSITORY_URL } = require('../../plugins/util/tags')
-const log = require('./log')
 const { version } = require('../../../../../package.json')
-const { getEnvironmentVariable } = require('../../config-helper')
+const { getValueFromEnvSources } = require('../../config/helper')
+const log = require('./log')
+const JSONBuffer = require('./json-buffer')
+const config = require('./config')
 const { pruneSnapshot } = require('./snapshot-pruner')
 
 module.exports = send
@@ -23,8 +23,8 @@ const hostname = getHostname()
 const service = config.service
 
 const ddtags = [
-  ['env', getEnvironmentVariable('DD_ENV')],
-  ['version', getEnvironmentVariable('DD_VERSION')],
+  ['env', getValueFromEnvSources('DD_ENV')],
+  ['version', getValueFromEnvSources('DD_VERSION')],
   ['debugger_version', version],
   ['host_name', hostname],
   [GIT_COMMIT_SHA, config.commitSHA],

package/packages/dd-trace/src/debugger/devtools_client/session.js

@@ -7,7 +7,7 @@ const inspector = require('./inspector_promises_polyfill')
  *   connect: () => void,
  *   connectToMainThread: () => void
  *   disconnect: () => void,
- *   post: (method: string, params?: object) => Promise<any>,
+ *   post: (method: string, params?: object) => Promise<unknown>,
  * }} CDPSession
  */
 const session = /** @type {CDPSession} */ (new inspector.Session())

package/packages/dd-trace/src/debugger/devtools_client/snapshot/collector.js

@@ -1,8 +1,8 @@
 'use strict'
 
+const session = require('../session')
 const { collectionSizeSym, largeCollectionSkipThresholdSym, fieldCountSym, timeBudgetSym } = require('./symbols')
 const { LARGE_OBJECT_SKIP_THRESHOLD } = require('./constants')
-const session = require('../session')
 
 const LEAF_SUBTYPES = new Set(['date', 'regexp'])
 const ITERABLE_SUBTYPES = new Set(['map', 'set', 'weakmap', 'weakset'])
@@ -13,12 +13,12 @@ module.exports = {
 }
 
 /**
- * @typedef {Object} GetObjectOptions
- * @property {Object} maxReferenceDepth - The maximum depth of the object to traverse
+ * @typedef {object} GetObjectOptions
+ * @property {object} maxReferenceDepth - The maximum depth of the object to traverse
  * @property {number} maxCollectionSize - The maximum size of a collection to include in the snapshot
  * @property {number} maxFieldCount - The maximum number of properties on an object to include in the snapshot
  * @property {bigint} deadlineNs - The deadline in nanoseconds compared to `process.hrtime.bigint()`
- * @property {Object} ctx - A context object to track the state/progress of the snapshot collection.
+ * @property {object} ctx - A context object to track the state/progress of the snapshot collection.
  * @property {boolean} ctx.deadlineReached - Will be set to `true` if the deadline has been reached.
  * @property {Error[]} ctx.captureErrors - An array on which errors can be pushed if an issue is detected while
  *   collecting the snapshot.
@@ -34,7 +34,7 @@ module.exports = {
  *   and should not be set by the caller.
  * @param {boolean} [collection=false] - Whether the object is a collection. Only used internally by this module to
  *   track the current object type and should not be set by the caller.
- * @returns {Promise<Object[]>} The properties of the object
+ * @returns {Promise<object[]>} The properties of the object
  */
 async function collectObjectProperties (objectId, opts, depth = 0, collection = false) {
   const { result, privateProperties } = await session.post('Runtime.getProperties', {

package/packages/dd-trace/src/debugger/devtools_client/snapshot/constants.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const { getEnvironmentVariable } = require('../../../config-helper')
+const { getEnvironmentVariable } = require('../../../config/helper')
 
 const largeObjectSkipThreshold = Number(
   getEnvironmentVariable('_DD_DYNAMIC_INSTRUMENTATION_EXPERIMENTAL_LARGE_OBJECT_SKIP_THRESHOLD')

package/packages/dd-trace/src/debugger/devtools_client/snapshot/index.js

@@ -16,7 +16,7 @@ module.exports = {
 }
 
 /**
- * @typedef {Object} GetLocalStateForCallFrameOptions
+ * @typedef {object} GetLocalStateForCallFrameOptions
  * @property {number} [maxReferenceDepth] - The maximum depth of the object to traverse. Defaults to
  *   {@link DEFAULT_MAX_REFERENCE_DEPTH}.
  * @property {number} [maxCollectionSize] - The maximum size of a collection to include in the snapshot. Defaults to
@@ -34,7 +34,7 @@ module.exports = {
  *
  * @param {import('inspector').Debugger.CallFrame} callFrame - The call frame to get the local state for
  * @param {GetLocalStateForCallFrameOptions} [opts] - The options for the snapshot
- * @returns {Promise<Object>} The local state for the call frame
+ * @returns {Promise<object>} The local state for the call frame
  */
 async function getLocalStateForCallFrame (
   callFrame,

package/packages/dd-trace/src/debugger/devtools_client/state.js

@@ -24,7 +24,7 @@ module.exports = {
    * Find the script to inspect based on a partial or absolute path. Handles both Windows and POSIX paths.
    *
    * @param {string} path - Partial or absolute path to match against loaded scripts
-   * @returns {Object | null} - Object containing `url`, `scriptId`, `sourceMapURL`, and `source` - or null if no match
+   * @returns {object | null} - Object containing `url`, `scriptId`, `sourceMapURL`, and `source` - or null if no match
    */
   findScriptFromPartialPath (path) {
     if (!path) return null // This shouldn't happen, but better safe than sorry

package/packages/dd-trace/src/debugger/devtools_client/status.js

@@ -1,10 +1,10 @@
 'use strict'
 
 const TTLSet = require('../../../../../vendor/dist/ttl-set')
-const config = require('./config')
-const JSONBuffer = require('./json-buffer')
 const request = require('../../exporters/common/request')
 const FormData = require('../../exporters/common/form-data')
+const config = require('./config')
+const JSONBuffer = require('./json-buffer')
 const log = require('./log')
 
 module.exports = {

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

@@ -4,32 +4,55 @@ const { readFile } = require('fs')
 const { types } = require('util')
 const { join } = require('path')
 const { Worker, MessageChannel, threadId: parentThreadId } = require('worker_threads')
-const getDebuggerConfig = require('./config')
 const log = require('../log')
+const getDebuggerConfig = require('./config')
 
 let worker = null
 let configChannel = null
 let ackId = 0
+let rcAckCallbacks = null
+let rc = null
 
 // eslint-disable-next-line eslint-rules/eslint-process-env
 const { NODE_OPTIONS, ...env } = process.env
 
 module.exports = {
+  isStarted,
   start,
-  configure
+  configure,
+  stop
+}
+
+/**
+ * Check if the Debugger worker is currently running
+ *
+ * @returns {boolean} True if the worker is started, false otherwise
+ */
+function isStarted () {
+  return worker !== null
 }
 
-function start (config, rc) {
+/**
+ * Start the Debugger worker thread.
+ * Creates a worker thread, sets up message channels, and registers
+ * the LIVE_DEBUGGING product handler with remote config.
+ * Does nothing if the worker is already started.
+ *
+ * @param {object} config - The tracer configuration object
+ * @param {object} rcInstance - The RemoteConfig instance
+ */
+function start (config, rcInstance) {
   if (worker !== null) return
 
   log.debug('[debugger] Starting Dynamic Instrumentation client...')
 
-  const rcAckCallbacks = new Map()
+  rc = rcInstance
+  rcAckCallbacks = new Map()
   const probeChannel = new MessageChannel()
   const logChannel = new MessageChannel()
   configChannel = new MessageChannel()
 
-  process[Symbol.for('datadog:node:util:types')] = types
+  globalThis[Symbol.for('dd-trace')].utilTypes = types
 
   readProbeFile(config.dynamicInstrumentation.probeFile, (probes) => {
     const action = 'apply'
@@ -84,19 +107,10 @@ function start (config, rc) {
   worker.on('error', (err) => log.error('[debugger] worker thread error', err))
   worker.on('messageerror', (err) => log.error('[debugger] received "messageerror" from worker', err))
 
-  worker.on('exit', (code) => {
+  worker.once('exit', (code) => {
     const error = new Error(`Dynamic Instrumentation worker thread exited unexpectedly with code ${code}`)
-
     log.error('[debugger] worker thread exited unexpectedly', error)
-
-    // Be nice, clean up now that the worker thread encountered an issue and we can't continue
-    rc.removeProductHandler('LIVE_DEBUGGING')
-    worker.removeAllListeners()
-    configChannel = null
-    for (const ackId of rcAckCallbacks.keys()) {
-      rcAckCallbacks.get(ackId)(error)
-      rcAckCallbacks.delete(ackId)
-    }
+    cleanup(error) // Be nice, clean up now that the worker thread encountered an issue and we can't continue
   })
 
   worker.unref()
@@ -108,11 +122,65 @@ function start (config, rc) {
   configChannel.port2.unref()
 }
 
+/**
+ * Reconfigure the Debugger worker with updated settings.
+ * Sends the new configuration to the worker thread via the config channel.
+ * Does nothing if the worker is not started.
+ *
+ * @param {object} config - The updated tracer configuration object
+ */
 function configure (config) {
   if (configChannel === null) return
   configChannel.port2.postMessage(getDebuggerConfig(config))
 }
 
+/**
+ * Stop the Debugger worker thread.
+ * Terminates the worker and cleans up resources.
+ * Safe to call even if the worker is not started.
+ */
+function stop () {
+  if (worker === null) return
+
+  log.debug('[debugger] Stopping Dynamic Instrumentation client...')
+
+  try {
+    worker.terminate()
+    cleanup() // Graceful shutdown - termination succeeded
+  } catch (err) {
+    log.error('[debugger] Error terminating worker', err)
+    cleanup(err) // Cleanup with error - termination failed
+  }
+}
+
+/**
+ * Internal cleanup function to reset all debugger resources.
+ * Called when stopping the debugger or when the worker exits unexpectedly.
+ *
+ * @param {Error} [error] - Optional error to pass to pending ack callbacks (for unexpected exits)
+ */
+function cleanup (error) {
+  if (rc) {
+    rc.removeProductHandler('LIVE_DEBUGGING')
+    rc = null
+  }
+  if (worker) {
+    worker.removeAllListeners()
+    worker = null
+  }
+  configChannel = null
+
+  // Call any pending ack callbacks
+  // Pass error for unexpected exits, or undefined for graceful shutdown
+  if (rcAckCallbacks) {
+    for (const ackId of rcAckCallbacks.keys()) {
+      rcAckCallbacks.get(ackId)(error)
+      rcAckCallbacks.delete(ackId)
+    }
+    rcAckCallbacks = null
+  }
+}
+
 function readProbeFile (path, cb) {
   if (!path) return