feat: ignore_message_queues configuration (#2008)

* feat: ignore_message_queues configuration

* feat: docs

* feat: typescript type

* fix: whitespace nit

* fix: lint

* fix: makes type optional

* fix: central config

* fix: PR feedback -- central config, consistant grammar

docs/configuration.asciidoc

@@ -933,3 +933,34 @@ During startup the Node.js agent queries the local environment to determine whet
 - `none`: Do not query for any cloud provider information.
 
 If the value is not one of the five listed above, the agent will use the value of `auto`.
+
+[[ignore-message-queues]]
+==== `ignoreMessageQueues`
+* *Type:* Array
+* *Default:* `[]`
+* *Env:* `ELASTIC_IGNORE_MESSAGE_QUEUES`
+* <<dynamic-configuration, image:./images/dynamic-config.svg[] >> *Central config name:* `ignore_message_queues`
+
+Array or comma-separated string of wildcard patterns that tell the agent to
+ignore certain queues/topics when instrumenting messaging systems.
+
+When an instrumented messaging system sends or receives a message, the agent
+will test the queue/topic name against each wildcard in this list. If
+the name matches, the agent will skip instrumenting the operation.
+
+The `ignoreMessageQueues` property supports simple wildcard (`*`) patterns, and
+may not include commas.  Wildcard matches are case-insensitive by default. You
+may make wildcard searches case-sensitive by using the `(?-i)` prefix.
+
+Example usage:
+
+[source,js]
+----
+require('elastic-apm-node').start({
+  ignoreMessageQueues: [
+    'overnight_jobs',
+    'events_*',
+    '(?-i)caseSensitiveSearch'
+  ]
+})
+----

index.d.ts

@@ -211,6 +211,7 @@ interface AgentConfigOptions {
   frameworkVersion?: string;
   globalLabels?: KeyValueConfig;
   hostname?: string;
+  ignoreMessageQueues?: Array<string>;
   ignoreUrls?: Array<string | RegExp>;
   ignoreUserAgents?: Array<string | RegExp>;
   instrument?: boolean;

lib/config.js

@@ -58,6 +58,7 @@ var DEFAULTS = {
   errorOnAbortedRequests: false,
   filterHttpHeaders: true,
   globalLabels: undefined,
+  ignoreMessageQueues: [],
   instrument: true,
   instrumentIncomingHTTPRequests: true,
   kubernetesNamespace: undefined,
@@ -106,6 +107,7 @@ var ENV_TABLE = {
   cloudProvider: 'ELASTIC_APM_CLOUD_PROVIDER',
   disableInstrumentations: 'ELASTIC_APM_DISABLE_INSTRUMENTATIONS',
   environment: 'ELASTIC_APM_ENVIRONMENT',
+  ignoreMessageQueues: 'ELASTIC_IGNORE_MESSAGE_QUEUES',
   errorMessageMaxLength: 'ELASTIC_APM_ERROR_MESSAGE_MAX_LENGTH',
   errorOnAbortedRequests: 'ELASTIC_APM_ERROR_ON_ABORTED_REQUESTS',
   filterHttpHeaders: 'ELASTIC_APM_FILTER_HTTP_HEADERS',
@@ -151,7 +153,8 @@ var CENTRAL_CONFIG = {
   transaction_max_spans: 'transactionMaxSpans',
   capture_body: 'captureBody',
   transaction_ignore_urls: 'transactionIgnoreUrls',
-  sanitize_field_names: 'sanitizeFieldNames'
+  sanitize_field_names: 'sanitizeFieldNames',
+  ignore_message_queues: 'ignoreMessageQueues'
 }
 
 var BOOL_OPTS = [
@@ -201,7 +204,8 @@ var MINUS_ONE_EQUAL_INFINITY = [
 var ARRAY_OPTS = [
   'disableInstrumentations',
   'sanitizeFieldNames',
-  'transactionIgnoreUrls'
+  'transactionIgnoreUrls',
+  'ignoreMessageQueues'
 ]
 
 var KEY_VALUE_OPTS = [
@@ -221,6 +225,7 @@ class Config {
     this.ignoreUserAgentRegExp = []
     this.transactionIgnoreUrlRegExp = []
     this.sanitizeFieldNamesRegExp = []
+    this.ignoreMessageQueuesRegExp = []
     // If we didn't find a config file on process boot, but a path to one is
     // provided as a config option, let's instead try to load that
     if (confFile === null && opts && opts.configFile) {
@@ -491,6 +496,17 @@ function normalizeIgnoreOptions (opts) {
     }
     delete opts.ignoreUserAgents
   }
+
+  if (opts.ignoreMessageQueues) {
+    if (!opts.ignoreMessageQueuesRegExp) {
+      opts.ignoreMessageQueuesRegExp = []
+    }
+    const wildcard = new WildcardMatcher()
+    for (const ptn of opts.ignoreMessageQueues) {
+      const re = wildcard.compile(ptn)
+      opts.ignoreMessageQueuesRegExp.push(re)
+    }
+  }
 }
 
 function normalizeNumbers (opts) {

test/config.js

@@ -1060,6 +1060,73 @@ test('should accept and normalize cloudProvider', function (t) {
   delete process.env.ELASTIC_APM_CLOUD_PROVIDER
   t.end()
 })
+
+test('should accept and normalize ignoreMessageQueues', function (suite) {
+  suite.test('ignoreMessageQueues defaults', function (t) {
+    const agent = Agent()
+    agent.start()
+    t.equals(
+      agent._conf.ignoreMessageQueues.length,
+      0,
+      'ignore message queue defaults empty'
+    )
+
+    t.equals(
+      agent._conf.ignoreMessageQueuesRegExp.length,
+      0,
+      'ignore message queue regex defaults empty'
+    )
+    t.end()
+  })
+
+  suite.test('ignoreMessageQueues via configuration', function (t) {
+    const agent = Agent()
+    agent.start({ ignoreMessageQueues: ['f*o', 'bar'] })
+    t.equals(
+      agent._conf.ignoreMessageQueues.length,
+      2,
+      'ignore message picks up configured values'
+    )
+
+    t.equals(
+      agent._conf.ignoreMessageQueuesRegExp.length,
+      2,
+      'ignore message queue regex picks up configured values'
+    )
+
+    t.ok(
+      agent._conf.ignoreMessageQueuesRegExp[0].test('faooooo'),
+      'wildcard converted to regular expression'
+    )
+    t.end()
+  })
+
+  suite.test('ignoreMessageQueues via env', function (t) {
+    const agent = Agent()
+    process.env.ELASTIC_IGNORE_MESSAGE_QUEUES = 'f*o,bar,baz'
+    agent.start()
+    t.equals(
+      agent._conf.ignoreMessageQueues.length,
+      3,
+      'ignore message queue picks up env values'
+    )
+
+    t.equals(
+      agent._conf.ignoreMessageQueuesRegExp.length,
+      3,
+      'ignore message queue regex picks up env values'
+    )
+
+    t.ok(
+      agent._conf.ignoreMessageQueuesRegExp[0].test('faooooo'),
+      'wildcard converted to regular expression'
+    )
+    t.end()
+  })
+
+  suite.end()
+})
+
 function assertEncodedTransaction (t, trans, result) {
   t.comment('transaction')
   t.strictEqual(result.id, trans.id, 'id matches')