feat: add configFile config option

docs/configuration.asciidoc

@@ -743,3 +743,41 @@ Example:
 ----
 ELASTIC_APM_GLOBAL_LABELS="subspace=sap-hana,rack=number6"
 ----
+
+[[config-file]]
+==== `configFile`
+
+* *Type:* String
+* *Default:* `elastic-apm-node.js`
+* *Env:* `ELASTIC_APM_CONFIG_FILE`
+
+The Node.js agent will look for a file named `elastic-apm-node.js` in the current working directory.
+You can specify a custom path using this config option (this path must include the filename), e.g:
+
+[source,bash]
+----
+ELASTIC_APM_CONFIG_FILE=/path/to/my-elastic-apm-node.js
+----
+
+NOTE: The inline version of this config option,
+that is passed to the <<apm-start,`start`>> function,
+will be ignored if a config file was already loaded when this module was required (based on either the default value or because of the `ELASTIC_APM_CONFIG_FILE` environment variable).
+
+The configuration file is expected to export an object,
+following the same conventions as the `options` object,
+given as the first argument to the <<apm-start,`start`>> function, e.g.:
+
+[source,js]
+----
+module.exports = {
+  // Override service name from package.json
+  // Allowed characters: a-z, A-Z, 0-9, -, _, and space
+  serviceName: '',
+
+  // Use if APM Server requires a token
+  secretToken: '',
+
+  // Set custom APM Server URL (default: http://localhost:8200)
+  serverUrl: ''
+}
+----

docs/setup.asciidoc

@@ -101,31 +101,8 @@ require('elastic-apm-node').start({
 [[agent-configuration-file]]
 ==== Agent configuration file
 
-The Node.js agent will look for a file named `elastic-apm-node.js` in the current working directory. You can specify a custom path for this file using
-the `ELASTIC_APM_CONFIG_FILE` environment variable (this path must include the filename), e.g:
-
-[source,bash]
-----
-ELASTIC_APM_CONFIG_FILE=/path/to/elastic-apm-node.js
-----
-
-The configuration file is expected to export an object following the same conventions as the `options` object given as the first argument
-to the <<apm-start,`start`>> function, e.g.:
-
-[source,js]
-----
-module.exports = {
-  // Override service name from package.json
-  // Allowed characters: a-z, A-Z, 0-9, -, _, and space
-  serviceName: '',
-
-  // Use if APM Server requires a token
-  secretToken: '',
-
-  // Set custom APM Server URL (default: http://localhost:8200)
-  serverUrl: ''
-}
-----
+The Node.js agent will look for a file named `elastic-apm-node.js` in the current working directory.
+You can specify a custom path for this file using the <<config-file,`configFile`>> config option.
 
 [[es-modules]]
 === ES Modules support

lib/config.js

@@ -24,15 +24,7 @@ config.CAPTURE_ERROR_LOG_STACK_TRACES_ALWAYS = 'always'
 
 module.exports = config
 
-var confPath = path.resolve(process.env.ELASTIC_APM_CONFIG_FILE || 'elastic-apm-node.js')
-if (fs.existsSync(confPath)) {
-  try {
-    var confFile = require(confPath)
-  } catch (err) {
-    console.error('Elastic APM initialization error: Can\'t read config file %s', confPath)
-    console.error(err.stack)
-  }
-}
+let confFile = loadConfigFile()
 
 let serviceName, serviceVersion
 try {
@@ -201,10 +193,16 @@ class Config {
     this.ignoreUserAgentStr = []
     this.ignoreUserAgentRegExp = []
 
+    // 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) {
+      confFile = loadConfigFile(opts.configFile)
+    }
+
     Object.assign(
       this,
       DEFAULTS, // default options
-      confFile, // options read from elastic-apm-node.js config file
+      confFile, // options read from config file
       opts, // options passed in to agent.start()
       readEnv() // options read from environment variables
     )
@@ -525,3 +523,18 @@ function pairsToObject (pairs) {
 function numberBetweenZeroAndOne (n) {
   return n >= 0 && n <= 1
 }
+
+function loadConfigFile (configFile) {
+  const confPath = path.resolve(configFile || process.env.ELASTIC_APM_CONFIG_FILE || 'elastic-apm-node.js')
+
+  if (fs.existsSync(confPath)) {
+    try {
+      return require(confPath)
+    } catch (err) {
+      console.error('Elastic APM initialization error: Can\'t read config file %s', confPath)
+      console.error(err.stack)
+    }
+  }
+
+  return null
+}