Merge remote-tracking branch 'upstream/master' into feature/windows-b…

…uild

.ci/Jenkinsfile

@@ -254,18 +254,15 @@ pipeline {
       agent none
       when {
         beforeAgent true
-        allOf {
-          anyOf {
-            environment name: 'GIT_BUILD_CAUSE', value: 'pr'
-            expression { return !params.Run_As_Master_Branch }
-          }
+        anyOf {
+          changeRequest()
+          expression { return !params.Run_As_Master_Branch }
         }
       }
       steps {
-        log(level: 'INFO', text: 'Launching Async ITs')
         build(job: env.ITS_PIPELINE, propagate: false, wait: false,
-              parameters: [string(name: 'AGENT_INTEGRATION_TEST', value: 'Node.js'),
-                           string(name: 'BUILD_OPTS', value: "--nodejs-agent-package ${env.CHANGE_FORK?.trim() ?: 'elastic' }/${env.REPO}#${env.GIT_BASE_COMMIT}"),
+              parameters: [string(name: 'INTEGRATION_TEST', value: 'Node.js'),
+                           string(name: 'BUILD_OPTS', value: "--nodejs-agent-package ${env.CHANGE_FORK?.trim() ?: 'elastic' }/${env.REPO}#${env.GIT_BASE_COMMIT} --opbeans-node-agent-branch ${env.GIT_BASE_COMMIT}"),
                            string(name: 'GITHUB_CHECK_NAME', value: env.GITHUB_CHECK_ITS_NAME),
                            string(name: 'GITHUB_CHECK_REPO', value: env.REPO),
                            string(name: 'GITHUB_CHECK_SHA1', value: env.GIT_BASE_COMMIT)])
@@ -439,7 +436,7 @@ def getSmartTAVContext() {
         withGithubNotify(context: 'Linting') {
           deleteDir()
           unstash 'source'
-          docker.image('node:12').inside("-v ${WORKSPACE}/${BASE_DIR}:/app"){
+          docker.image('node:12').inside("-v ${WORKSPACE}/${BASE_DIR}:/app -v /var/lib/jenkins/.git-references/:/var/lib/jenkins/.git-references"){
             withEnv(["HOME=/app"]) {
               sh(label: 'Basic tests I', script: 'cd /app && .ci/scripts/test_basic.sh')
               sh(label: 'Basic tests II', script: 'cd /app && .ci/scripts/test_types_babel_esm.sh')

.ci/docker/docker-compose.yml

@@ -11,6 +11,7 @@ services:
     environment:
       POSTGRES_USER: 'postgres'
       POSTGRES_DB: 'test_elastic_apm'
+      POSTGRES_HOST_AUTH_METHOD: 'trust'
     healthcheck:
       test: ["CMD", "pg_isready"]
       interval: 1s
@@ -101,7 +102,7 @@ services:
       interval: 30s
       timeout: 10s
       retries: 5
-  
+
   memcached:
     image: memcached:alpine
     user: "11211"

.ci/jobs/apm-agent-nodejs-downstream.yml

@@ -32,6 +32,7 @@
           recursive: true
           parent-credentials: true
           timeout: 100
+          reference-repo: /var/lib/jenkins/.git-references/apm-agent-nodejs.git
         timeout: '15'
         use-author: true
         wipe-workspace: 'True'

.ci/jobs/apm-agent-nodejs-linting-mbp.yml

@@ -33,6 +33,7 @@
           recursive: true
           parent-credentials: true
           timeout: 100
+          reference-repo: /var/lib/jenkins/.git-references/apm-agent-nodejs.git
         timeout: '15'
         use-author: true
         wipe-workspace: 'True'

.ci/jobs/apm-agent-nodejs-mbp.yml

@@ -37,6 +37,7 @@
           recursive: true
           parent-credentials: true
           timeout: 100
+          reference-repo: /var/lib/jenkins/.git-references/apm-agent-nodejs.git
         timeout: '15'
         use-author: true
         wipe-workspace: 'True'

.ci/packer_cache.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+source /usr/local/bin/bash_standard_lib.sh
+
+grep "-" .ci/.jenkins_nodejs.yml | cut -d'-' -f2- | \
+while read -r version;
+do
+    transformedVersion=$(echo "${version}" | sed 's#"##g' | cut -d":" -f2)
+    imageName="apm-agent-nodejs"
+    registryImageName="docker.elastic.co/observability-ci/${imageName}:${transformedVersion}"
+    (retry 2 docker pull "${registryImageName}")
+    docker tag "${registryImageName}" "node:${transformedVersion}"
+done
+
+docker-compose \
+  --no-ansi \
+  --log-level ERROR \
+  -f .ci/docker/docker-compose-all.yml \
+  pull --quiet --ignore-pull-failures

.ci/scripts/test.sh

@@ -44,6 +44,26 @@ if [ "${IS_EDGE}" = "true" ]; then
   DOCKER_COMPOSE_FILE=docker-compose-edge.yml
 fi
 
+set +e
+NVM_NODEJS_ORG_MIRROR=${NVM_NODEJS_ORG_MIRROR} \
+ELASTIC_APM_ASYNC_HOOKS=${ELASTIC_APM_ASYNC_HOOKS} \
+NODE_VERSION=${NODE_VERSION} \
+TAV_VERSIONS=${TAV_VERSIONS} \
+USER_ID="$(id -u):$(id -g)" \
+docker-compose \
+  --no-ansi \
+  --log-level ERROR \
+  -f ${DOCKER_FOLDER}/${DOCKER_COMPOSE_FILE} \
+  build >docker-compose.log 2>docker-compose.err
+
+if [ $? -gt 0 ] ; then
+  echo "Docker compose failed, see the below log output"
+  cat docker-compose.log && rm docker-compose.log
+  cat docker-compose.err && rm docker-compose.err
+  exit 1
+fi
+
+set -e
 NVM_NODEJS_ORG_MIRROR=${NVM_NODEJS_ORG_MIRROR} \
 ELASTIC_APM_ASYNC_HOOKS=${ELASTIC_APM_ASYNC_HOOKS} \
 NODE_VERSION=${NODE_VERSION} \
@@ -55,10 +75,10 @@ docker-compose \
   -f ${DOCKER_FOLDER}/${DOCKER_COMPOSE_FILE} \
   up \
   --exit-code-from node_tests \
-  --build \
   --remove-orphans \
   --abort-on-container-exit \
   node_tests
+
 NODE_VERSION=${NODE_VERSION} docker-compose \
   --no-ansi \
   --log-level ERROR \

.ci/scripts/test_types_babel_esm.sh

@@ -7,6 +7,13 @@ npm install
 node --version
 npm --version
 
+major_node_version=`node --version | cut -d . -f1 | cut -d v -f2`
+minor_node_version=`node --version | cut -d . -f2`
+
 npm run test:types
-npm run test:babel
+
+if [[ $major_node_version -ne 13 ]] || [[ $minor_node_version -gt 1 ]]; then
+  npm run test:babel
+fi
+
 npm run test:esm

.tav.yml

@@ -4,16 +4,21 @@ generic-pool:
 mimic-response:
   versions: ^1.0.0
   commands: node test/instrumentation/modules/mimic-response.js
-got-old:
+got-very-old:
   name: got
   versions: '>=4.0.0 <9.0.0'
   node: '>=5'
   commands: node test/instrumentation/modules/http/github-423.js
-got-new:
+got-old:
   name: got
-  versions: '>=9.0.0'
+  versions: ^9.0.0
   node: '>=8.3'
   commands: node test/instrumentation/modules/http/github-423.js
+got-new:
+  name: got
+  versions: '>=10.0.0 <10.5.1 || >10.5.1' # v10.5.1 is broken
+  node: '>=10'
+  commands: node test/instrumentation/modules/http/github-423.js
 mysql:
   versions: ^2.0.0
   commands:
@@ -209,7 +214,7 @@ express-queue:
 koa-router:
   node: '>=6.0.0'
   peerDependencies: koa@2
-  versions: '>=5.2.0 <8'
+  versions: '>=5.2.0 <9'
   commands: node test/instrumentation/modules/koa-router/old-name.js
 '@koa/router':
   node: '>=8.0.0'
@@ -242,9 +247,17 @@ hapi-async-await:
   commands:
     - node test/instrumentation/modules/hapi/basic-legacy-path.js
     - node test/instrumentation/modules/hapi/set-framework.js
-'@hapi/hapi':
+'@hapi/hapi-old':
+  name: '@hapi/hapi'
   node: '>=8.2'
-  versions: '>=17.0.0'
+  versions: '>=17.0.0 <19.0.0'
+  commands:
+    - node test/instrumentation/modules/hapi/basic.js
+    - node test/instrumentation/modules/hapi/set-framework-2.js
+'@hapi/hapi-new':
+  name: '@hapi/hapi'
+  node: '>=12'
+  versions: '>=19.0.0'
   commands:
     - node test/instrumentation/modules/hapi/basic.js
     - node test/instrumentation/modules/hapi/set-framework-2.js

CHANGELOG.asciidoc

@@ -21,6 +21,15 @@ endif::[]
 [[release-notes-3.x]]
 === Node.js Agent version 3.x
 
+[[release-notes-3.4.0]]
+==== 3.4.0 - 2020/2/21
+
+* feat: support W3C TraceContext traceparent header {pull}1587[#1587])
+* feat: add custom metrics API (experimental) {pull}1571[#1571])
+* feat(koa-router): add support for v8.x {pull}1642[#1642])
+* fix(cassandra): improve support for cassandra-driver v4.4.0+ {pull}1636[#1636])
+* fix: support promisifying setTimeout and friends {pull}1636[#1636])
+
 [[release-notes-3.3.0]]
 ==== 3.3.0 - 2019/12/13
 
@@ -65,13 +74,34 @@ endif::[]
 [[release-notes-2.x]]
 === Node.js Agent version 2.x
 
+[[release-notes-2.17.3]]
+==== 2.17.3 - 2020/2/27
+
+[float]
+===== Bug fixes
+* fix: support promisifying setTimeout and friends {pull}1649[#1649]
+* fix(cassandra): improve support for cassandra-driver v4.4.0+ {pull}1649[#1649]
+* fix(knex): make stack traces work in 0.18+ {pull}1500[#1500]
+* fix(tedious): ensure shimmed module exposes same API {pull}1496[#1496]
+* fix(metrics): do not send transaction breakdowns when disabled {pull}1489[#1489]
+* fix(tedious): support 6.5+ {pull}1488[#1488]
+* fix: always end transaction when socket is closed prematurely {pull}1445[#1445]
+* perf: cache 'ids' value of transactions and spans {pull}1438[#1438]
+
+[[release-notes-2.17.2]]
+==== 2.17.2 - 2019/10/2
+
+[float]
+===== Bug fixes
+* chore(http): workaround(s) to suppress DEP0066 warnings {pull}1424[#1424]
+
 [[release-notes-2.17.1]]
 ==== 2.17.1 - 2019/9/26
 
 [float]
 ===== Bug fixes
-* fix: support all falsy return values from error filters {pull}1389[#1389]
-* fix: capture all non-string http bodies {pull}1376[#1376]
+* fix: support all falsy return values from error filters {pull}1394[#1394]
+* fix: capture all non-string http bodies {pull}1381[#1381]
 
 [[release-notes-2.17.0]]
 ==== 2.17.0 - 2019/9/19

CONTRIBUTING.md

@@ -163,6 +163,7 @@ If you have access to make releases, the process is as follows:
 1. Be sure you have checked out the `master` branch and have pulled latest changes
 1. Update the version in `package.json` according to the scale of the change. (major, minor or patch)
 1. Add commit messages to `CHANGELOG.asciidoc` (You may skip non-user-visible changes)
+1. If a major or minor release, update the EOL table in `docs/upgrading.asciidoc`. EOL is 18 months after release date.
 1. Commit changes with message `x.y.z` where `x.y.z` is the version in `package.json`
 1. Tag the commit with `git tag vx.y.x`, for example `git tag v1.2.3`
 1. Reset the latest major branch (`1.x`, `2.x` etc) to point to the current master, e.g. `git branch -f 3.x master`
@@ -180,5 +181,5 @@ If you have access to make releases, the process is as follows:
 1. Tag the commit with `git tag vx.y.x`, for example `git tag v1.2.3`
 1. Run tests with `npm test`
 1. Push commits and tags upstream with `git push upstream <major_branch> && git push upstream --tags` (and optionally to your own fork as well)
-1. Publish to npm with `npm publish --tag v2` (where `v2` is the tag for the past major version being published)
+1. Publish to npm with `npm publish --tag=2x` (where `2x` is the tag for the past major version being published)
 1. Make a PR against `master` containing the updates to `CHANGELOG.asciidoc` so that `master` always contain information about all releases

LICENSE

@@ -2,7 +2,7 @@ BSD 2-Clause License
 
 Copyright (c) 2012, Matt Robenolt
 Copyright (c) 2013-2014, Thomas Watson Steen and Elasticsearch BV
-Copyright (c) 2015-2018, Elasticsearch BV
+Copyright (c) 2015-2020, Elasticsearch BV
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

docs/distributed-tracing.asciidoc

@@ -0,0 +1,94 @@
+[[distributed-tracing]]
+== Distributed tracing
+
+// Content from APM Overview documentation
+// https://www.elastic.co/guide/en/apm/get-started/current/distributed-tracing.html
+Distributed tracing enables you to analyze performance throughout your microservices architecture all in one view.
+This is accomplished by tracing all of the requests --
+from the initial web request to your front-end service -- to queries made to your back-end services.
+This makes finding possible bottlenecks throughout your application much easier and faster.
+
+Elastic APM automatically supports distributed tracing,
+but there are some cases, outlined below, where additional setup is necessary.
+
+[float]
+[[tracing-rum-correlation]]
+=== Real User Monitoring (RUM) correlation
+
+// Content from RUM documentation
+// https://www.elastic.co/guide/en/apm/agent/rum-js/master/distributed-tracing-guide.html
+If your backend service generates an HTML page dynamically,
+the trace ID and parent span ID must be injected into the page when the RUM Agent is initialized.
+This ensures that the web browser’s page load appears as the root of the trace,
+and allows you to analyze the time spent in the browser vs in backend services.
+
+// Content from transaction-api.asciidoc
+include::./transaction-api.asciidoc[tag=ensure-parent-id-snippet]
+
+For more information, see <<transaction-ensure-parent-id>>.
+
+[float]
+[[tracing-custom-protocol]]
+=== Custom protocols
+
+Distributed tracing is automatically supported with HTTP/HTTPS.
+If you're using another protocol, like TCP, UDP, WebSocket, or Protocol Buffers,
+there are a few manual setup steps you must follow.
+
+In a distributed trace, multiple transactions are linked together with a `traceparent`.
+To create your own distributed trace, you must pass the current `traceparent` from an outgoing service,
+to a receiving service, and create a new transaction as a child of that `traceparent`:
+
+1. In one service, start a transaction with <<apm-start-transaction,`apm.startTransaction()`>>,
+or a span with <<apm-start-span,`apm.startSpan()`>>.
+
+2. Get the serialized `traceparent` string of the started transaction/span with <<apm-current-traceparent>>.
+
+3. Encode the `traceparent` and send it to the receiving service inside your regular request.
+
+4. Decode and store the `traceparent` in the receiving service.
+
+5. Manually start a new transaction as a child of the received `traceparent`,
+with <<apm-start-transaction,`apm.startTransaction()`>>.
+Pass in the `traceparent` as the `childOf` option.
+
+[float]
+[[tracing-custom-example]]
+==== Example
+
+Consider a scenario where you're using raw UDP to communicate between two services, A and B:
+
+**Service A**
+
+Service A starts a transaction, and gets the current `traceparent`.
+
+[source,js]
+----
+agent.startTransaction('my-service-a-transaction')
+const traceparent = agent.currentTraceparent
+----
+
+Service A then sends the `traceparent` as a "header" to service B.
+
+[source,js]
+----
+// Pseudocode for sending data
+sendMetadata(`traceparent: ${traceparent}\n`)
+----
+
+**Service B**
+
+Service B reads the `traceparent` from the incoming request.
+
+[source,js]
+----
+// Pseudocode for reading incoming request
+const traceparent = readTraceparentFromUDPPacket()
+----
+
+Service B uses the `traceparent` to initialize a new transaction that is a child of the original `traceparent`.
+
+[source,js]
+----
+agent.startTransaction('my-service-b-transaction', { childOf: traceparent })
+----

docs/index.asciidoc

@@ -37,6 +37,8 @@ include::./log-correlation.asciidoc[]
 
 include::./source-maps.asciidoc[]
 
+include::./distributed-tracing.asciidoc[]
+
 include::./performance-tuning.asciidoc[]
 
 include::./troubleshooting.asciidoc[]

docs/supported-technologies.asciidoc

@@ -40,7 +40,7 @@ These are the frameworks that we officially support:
 |Framework |Version
 |<<express,Express>> |^4.0.0
 |<<hapi,hapi>> |>=9.0.0 <19.0.0
-|<<hapi,@hapi/hapi>> |>=17.9.0 <19.0.0
+|<<hapi,@hapi/hapi>> |>=17.9.0 <20.0.0
 |<<koa,Koa>> via koa-router or @koa/router |>=5.2.0 <9.0.0
 2+|Koa doesn't have a built in router, so we can't support Koa directly since we rely on
 router information for full support. We currently support the most popular Koa router called