4.x (#3528)

feat!: the start of v4.x Significant and breaking changes: - Min supported Node.js is now 14.5.0 (up from 8.6). - Drop support for the obsolete "patch" context manager, i.e. the `contextManager: "patch"` config option. This was a limited async context management that predated the preferred `AsyncLocalStorage` core Node.js mechanism for context tracking. (#3529) - Config vars: - Remove `logUncaughtExceptions` config option, if the agent's `uncaughtException` handler is active it now *always* logs the error to the console. (#2412) - Remove `filterHttpHeaders` config option, see `sanitizeFieldNames` instead. (#3332) - Remove long deprecate `ELASTIC_APM_KUBERNETES_*` envvars, use `KUBERNETES_*` instead. (#2661) - The `useElasticTraceparentHeader` config option now defaults to `false`. This means the `elastic-apm-traceparent` HTTP header is now no longer sent by default. (#3555) - Drop erroneous `ELASTIC_SANITIZE_FIELD_NAMES` and `ELASTIC_IGNORE_MESSAGE_QUEUES` config envvars. - Instrumentations: - Drop instrumentation for old `hapi`, the current `@hapi/hapi` is still instrumented. (#2691) - APIs: - Ignore a `timer` option passed to `startTransaction()` and `startSpan()` APIs. (#2990) - Remove the deprecated `span.toString()` and `transaction.toString()` APIs. (#2348) - Change `apm.startTransaction()` API to return a noop transaction instead of null when the agent is not started. (#2429) - Remove `transaction.subtype` and `transaction.action` properties from the API. This also impacts <<apm-start-transaction>> and `transaction.setType(...)`, both of which now no longer accept `subtype` and `action` parameters. (#3557)
elastic · Sep 1, 2023 · c6cdaf9 · c6cdaf9
1 parent 7f8fd48
commit c6cdaf9
Show file tree

Hide file tree

Showing 102 changed files with 1,707 additions and 2,561 deletions.
diff --git a/.ci/Makefile b/.ci/Makefile
@@ -71,7 +71,7 @@ publish: validate-layer-name validate-aws-default-region
 		--layer-name "$(ELASTIC_LAYER_NAME)" \
 		--description "AWS Lambda Extension Layer for the Elastic APM Node.js Agent" \
 		--license "Apache-2.0" \
-		--compatible-runtimes nodejs18.x nodejs16.x nodejs14.x nodejs12.x nodejs10.x \
+		--compatible-runtimes nodejs18.x nodejs16.x nodejs14.x \
 		--zip-file "fileb://./$(AWS_FOLDER)/elastic-apm-node-lambda-layer-$(GITHUB_REF_NAME).zip"
 
 # Grant public access to the given LAYER in the given AWS region
@@ -98,9 +98,8 @@ create-arn-file: validate-release-notes-url
 
 github-release: validate-ref-name
 	@gh release list
-	@gh \
-		release \
-		create $(GITHUB_REF_NAME) \
+	@gh release create $(GITHUB_REF_NAME) \
+		--latest \
 		--title '$(GITHUB_REF_NAME)' \
 		--notes-file $(AWS_FOLDER)/$(SUFFIX_ARN_FILE)
 

diff --git a/.ci/scripts/docker-test.sh b/.ci/scripts/docker-test.sh
@@ -1,22 +1,10 @@
 #!/usr/bin/env bash
 set -ueo pipefail
 
-major_node_version=`node --version | cut -d . -f1 | cut -d v -f2`
-minor_node_version=`node --version | cut -d . -f2`
-
-if [[ $major_node_version -eq 8 ]] && [[ $minor_node_version -lt 8 ]]; then
-  export NODE_OPTIONS="${NODE_OPTIONS:+${NODE_OPTIONS}} --expose-http2"
-fi
-
 # "test/instrumentation/modules/http2.js" fails if the OpenSSL SECLEVEL=2,
 # which is the case in the node:16 Docker image and could be in other
 # environments. Here we explicitly set it to SECLEVEL=0 for testing.
-#
-# Skip for node v8 because it results in this warning:
-#   openssl config failed: error:25066067:DSO support routines:DLFCN_LOAD:could not load the shared library
-if [[ $major_node_version -gt 8 ]]; then
-  export NODE_OPTIONS="${NODE_OPTIONS:+${NODE_OPTIONS}} --openssl-config=$(pwd)/test/openssl-config-for-testing.cnf"
-fi
+export NODE_OPTIONS="${NODE_OPTIONS:+${NODE_OPTIONS}} --openssl-config=$(pwd)/test/openssl-config-for-testing.cnf"
 
 # Workaround to git <2.7
 # error fatal: unable to look up current user in the passwd file: no such user
@@ -27,16 +15,16 @@ if [ -z "$(grep \"\:$(id -u)\:\" /etc/passwd)" ]; then
   git config -l
 fi
 
-npm_install() {
+npm_ci() {
   local retries=2
   local count=0
 
-  until npm install --no-save; do
+  until npm ci; do
     exit=$?
     wait=$((2 ** $count))
     count=$(($count + 1))
     if [ $count -lt $retries ]; then
-      printf "Retry of 'npm install' %s/%s exited %s, retrying in %s seconds...\n" "$count" "$retries" "$exit" "$wait" >&2
+      printf "Retry of 'npm ci' %s/%s exited %s, retrying in %s seconds...\n" "$count" "$retries" "$exit" "$wait" >&2
       printf "Force-cleaning of npm cache.\n" >&2
       npm cache clean --force
       sleep $wait
@@ -52,7 +40,7 @@ export
 id
 node --version
 npm --version
-npm_install
+npm_ci
 
 # Attempt to provide junit-formatted test results, for Jenkins' "Test Results"
 # and other features like flaky-test reporting.

diff --git a/.ci/scripts/prepare-benchmarks-env.sh b/.ci/scripts/prepare-benchmarks-env.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 
 # Install the given node version, put it on the PATH (hence requiring "source"
-# to use this) and `npm install`.
+# to use this) and `npm ci`.
 #
 # Usage:
 #   NODE_VERSION=...
@@ -44,4 +44,4 @@ npm --version
 echo "--- Install dependencies"
 set -x
 npm config list
-npm install
+npm ci
diff --git a/.ci/tav.json b/.ci/tav.json
@@ -1,5 +1,5 @@
 {
-  "versions": [ 20, 18, 16, 14, 12, 10, 8 ],
+  "versions": [ 20, 18, 16, 14 ],
   "// modules": [
     "List of instrumented modules with the min Node version supported.",
     "minVersion for each module should be kept in sync with .tav.yml"

diff --git a/.github/workflows/edge.yml b/.github/workflows/edge.yml
@@ -38,12 +38,9 @@ jobs:
       fail-fast: false
       matrix:
         node: [ "21" ]
-        contextManager: [ 'patch', '' ]
     steps:
       - uses: actions/checkout@v3
       - run: .ci/scripts/test.sh -b "nightly" "${{ matrix.node }}"
-        env:
-          ELASTIC_APM_CONTEXT_MANAGER: ${{ matrix.contextManager }}
 
   # This should list all the Node.js major versions listed at
   # https://nodejs.org/en/about/releases/, plus the next version (for which
@@ -62,10 +59,8 @@ jobs:
           - "20"
           - "18"
           - "16"
-        contextManager: [ 'patch', '' ]
     steps:
       - uses: actions/checkout@v3
       - run: .ci/scripts/test.sh -b "rc" "${{ matrix.node }}"
         env:
           VERSION: ${{ matrix.node }}
-          ELASTIC_APM_CONTEXT_MANAGER: ${{ matrix.contextManager }}
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -19,7 +19,7 @@ jobs:
 
       - uses: actions/setup-node@v3
         with:
-          node-version: 'v16.15.1'
+          node-version: 'v16.20.2'
 
       - uses: elastic/apm-pipeline-library/.github/actions/docker-login@current
         with:
@@ -69,7 +69,7 @@ jobs:
       - name: npm publish
         run: |-
           echo "//registry.npmjs.org/:_authToken=${{ env.NPMJS_TOKEN }}" > .npmrc
-          npm publish --otp=${{ env.TOTP_CODE }}
+          npm publish --tag=latest --otp=${{ env.TOTP_CODE }}
 
       - if: always()
         uses: elastic/apm-pipeline-library/.github/actions/notify-build-status@current

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -6,6 +6,7 @@ on:
   push:
     branches:
     - main
+    - 3.x
     paths-ignore:
     - '**/*.md'
     - '**/*.asciidoc'
@@ -14,6 +15,7 @@ on:
   pull_request:
     branches:
     - main
+    - 3.x
     paths-ignore:
     - '**/*.md'
     - '**/*.asciidoc'
@@ -35,7 +37,7 @@ jobs:
       - uses: actions/setup-node@v3
         with:
           node-version: 16
-      - run: npm install
+      - run: npm ci
       - run: npm run lint
 
   test-vers:
@@ -127,32 +129,24 @@ jobs:
       matrix:
         node:
           - '20'
+          - '20.0'
           - '18'
           - '18.0'
           - '16'
           - '16.0'
           - '14'
           - '14.0'
-          - '12'
-          - '12.0'
-          - '10'
-          - '10.0'
-          - '8'
-          - '8.6'
-        contextManager: [ 'patch', '' ]
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
     - uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node }}
     - run: docker ps  # show the services against which we'll be testing
-    - run: npm install
+    - run: npm ci
     - run: npm ls --all || true
     - name: npm test
       run: npm test
-      env:
-        ELASTIC_APM_CONTEXT_MANAGER: ${{ matrix.contextManager }}
     - uses: inception-health/otel-upload-test-artifact-action@v1
       if: always()
       continue-on-error: true
@@ -174,7 +168,7 @@ jobs:
         # which version more of our users are using.
         node-version: 16
         cache: 'npm'
-    - run: npm install
+    - run: npm ci
     - run: npm ls --all || true
     # Run a subset of tests that we can reasonably get running on Windows CI.
     - run: node test/test.js

diff --git a/.nvmrc b/.nvmrc
@@ -1 +1 @@
-16.20.1
+16.20.2
diff --git a/.tav.yml b/.tav.yml
@@ -335,8 +335,8 @@ pug:
 
 # @hapi/hapi
 # - Package name: Starting with v17.9.0 and v18.2.0 the name changed from
-#   'hapi' to '@hapi/hapi'. Instrumentation for the old 'hapi' is now deprecated
-#   and untested; it will be dropped in the next major version of the agent.
+#   'hapi' to '@hapi/hapi'. Starting in elastic-apm-node@4, only the newer
+#   '@hapi/hapi' is instrumented.
 # - Node version compat:
 #   - @hapi/hapi@19: supports node >=v12 (judging from commit 50d8d7d)
 #   - @hapi/hapi@20: appears (from travis template refs) to support node >=v12
@@ -350,29 +350,29 @@ pug:
   versions: '>=17.0.0 <19.0.0'
   node: '>=8.12.0 <16.0.0'
   commands:
-    - node test/instrumentation/modules/hapi/basic.test.js
-    - node test/instrumentation/modules/hapi/set-framework-hapihapi.test.js
+    - node test/instrumentation/modules/hapi/hapi.test.js
+    - node test/instrumentation/modules/hapi/set-framework.test.js
 '@hapi/hapi-v19-v20.1.2':
   name: '@hapi/hapi'
   versions: '>=19.0.0 <20.1.2'
   node: '>=12.0.0 <16.0.0'
   commands:
-    - node test/instrumentation/modules/hapi/basic.test.js
-    - node test/instrumentation/modules/hapi/set-framework-hapihapi.test.js
+    - node test/instrumentation/modules/hapi/hapi.test.js
+    - node test/instrumentation/modules/hapi/set-framework.test.js
 '@hapi/hapi-v20.1.2-v21':
   name: '@hapi/hapi'
   versions: '>=20.1.2 <21.0.0'
   node: '>=12.0.0'
   commands:
-    - node test/instrumentation/modules/hapi/basic.test.js
-    - node test/instrumentation/modules/hapi/set-framework-hapihapi.test.js
+    - node test/instrumentation/modules/hapi/hapi.test.js
+    - node test/instrumentation/modules/hapi/set-framework.test.js
 '@hapi/hapi-v21-':
   name: '@hapi/hapi'
   versions: '>=21.0.0'
   node: '>=14.10.0'
   commands:
-    - node test/instrumentation/modules/hapi/basic.test.js
-    - node test/instrumentation/modules/hapi/set-framework-hapihapi.test.js
+    - node test/instrumentation/modules/hapi/hapi.test.js
+    - node test/instrumentation/modules/hapi/set-framework.test.js
 
 tedious-v1-v11:
   name: tedious

diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc
@@ -28,15 +28,70 @@ Notes:
         ==== x.x.x - YYYY/MM/DD
 ////
 
-[[release-notes-3.x]]
-=== Node.js Agent version 3.x
+[[release-notes-4.x]]
+=== Node.js Agent version 4.x
+
+See the <<upgrade-to-v4>> guide.
+
+==== Unreleased
 
 [float]
 ===== Breaking changes
 
+* Set the new minimum supported Node.js to version 14.5.0.
+  Users of earlier Node.js versions can use elastic-apm-node v3.x, which
+  supports back to Node.js v8.6.
+
+* Ignore a `timer` option passed to `startTransaction()` and `startSpan()` APIs.
+  This option was never documented. It would be surprising if any user is
+  impacted by this.
+
+* Remove long deprecated support for the `ELASTIC_APM_`-prefixed environment
+  variables for the <<kubernetes-node-name,Kubernetes config options>>. For
+  example, one must use `KUBERNETES_POD_NAME` and not
+  `ELASTIC_APM_KUBERNETES_POD_NAME`. ({issues}2661[#2661])
+
+* The config option `filterHttpHeaders` is now _removed_. ({pull}3539[#3539])
+
+* Remove the deprecated `span.toString()` and `transaction.toString()` APIs.
+  See <<v4-api-to-string,the upgrading doc>> for details. ({issues}2348[#2348])
+
+* Remove instrumentation support for the old 'hapi' package -- the current
+  '@hapi/hapi' package is still instrumented. ({issues}2691[#2691])
+
+* Change `apm.startTransaction()` api to return a noop transaction instead of
+  null, if the agent is not yet started. ({issues}2429[#2429])
+
+* Drop support for the obsolete "patch" context manager, i.e. the
+  `contextManager: "patch"` config option. This was a limited async context
+  management that predated the preferred `AsyncLocalStorage` core Node.js
+  mechanism for context tracking. It was deprecated in v3.37.0.  As well, the
+  related and deprecated `asyncHooks` config option has been removed.
+  ({issues}3529[#3529])
+
+* Remove the `logUncaughtExceptions` config option.
+  See <<v4-config-options,Upgrading to v4>> for details.
+  ({issues}2412[#2412])
+
+* Remove `transaction.subtype` and `transaction.action` properties from API.
+  This also impacts <<apm-start-transaction>> and `transaction.setType(...)`,
+  both of which now no longer accept `subtype` and `action` parameters.
+  These two properties were deprecated in v3.25.0.
+  ({issues}3557[#3557])
+
+* Remove support for the erroneous `ELASTIC_SANITIZE_FIELD_NAMES` and
+  `ELASTIC_IGNORE_MESSAGE_QUEUES` config environment variables. The correct env
+  vars are `ELASTIC_APM_SANITIZE_FIELD_NAMES` and
+  `ELASTIC_APM_IGNORE_MESSAGE_QUEUES`, respectively, and were supported starting
+  in v3.36.0.
+
 [float]
 ===== Features
 
+* The `apm.destroy()` method is now async. Almost no users should need to use
+  this method. However, if used, to be sure to wait for APM agent shutdown to
+  be complete, one can now `await apm.destroy()`. ({issues}3222[#3222])
+
 * Support instrumenting `mongodb` v6. ({pull}3596[#3596])
 
 [float]
@@ -49,10 +104,25 @@ Notes:
 [float]
 ===== Chores
 
+* Add a warning message when a duration or size config option is provided
+  without units. ({issues}2121[#2121])
+
+* Change default value of `useElasticTraceparentHeader` config option to `false`.
+  This means that for outgoing HTTP requests, the APM agent will no longer add the
+  `elastic-apm-traceparent` header. This vendor-specific header was used in the past
+  while the https://w3c.github.io/trace-context/[W3C trace-context] spec was still
+  in development. Now that it is in wide use, the `elastic-apm-traceparent` header is
+  only useful for interaction with very old Elastic APM agents.
+
 * Add default ports into `context.service.target.name` for HTTP spans conforming to the
   spec update done in https://github.com/elastic/apm/pull/700 ({pull}3590[#3590])
 
 
+[[release-notes-3.x]]
+=== Node.js Agent version 3.x
+
+// To see the changelog for later 3.x release, see the "3.x" branch: <https://github.com/elastic/apm-agent-nodejs/blob/3.x/CHANGELOG.asciidoc>
+
 [[release-notes-3.49.1]]
 ==== 3.49.1 - 2023/08/09
 
@@ -236,7 +306,7 @@ in a Worker will *not* start the APM agent. Instead, one must use:
 [float]
 ===== Chores
 
-* The config option <<filter-http-headers, filterHttpHeaders>> is now *deprecated*. It will be
+* The config option `filterHttpHeaders` is now *deprecated*. It will be
   removed in a future major version. ({pull}3333[#3333])
 
 * Add cookie map in transactions' request context and redact cookie header ({pull}3322[#3322])
@@ -617,7 +687,7 @@ paths are considered for request body capture. ({pull}2873[#2873])
 +
 This also adds a new <<context-manager,`contextManager`>> configuration option
 to control which mechanism the agent uses for run-context tracking. It replaces
-the, now deprecated, <<async-hooks,`asyncHooks`>> configuration option. If
+the, now deprecated, `asyncHooks` configuration option. If
 you experience problems with the new AsyncLocalStorage-based tracking, you can
 restore the older behavior with `contextManager: "asynchooks"`.
 
@@ -1254,9 +1324,8 @@ added to multiple events.
   of (re)implementing Lambda support ({pull}2363[#2363]). Some fixes for better
   flushing of data at the end of a Lambda invocation.
 
-* <<span-to-string,`span.toString()`>> and <<transaction-to-string,`transaction.toString()`>>
-  have been *deprecated*. The exact string output may change in v4 of the
-  agent.
+* `span.toString()` and `transaction.toString()` have been *deprecated*. The
+  exact string output may change in v4 of the agent.
 
 * Add `Span.ids` and `Transaction.ids` to TypeScript types. ({pull}2347[#2347])