dd-trace 4.18.0 → 5.6.0

package/CONTRIBUTING.md

@@ -70,4 +70,102 @@ We follow an all-green policy which means that for any PR to be merged _all_ tes
 
 Eventually we plan to look into putting these permission-required tests behind a label which team members can add to their PRs at creation to run the full CI and can add to outside contributor PRs to trigger the CI from their own user credentials. If the label is not present there will be another action which checks the label is present. Rather than showing a bunch of confusing failures to new contributors it would just show a single job failure which indicates an additional label is required, and we can name it in a way that makes it clear that it's not the responsibility of the outside contributor to add it. Something like `approve-full-ci` is one possible choice there.
 
+## Development Requirements
+
+Since this project supports multiple Node versions, using a version
+manager such as [nvm](https://github.com/creationix/nvm) is recommended.
+
+We use [yarn](https://yarnpkg.com/) for its workspace functionality, so make sure to install that as well.
+
+To install dependencies once you have Node and yarn installed, run:
+
+```sh
+$ yarn
+```
+
+
+## Testing
+
+Before running _plugin_ tests, the data stores need to be running.
+The easiest way to start all of them is to use the provided
+docker-compose configuration:
+
+```sh
+$ docker-compose up -d -V --remove-orphans --force-recreate
+$ yarn services
+```
+
+> **Note**
+> The `couchbase`, `grpc` and `oracledb` instrumentations rely on native modules
+> that do not compile on ARM64 devices (for example M1/M2 Mac) - their tests
+> cannot be run locally on these devices.
+
+### Unit Tests
+
+There are several types of unit tests, for various types of components. The
+following commands may be useful:
+
+```sh
+# Tracer core tests (i.e. testing `packages/dd-trace`)
+$ yarn test:trace:core
+# "Core" library tests (i.e. testing `packages/datadog-core`
+$ yarn test:core
+# Instrumentations tests (i.e. testing `packages/datadog-instrumentations`
+$ yarn test:instrumentations
+```
+
+Several other components have test commands as well. See `package.json` for
+details.
+
+To test _plugins_ (i.e. components in `packages/datadog-plugin-XXXX`
+directories, set the `PLUGINS` environment variable to the plugin you're
+interested in, and use `yarn test:plugins`. If you need to test multiple
+plugins you may separate then with a pipe (`|`) delimiter. Here's an
+example testing the `express` and `bluebird` plugins:
+
+```sh
+PLUGINS="express|bluebird" yarn test:plugins
+```
+
+
+### Memory Leaks
+
+To run the memory leak tests, use:
+
+```sh
+$ yarn leak:core
+
+# or
+
+$ yarn leak:plugins
+```
+
+
+### Linting
+
+We use [ESLint](https://eslint.org) to make sure that new code
+conforms to our coding standards.
+
+To run the linter, use:
+
+```sh
+$ yarn lint
+```
+
+
+### Benchmarks
+
+Our microbenchmarks live in `benchmark/sirun`. Each directory in there
+corresponds to a specific benchmark test and its variants, which are used to
+track regressions and improvements over time.
+
+In addition to those, when two or more approaches must be compared, please write
+a benchmark in the `benchmark/index.js` module so that we can keep track of the
+most efficient algorithm. To run your benchmark, use:
+
+```sh
+$ yarn bench
+```
+
+
 [1]: https://docs.datadoghq.com/help

package/LICENSE-3rdparty.csv

@@ -8,7 +8,7 @@ require,@datadog/sketches-js,Apache license 2.0,Copyright 2020 Datadog Inc.
 require,@opentelemetry/api,Apache license 2.0,Copyright OpenTelemetry Authors
 require,@opentelemetry/core,Apache license 2.0,Copyright OpenTelemetry Authors
 require,crypto-randomuuid,MIT,Copyright 2021 Node.js Foundation and contributors
-require,diagnostics_channel,MIT,Copyright 2021 Simon D.
+require,dc-polyfill,MIT,Copyright 2023 Datadog Inc.
 require,ignore,MIT,Copyright 2013 Kael Zhang and contributors
 require,import-in-the-middle,Apache license 2.0,Copyright 2021 Datadog Inc.
 require,int64-buffer,MIT,Copyright 2015-2016 Yusuke Kawasaki
@@ -17,10 +17,7 @@ require,istanbul-lib-coverage,BSD-3-Clause,Copyright 2012-2015 Yahoo! Inc.
 require,jest-docblock,MIT,Copyright Meta Platforms, Inc. and affiliates.
 require,koalas,MIT,Copyright 2013-2017 Brian Woodward
 require,limiter,MIT,Copyright 2011 John Hurliman
-require,lodash.kebabcase,MIT,Copyright JS Foundation and other contributors
-require,lodash.pick,MIT,Copyright JS Foundation and other contributors
 require,lodash.sortby,MIT,Copyright JS Foundation and other contributors
-require,lodash.uniq,MIT,Copyright JS Foundation and other contributors
 require,lru-cache,ISC,Copyright (c) 2010-2022 Isaac Z. Schlueter and Contributors
 require,methods,MIT,Copyright 2013-2014 TJ Holowaychuk
 require,module-details-from-path,MIT,Copyright 2016 Thomas Watson Steen
@@ -28,9 +25,12 @@ require,msgpack-lite,MIT,Copyright 2015 Yusuke Kawasaki
 require,node-abort-controller,MIT,Copyright (c) 2019 Steve Faulkner
 require,opentracing,MIT,Copyright 2016 Resonance Labs Inc
 require,path-to-regexp,MIT,Copyright 2014 Blake Embrey
+require,pprof-format,MIT,Copyright 2022 Stephen Belanger
 require,protobufjs,BSD-3-Clause,Copyright 2016 Daniel Wirtz
+require,tlhunter-sorted-set,MIT,Copyright (c) 2023 Datadog Inc.
 require,retry,MIT,Copyright 2011 Tim Koschützki Felix Geisendörfer
 require,semver,ISC,Copyright Isaac Z. Schlueter and Contributors
+require,shell-quote,mit,Copyright (c) 2013 James Halliday
 dev,@types/node,MIT,Copyright Authors
 dev,autocannon,MIT,Copyright 2016 Matteo Collina
 dev,aws-sdk,Apache 2.0,Copyright 2012-2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
@@ -62,7 +62,6 @@ dev,mocha,MIT,Copyright 2011-2018 JS Foundation and contributors https://js.foun
 dev,multer,MIT,Copyright 2014 Hage Yaapa
 dev,nock,MIT,Copyright 2017 Pedro Teixeira and other contributors
 dev,nyc,ISC,Copyright 2015 Contributors
-dev,pprof-format,MIT,Copyright 2022 Stephen Belanger
 dev,proxyquire,MIT,Copyright 2013 Thorsten Lorenz
 dev,rimraf,ISC,Copyright Isaac Z. Schlueter and Contributors
 dev,sinon,BSD-3-Clause,Copyright 2010-2017 Christian Johansen

package/MIGRATING.md

@@ -4,6 +4,21 @@ This guide describes the steps to upgrade dd-trace from a major version to the
 next. If you are having any issues related to migrating, please feel free to
 open an issue or contact our [support](https://www.datadoghq.com/support/) team.
 
+## 4.0 to 5.0
+
+### Node 16 is no longer supported
+
+Node.js 16 has reached EOL in September 2023 and is no longer supported. Generally
+speaking, we highly recommend always keeping Node.js up to date regardless of
+our support policy.
+
+### Update `trace<T>` TypeScript declaration
+
+The TypeScript declaration for `trace<T>` has been updated to enforce 
+that calls to `tracer.trace(name, fn)` must receive a function which takes at least 
+the span object. Previously the span was technically optional when it should not have 
+been as the span must be handled.
+
 ## 3.0 to 4.0
 
 ### Node 14 is no longer supported

package/README.md

@@ -1,7 +1,8 @@
 # `dd-trace`: Node.js APM Tracer Library
 
-[![npm v4](https://img.shields.io/npm/v/dd-trace/latest?color=blue&label=dd-trace%40v4&logo=npm)](https://www.npmjs.com/package/dd-trace)
-[![npm v3](https://img.shields.io/npm/v/dd-trace/latest-node14?color=blue&label=dd-trace%40v3&logo=npm)](https://www.npmjs.com/package/dd-trace/v/latest-node12)
+[![npm v5](https://img.shields.io/npm/v/dd-trace/latest?color=blue&label=dd-trace%40v5&logo=npm)](https://www.npmjs.com/package/dd-trace)
+[![npm v4](https://img.shields.io/npm/v/dd-trace/latest-node16?color=blue&label=dd-trace%40v4&logo=npm)](https://www.npmjs.com/package/dd-trace/v/latest-node16)
+[![npm v3](https://img.shields.io/npm/v/dd-trace/latest-node14?color=blue&label=dd-trace%40v3&logo=npm)](https://www.npmjs.com/package/dd-trace/v/latest-node14)
 [![codecov](https://codecov.io/gh/DataDog/dd-trace-js/branch/master/graph/badge.svg)](https://codecov.io/gh/DataDog/dd-trace-js)
 
 <img align="right" src="https://user-images.githubusercontent.com/551402/208212084-1d0c07e2-4135-4c61-b2da-8f2fddbc66ed.png" alt="Bits the dog  JavaScript" width="200px"/>
@@ -28,24 +29,25 @@ Most of the documentation for `dd-trace` is available on these webpages:
 | [`v1`](https://github.com/DataDog/dd-trace-js/tree/v1.x) | ![npm v1](https://img.shields.io/npm/v/dd-trace/legacy-v1?color=white&label=%20&style=flat-square)     | `>= v12` | **End of Life** | 2021-07-13     | 2022-02-25  |
 | [`v2`](https://github.com/DataDog/dd-trace-js/tree/v2.x) | ![npm v2](https://img.shields.io/npm/v/dd-trace/latest-node12?color=white&label=%20&style=flat-square) | `>= v12` | **End of Life** | 2022-01-28     | 2023-08-15  |
 | [`v3`](https://github.com/DataDog/dd-trace-js/tree/v3.x) | ![npm v3](https://img.shields.io/npm/v/dd-trace/latest-node14?color=white&label=%20&style=flat-square) | `>= v14` | **Maintenance** | 2022-08-15     | 2024-05-15  |
-| [`v4`](https://github.com/DataDog/dd-trace-js/tree/v4.x) | ![npm v4](https://img.shields.io/npm/v/dd-trace/latest?color=white&label=%20&style=flat-square)        | `>= v16` | **Current**     | 2023-05-12     | Unknown     |
+| [`v4`](https://github.com/DataDog/dd-trace-js/tree/v4.x) | ![npm v4](https://img.shields.io/npm/v/dd-trace/latest-node16?color=white&label=%20&style=flat-square)        | `>= v16` | **Maintenance**     | 2023-05-12     | 2025-01-11     |
+| [`v5`](https://github.com/DataDog/dd-trace-js/tree/v5.x) | ![npm v5](https://img.shields.io/npm/v/dd-trace/latest?color=white&label=%20&style=flat-square)        | `>= v18` | **Current**     | 2024-01-11     | Unknown     |
 
-We currently maintain two release lines, namely `v3` and `v4`.
-Features and bug fixes that are merged are released to the `v4` line and, if appropriate, also the `v3` line.
+We currently maintain three release lines, namely `v5`, `v4` and `v3`.
+Features and bug fixes that are merged are released to the `v5` line and, if appropriate, also the `v4` & `v3` line.
 
-For any new projects it is recommended to use the `v4` release line:
+For any new projects it is recommended to use the `v5` release line:
 
 ```sh
 $ npm install dd-trace
 $ yarn add dd-trace
 ```
 
-However, existing projects that already use the `v3` release line, or projects that need to support EOL versions of Node.js, may continue to use these release lines.
+However, existing projects that already use the `v4` & `v3` release line, or projects that need to support EOL versions of Node.js, may continue to use these release lines.
 This is done by specifying the version when installing the package.
 
 ```sh
-$ npm install dd-trace@3
-$ yarn add dd-trace@3
+$ npm install dd-trace@4
+$ yarn add dd-trace@4
 ```
 
 Any backwards-breaking functionality that is introduced into the library will result in an increase of the major version of the library and therefore a new release line.
@@ -60,95 +62,12 @@ For more information about library versioning and compatibility, see the [NodeJS
 Changes associated with each individual release are documented on the [GitHub Releases](https://github.com/DataDog/dd-trace-js/releases) screen.
 
 
-## Development
+## Development and Contribution
 
-Before contributing to this open source project, read our [CONTRIBUTING.md](https://github.com/DataDog/dd-trace-js/blob/master/CONTRIBUTING.md).
+Please read the [CONTRIBUTING.md](https://github.com/DataDog/dd-trace-js/blob/master/CONTRIBUTING.md) document before contributing to this open source project.
 
 
-## Requirements
-
-Since this project supports multiple Node versions, using a version
-manager such as [nvm](https://github.com/creationix/nvm) is recommended.
-
-We use [yarn](https://yarnpkg.com/) for its workspace functionality, so make sure to install that as well.
-
-To install dependencies once you have Node and yarn installed, run:
-
-```sh
-$ yarn
-```
-
-
-## Testing
-
-Before running _plugin_ tests, the data stores need to be running.
-The easiest way to start all of them is to use the provided
-docker-compose configuration:
-
-```sh
-$ docker-compose up -d -V --remove-orphans --force-recreate
-$ yarn services
-```
-
-> **Note**
-> The `couchbase`, `grpc` and `oracledb` instrumentations rely on native modules
-> that do not compile on ARM64 devices (for example M1/M2 Mac) - their tests
-> cannot be run locally on these devices.
-
-### Unit Tests
-
-There are several types of unit tests, for various types of components. The
-following commands may be useful:
-
-```sh
-# Tracer core tests (i.e. testing `packages/dd-trace`)
-$ yarn test:trace:core
-# "Core" library tests (i.e. testing `packages/datadog-core`
-$ yarn test:core
-# Instrumentations tests (i.e. testing `packages/datadog-instrumentations`
-$ yarn test:instrumentations
-```
-
-Several other components have test commands as well. See `package.json` for
-details.
-
-To test _plugins_ (i.e. components in `packages/datadog-plugin-XXXX`
-directories, set the `PLUGINS` environment variable to the plugin you're
-interested in, and use `yarn test:plugins`. If you need to test multiple
-plugins you may separate then with a pipe (`|`) delimiter. Here's an
-example testing the `express` and `bluebird` plugins:
-
-```sh
-PLUGINS="express|bluebird" yarn test:plugins
-```
-
-
-### Memory Leaks
-
-To run the memory leak tests, use:
-
-```sh
-$ yarn leak:core
-
-# or
-
-$ yarn leak:plugins
-```
-
-
-### Linting
-
-We use [ESLint](https://eslint.org) to make sure that new code
-conforms to our coding standards.
-
-To run the linter, use:
-
-```sh
-$ yarn lint
-```
-
-
-### Experimental ESM Support
+## Experimental ESM Support
 
 > **Warning**
 > 
@@ -161,26 +80,18 @@ but code loaded using `import` might not always work.
 
 Use the following command to enable experimental ESM support with your application:
 
+Node.js < v20.6
+
 ```sh
 node --loader dd-trace/loader-hook.mjs entrypoint.js
 ```
 
-
-### Benchmarks
-
-Our microbenchmarks live in `benchmark/sirun`. Each directory in there
-corresponds to a specific benchmark test and its variants, which are used to
-track regressions and improvements over time.
-
-In addition to those, when two or more approaches must be compared, please write
-a benchmark in the `benchmark/index.js` module so that we can keep track of the
-most efficient algorithm. To run your benchmark, use:
+Node.js >= v20.6
 
 ```sh
-$ yarn bench
+node --import dd-trace/register.js entrypoint.js
 ```
 
-
 ## Serverless / Lambda
 
 Note that there is a separate Lambda project, [datadog-lambda-js](https://github.com/DataDog/datadog-lambda-js), that is responsible for enabling metrics and distributed tracing when your application runs on Lambda.
@@ -192,40 +103,9 @@ Regardless of where you open the issue, someone at Datadog will try to help.
 
 ## Bundling
 
-Generally, `dd-trace` works by intercepting `require()` calls that a Node.js application makes when loading modules. This includes modules that are built-in to Node.js, like the `fs` module for accessing the filesystem, as well as modules installed from the npm registry, like the `pg` database module.
-
-Also generally, bundlers work by crawling all of the `require()` calls that an application makes to files on disk, replacing the `require()` calls with custom code, and then concatenating all of the resulting JavaScript into one "bundled" file. When a built-in module is loaded, like `require('fs')`, that call can then remain the same in the resulting bundle.
-
-Fundamentally APM tools like `dd-trace` stop working at this point. Perhaps they continue to intercept the calls for built-in modules but don't intercept calls to third party libraries. This means that by default when you bundle a `dd-trace` app with a bundler it is likely to capture information about disk access (via `fs`) and outbound HTTP requests (via `http`), but will otherwise omit calls to third party libraries (like extracting incoming request route information for the `express` framework or showing which query is run for the `mysql` database client).
-
-To get around this, one can treat all third party modules, or at least third party modules that the APM needs to instrument, as being "external" to the bundler. With this setting the instrumented modules remain on disk and continue to be loaded via `require()` while the non-instrumented modules are bundled. Sadly this results in a build with many extraneous files and starts to defeat the purpose of bundling. 
-
-For these reasons it's necessary to have custom-built bundler plugins. Such plugins are able to instruct the bundler on how to behave, injecting intermediary code and otherwise intercepting the "translated" `require()` calls. The result is that many more packages are then included in the bundled JavaScript file. Some applications can have 100% of modules bundled, however native modules still need to remain external to the bundle.
-
-### Esbuild Support
-
-This library provides experimental esbuild support in the form of an esbuild plugin, and currently requires at least Node.js v16.17 or v18.7. To use the plugin, make sure you have `dd-trace@3+` installed, and then require the `dd-trace/esbuild` module when building your bundle.
-
-Here's an example of how one might use `dd-trace` with esbuild:
-
-```javascript
-const ddPlugin = require('dd-trace/esbuild')
-const esbuild = require('esbuild')
-
-esbuild.build({
-  entryPoints: ['app.js'], 
-  bundle: true,
-  outfile: 'out.js',
-  plugins: [ddPlugin],
-  platform: 'node', // allows built-in modules to be required
-  target: ['node16']
-}).catch((err) => {
-  console.error(err)
-  process.exit(1)
-})
-```
+If you would like to trace your bundled application then please read this page on [bundling and dd-trace](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs/#bundling). It includes information on how to use our ESBuild plugin and includes caveats for other bundlers.
 
 
 ## Security Vulnerabilities
 
-If you have found a security issue, please contact the security team directly at [security@datadoghq.com](mailto:security@datadoghq.com).
+Please refer to the [SECURITY.md](https://github.com/DataDog/dd-trace-js/blob/master/SECURITY.md) document if you have found a security issue.

package/ci/cypress/after-run.js

@@ -0,0 +1 @@
+module.exports = require('../../packages/datadog-plugin-cypress/src/after-run')

package/ci/cypress/after-spec.js

@@ -0,0 +1 @@
+module.exports = require('../../packages/datadog-plugin-cypress/src/after-spec')

package/ci/init.js

@@ -1,15 +1,11 @@
 /* eslint-disable no-console */
 const tracer = require('../packages/dd-trace')
-const { ORIGIN_KEY } = require('../packages/dd-trace/src/constants')
 const { isTrue } = require('../packages/dd-trace/src/util')
 
 const isJestWorker = !!process.env.JEST_WORKER_ID
 
 const options = {
   startupLogs: false,
-  tags: {
-    [ORIGIN_KEY]: 'ciapp-test'
-  },
   isCiVisibility: true,
   flushInterval: isJestWorker ? 0 : 5000
 }
@@ -44,6 +40,7 @@ if (isJestWorker) {
 if (shouldInit) {
   tracer.init(options)
   tracer.use('fs', false)
+  tracer.use('child_process', false)
 }
 
 module.exports = tracer

package/ext/kinds.d.ts

@@ -3,6 +3,7 @@ declare const kinds: {
   CLIENT: 'client'
   PRODUCER: 'producer'
   CONSUMER: 'consumer'
+  INTERNAL: 'internal'
 }
 
 export = kinds

package/ext/kinds.js

@@ -4,5 +4,6 @@ module.exports = {
   SERVER: 'server',
   CLIENT: 'client',
   PRODUCER: 'producer',
-  CONSUMER: 'consumer'
+  CONSUMER: 'consumer',
+  INTERNAL: 'internal'
 }

package/ext/tags.d.ts

@@ -17,7 +17,8 @@ declare const tags: {
   HTTP_REQUEST_HEADERS: 'http.request.headers'
   HTTP_RESPONSE_HEADERS: 'http.response.headers'
   HTTP_USERAGENT: 'http.useragent',
-  HTTP_CLIENT_IP: 'http.client_ip'
+  HTTP_CLIENT_IP: 'http.client_ip',
+  PATHWAY_HASH: 'pathway.hash'
 }
 
 export = tags

package/ext/tags.js

@@ -22,7 +22,12 @@ const tags = {
   HTTP_REQUEST_HEADERS: 'http.request.headers',
   HTTP_RESPONSE_HEADERS: 'http.response.headers',
   HTTP_USERAGENT: 'http.useragent',
-  HTTP_CLIENT_IP: 'http.client_ip'
+  HTTP_CLIENT_IP: 'http.client_ip',
+
+  // Messaging
+
+  // DSM Specific
+  PATHWAY_HASH: 'pathway.hash'
 }
 
 // Deprecated