feat: impl contextPropagationOnly config var; change disableSend beha…

…viour (#2396)

Implement contextPropagationOnly per spec (it does what disableSend
did before this change). Change disableSend to just disable comms
with APM server, but otherwise *not* attempt to reduce work.
https://github.com/elastic/apm/blob/master/specs/agents/transport.md#context_propagation_only-configuration

Closes: #2393

CHANGELOG.asciidoc

@@ -33,9 +33,28 @@ Notes:
 [float]
 ===== Breaking changes
 
+* Change <<disable-send, `disableSend`>> to no longer skip internal processing
+  work. It now *only* disables communication with APM Server. Use
+  <<context-propagation-only, `contextPropagationOnly`>> if your use case is
+  to limit the APM agent's processing to the minimum to support context
+  propagation and log correlation.
++
+This is listed under "Breaking changes" as a heads-up. The only possible
+negative result of this `disableSend` change is some extra CPU processing time
+by the agent. There is no outward functionality change.
+
 [float]
 ===== Features
 
+* Add <<context-propagation-only, `contextPropagationOnly`>> configuration
+  option. This supports the use case of using the APM agent to propagate HTTP
+  trace-context and to support log-correlation (adding `trace.id` et al fields
+  to log records) **without** an APM server, and to otherwise reduce the
+  processing time of the agent. ({issues}2393[#2393])
++
+This is similar to <<disable-send, `disableSend`>>, but differs in that
+`contextPropagationOnly: true` tells the agent to skip unnecessary work.
+
 * The User-Agent header used for communication with APM Server now includes
   the `serviceName` and `serviceVersion`. For some users this can be
   https://github.com/elastic/apm/issues/509[helpful for APM Server log analysis].
@@ -271,6 +290,7 @@ The fields affected by `longFieldMaxLength` are:
 
 * Add instrumentation of all AWS S3 methods when using the
   https://www.npmjs.com/package/aws-sdk[JavaScript AWS SDK v2] (`aws-sdk`).
+
 * Add <<disable-send, `disableSend`>> configuration option. This supports some
   use cases using the APM agent **without** an APM server. ({issues}2101[#2101])
 

docs/configuration.asciidoc

@@ -148,21 +148,41 @@ See {kibana-ref}/filters.html#environment-selector[environment selector] in the
 NOTE: This feature is fully supported in the APM app in Kibana versions >= 7.2.
 You must use the query bar to filter for a specific environment in versions prior to 7.2.
 
+
+[[context-propagation-only]]
+==== `contextPropagationOnly`
+
+* *Type:* Boolean
+* *Default:* `false`
+* *Env:* `ELASTIC_APM_CONTEXT_PROPAGATION_ONLY`
+
+If set to `true`, the agent will reduce its work to the minimum required to
+support automatic https://w3c.github.io/trace-context/[HTTP trace-context]
+propagation (for distributed tracing) and log correlation. The agent will not
+communicate with APM server (no tracing data is forwarded, no central
+configuration is retrieved) and will not collect metrics. This setting allows
+using the APM agent with a service that cannot use APM server. Usage is expected
+to be rare.
+
+
 [[disable-send]]
 ==== `disableSend`
 
 * *Type:* Boolean
 * *Default:* `false`
 * *Env:* `ELASTIC_APM_DISABLE_SEND`
 
-If set to `true`, the agent will work as usual, except for any task requiring
-communication with the APM server. Events will be dropped and the agent won't be
-able to receive central configuration, which means that any other configuration
-cannot be changed in this state without restarting the service.  Example uses
-for this setting are: maintaining the ability to create traces and log
-trace/transaction/span IDs through the log correlation feature, and getting
-automatic distributed tracing via the https://w3c.github.io/trace-context/[W3C
-HTTP headers].
+If set to `true`, the agent will work as usual, except that it will not attempt
+to communicate with APM server. Tracing and metrics data will be dropped and the
+agent won't be able to receive central configuration, which means that any other
+configuration cannot be changed in this state without restarting the service.
+
+This setting is similar to <<context-propagation-only,
+`contextPropagationOnly`>> in functionality. However, `disableSend` does not
+attempt to reduce time spent collecting tracing data. A use case for this
+setting is in CI environments, to test agent functionality without requiring a
+configured APM server.
+
 
 [[instrument]]
 ==== `instrument`

index.d.ts

@@ -225,6 +225,7 @@ declare namespace apm {
     cloudProvider?: string;
     configFile?: string;
     containerId?: string;
+    contextPropagationOnly?: boolean;
     disableInstrumentations?: string | string[];
     disableSend?: boolean;
     environment?: string;

lib/agent.js

@@ -408,8 +408,8 @@ Agent.prototype.captureError = function (err, opts, cb) {
 
   const id = errors.generateErrorId()
 
-  // Quick out if disableSend=true, no point in the processing time.
-  if (this._conf.disableSend) {
+  // Avoid unneeded error/stack processing if only propagating trace-context.
+  if (this._conf.contextPropagationOnly) {
     if (cb) {
       process.nextTick(cb, null, id)
     }

lib/config.js

@@ -46,6 +46,7 @@ var DEFAULTS = {
   centralConfig: true,
   cloudProvider: 'auto',
   containerId: undefined,
+  contextPropagationOnly: false,
   disableInstrumentations: [],
   disableSend: false,
   environment: process.env.NODE_ENV || 'development',
@@ -102,8 +103,9 @@ var ENV_TABLE = {
   captureHeaders: 'ELASTIC_APM_CAPTURE_HEADERS',
   captureSpanStackTraces: 'ELASTIC_APM_CAPTURE_SPAN_STACK_TRACES',
   centralConfig: 'ELASTIC_APM_CENTRAL_CONFIG',
-  containerId: 'ELASTIC_APM_CONTAINER_ID',
   cloudProvider: 'ELASTIC_APM_CLOUD_PROVIDER',
+  containerId: 'ELASTIC_APM_CONTAINER_ID',
+  contextPropagationOnly: 'ELASTIC_APM_CONTEXT_PROPAGATION_ONLY',
   disableInstrumentations: 'ELASTIC_APM_DISABLE_INSTRUMENTATIONS',
   disableSend: 'ELASTIC_APM_DISABLE_SEND',
   environment: 'ELASTIC_APM_ENVIRONMENT',
@@ -168,6 +170,7 @@ var BOOL_OPTS = [
   'captureHeaders',
   'captureSpanStackTraces',
   'centralConfig',
+  'contextPropagationOnly',
   'disableSend',
   'errorOnAbortedRequests',
   'filterHttpHeaders',
@@ -272,7 +275,7 @@ class Config {
       this.metricsInterval = 0
     }
 
-    if (this.disableSend) {
+    if (this.disableSend || this.contextPropagationOnly) {
       this.transport = function createNoopTransport (conf, agent) {
         return new NoopTransport()
       }

lib/instrumentation/index.js

@@ -270,11 +270,12 @@ Instrumentation.prototype.addEndedTransaction = function (transaction) {
     this._log.debug({ ctxmgr: this._runCtxMgr.toString() }, 'addEndedTransaction(%s)', transaction.name)
   }
 
-  if (agent._conf.disableSend) {
-    // Save effort if disableSend=true. This one log.trace related to
-    // disableSend is included as a possible log hint to future debugging for
-    // why events are not being sent to APM server.
-    agent.logger.trace('disableSend: skip sendTransaction')
+  // Avoid transaction filtering time if only propagating trace-context.
+  if (agent._conf.contextPropagationOnly) {
+    // This one log.trace related to contextPropagationOnly is included as a
+    // possible log hint to future debugging for why events are not being sent
+    // to APM server.
+    agent.logger.trace('contextPropagationOnly: skip sendTransaction')
     return
   }
 
@@ -306,7 +307,8 @@ Instrumentation.prototype.addEndedSpan = function (span) {
   }
   this._log.debug({ ctxmgr: this._runCtxMgr.toString() }, 'addEndedSpan(%s)', span.name)
 
-  if (agent._conf.disableSend) {
+  // Avoid span encoding time if only propagating trace-context.
+  if (agent._conf.contextPropagationOnly) {
     return
   }
 

lib/instrumentation/transaction.js

@@ -288,8 +288,8 @@ Transaction.prototype._captureBreakdown = function (span) {
   const metrics = agent._metrics
   const conf = agent._conf
 
-  // Quick out if disableSend=true, no point in the processing time.
-  if (conf.disableSend) {
+  // Avoid unneeded breakdown metrics processing if only propagating trace context.
+  if (conf.contextPropagationOnly) {
     return
   }
 

lib/metrics/index.js

@@ -23,7 +23,7 @@ class Metrics {
 
   start (refTimers) {
     const metricsInterval = this[agentSymbol]._conf.metricsInterval
-    const enabled = metricsInterval !== 0 && !this[agentSymbol]._conf.disableSend
+    const enabled = metricsInterval !== 0 && !this[agentSymbol]._conf.contextPropagationOnly
     if (enabled) {
       this[registrySymbol] = new MetricsRegistry(this[agentSymbol], {
         reporterOptions: {

lib/noop-transport.js

@@ -1,7 +1,10 @@
 'use strict'
 
 // A no-op (does nothing) Agent transport -- i.e. the APM server client API
-// provided by elastic-apm-http-client. This is used when `disableSend=true`.
+// provided by elastic-apm-http-client.
+//
+// This is used for some configurations (when `disableSend=true` or when
+// `contextPropagationOnly=true`) and in some tests.
 
 class NoopTransport {
   config (opts) {}

test/config.test.js

@@ -58,6 +58,7 @@ var optionFixtures = [
   ['captureSpanStackTraces', 'CAPTURE_SPAN_STACK_TRACES', true],
   ['centralConfig', 'CENTRAL_CONFIG', true],
   ['containerId', 'CONTAINER_ID'],
+  ['contextPropagationOnly', 'CONTEXT_PROPAGATION_ONLY', false],
   ['disableSend', 'DISABLE_SEND', false],
   ['disableInstrumentations', 'DISABLE_INSTRUMENTATIONS', []],
   ['environment', 'ENVIRONMENT', 'development'],