feat: add 'apmClientHeaders' config option for custom headers in APM server comms (#3760)

Closes: #3759

Author: trentm

CHANGELOG.asciidoc

@@ -41,6 +41,9 @@ See the <<upgrade-to-v4>> guide.
 [float]
 ===== Features
 
+* Add the <<apm-client-headers>> config option, to allow adding custom headers
+  to HTTP requests made to APM server by the APM agent. ({issues}3759[#3759])
+
 [float]
 ===== Bug fixes
 

docs/configuration.asciidoc

@@ -942,6 +942,32 @@ option. That will likely result in healthy requests being aborted prematurely.
 The value should include a time suffix ('m' for minutes, 's' for seconds, or
 'ms' for milliseconds), but defaults to seconds if no suffix is given.
 
+[[apm-client-headers]]
+==== `apmClientHeaders`
+
+[small]#Added in: REPLACEME#
+
+* *Type:* Object
+* *Env:* `ELASTIC_APM_APM_CLIENT_HEADERS`
+
+Specify custom headers to be included in HTTP requests by the APM agent to
+APM Server. Generally this should not be required for normal usage.
+
+Examples:
+
+[source,bash]
+----
+ELASTIC_APM_APM_CLIENT_HEADERS="foo=bar,spam=eggs"
+----
+
+[source,js]
+----
+require('elastic-apm-node').start({
+  apmClientHeaders: { foo: 'bar', spam: 'eggs' },
+  // ...
+})
+----
+
 
 [[sanitize-field-names]]
 ==== `sanitizeFieldNames`

examples/trace-http-request.js

@@ -45,10 +45,6 @@ function makeARequest(url, opts, cb) {
 // an HTTP server, we manually start a transaction. More details at:
 // https://www.elastic.co/guide/en/apm/agent/nodejs/current/custom-transactions.html
 const t0 = apm.startTransaction('t0');
-makeARequest(
-  'http://httpstat.us/200',
-  { headers: { accept: '*/*' } },
-  function () {
-    t0.end();
-  },
-);
+makeARequest('http://google.com/', { headers: { accept: '*/*' } }, function () {
+  t0.end();
+});

lib/apm-client/apm-client.js

@@ -166,6 +166,7 @@ function getHttpClientConfig(conf, agent) {
     serverCaCert: loadServerCaCertFile(conf.serverCaCertFile),
     rejectUnauthorized: conf.verifyServerCert,
     serverTimeout: conf.serverTimeout * 1000,
+    headers: maybePairsToObject(conf.apmClientHeaders),
 
     // APM Agent Configuration via Kibana:
     centralConfig: conf.centralConfig,

lib/config/schema.js

@@ -590,6 +590,12 @@ const CONFIG_SCHEMA = [
     defaultValue: [],
     deps: ['ignoreUserAgents'],
   },
+  {
+    name: 'apmClientHeaders',
+    configType: 'stringKeyValuePairs',
+    defaultValue: undefined,
+    envVar: 'ELASTIC_APM_APM_CLIENT_HEADERS',
+  },
   // Special options that
   // - may afect the whole config
   // - change the behavior of thelogger