elastic-apm 3.6.0 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e226ecd39fc71213084dffaefbd4343c1d5f5d78a4d8fc91786dca9f5e865533
-  data.tar.gz: a0289b4872d55be4132b6982da072844ce71b2a6723877626584c1f5e8d7315f
+  metadata.gz: 86463e0604357bc3c88e3507de76b0a2e92ba2a1311aab220b6b092df9523319
+  data.tar.gz: 97b3fcbc28f6b46de4e72f536b314380884f6dd192747258f861bf060aa588ab
 SHA512:
-  metadata.gz: 641923b3afdf3c3fe258053a2f2492092aa1af5a35a50c3783b6e7d0d00e6198f8454c95fb4f2eca0a1ea83f59afd552c600ffaed34efa0aeecf44d40b9948cd
-  data.tar.gz: 427eee529da777c98d4c4c02eb79f5aba46200e92edcac1f31b5bbd38df55f78801d92de063c37a54ffecf2fe3777697495c745f8334d3fdae4509626b1e1350
+  metadata.gz: 56a3b688bf4646a11888677fad884937b9f83b04b2cb47d5740f9cb0ce3e1c754abbe861e4888418f6ec168695f940d8ac24c4de3461c61a2d4f7360953d3f30
+  data.tar.gz: 9743b2bc369dfedf3ff28893062171bb1af0a2af201f845701966409ab4c0063a4584257f445fabc6c14eba8a170ddbac9e5fe391554be53652f801cf2d482d5

data/.ci/Jenkinsfile

@@ -19,7 +19,7 @@ pipeline {
   environment {
     REPO = 'apm-agent-ruby'
     BASE_DIR = "src/github.com/elastic/${env.REPO}"
-    PIPELINE_LOG_LEVEL='DEBUG'
+    PIPELINE_LOG_LEVEL = 'INFO'
     NOTIFY_TO = credentials('notify-to')
     JOB_GCS_BUCKET = credentials('gcs-bucket')
     CODECOV_SECRET = 'secret/apm-team/ci/apm-agent-ruby-codecov'
@@ -59,14 +59,23 @@ pipeline {
         deleteDir()
         gitCheckout(basedir: "${BASE_DIR}", githubNotifyFirstTimeContributor: true, reference: "${env.REFERENCE_REPO}")
         stash allowEmpty: true, name: 'source', useDefaultExcludes: false
+        script {
+          dir("${BASE_DIR}"){
+            // Skip all the stages except docs for PR's with asciidoc and md changes only
+            env.ONLY_DOCS = isGitRegionMatch(patterns: [ '.*\\.(asciidoc|md)' ], shouldMatchAll: true)
+          }
+        }
       }
     }
     stage('Sanity checks') {
       when {
         beforeAgent true
-        anyOf {
-          not { changeRequest() }
-          expression { return params.Run_As_Master_Branch }
+        allOf {
+          expression { return env.ONLY_DOCS == "false" }
+          anyOf {
+            not { changeRequest() }
+            expression { return params.Run_As_Master_Branch }
+          }
         }
       }
       options { skipDefaultCheckout() }
@@ -91,6 +100,10 @@ pipeline {
     */
     stage('Test') {
       options { skipDefaultCheckout() }
+      when {
+        beforeAgent true
+        expression { return env.ONLY_DOCS == "false" }
+      }
       steps {
         withGithubNotify(context: 'Tests', tab: 'tests') {
           deleteDir()
@@ -113,9 +126,12 @@ pipeline {
       agent none
       when {
         beforeAgent true
-        anyOf {
-          changeRequest()
-          expression { return !params.Run_As_Master_Branch }
+        allOf {
+          expression { return env.ONLY_DOCS == "false" }
+          anyOf {
+            changeRequest()
+            expression { return !params.Run_As_Master_Branch }
+          }
         }
       }
       steps {
@@ -137,7 +153,7 @@ pipeline {
             branch 'master'
             branch "\\d+\\.\\d+"
             branch "v\\d?"
-            tag "v\\d+\\.\\d+\\.\\d+*"
+            tag pattern: 'v\\d+.*', comparator: "REGEXP"
             expression { return params.Run_As_Master_Branch }
           }
           expression { return params.bench_ci }
@@ -238,7 +254,10 @@ pipeline {
           steps {
             deleteDir()
             // Let's wait for the Gem to be available
-            sh "(retry 10 curl --silent --show-error --fail -I https://rubygems.org/gems/elastic-apm/versions/${env.VERSION})"
+            sh label: 'Wait for gem', script: """#!/usr/bin/env bash
+              source /usr/local/bin/bash_standard_lib.sh
+              (retry 10 curl --silent --show-error --fail -I https://rubygems.org/gems/elastic-apm/versions/${env.VERSION})
+            """
             dir("${OPBEANS_REPO}"){
               git credentialsId: 'f6c7695a-671e-4f4f-a331-acdce44ff9ba',
                   url: "git@github.com:elastic/${OPBEANS_REPO}.git"
@@ -253,6 +272,19 @@ pipeline {
         }
       }
     }
+    stage('Coverage converge') {
+      when {
+        beforeAgent true
+        expression { return env.ONLY_DOCS == "false" }
+      }
+      steps{
+        dir("${BASE_DIR}"){
+          unpack_artifacts(rubyDownstreamJobs)
+          sh(script: "./spec/scripts/coverage_converge.sh")
+          cobertura coberturaReportFile: "coverage/coverage.xml"
+        }
+      }
+    }
   }
   post {
     cleanup {
@@ -261,6 +293,12 @@ pipeline {
   }
 }
 
+def unpack_artifacts(builds) {
+    builds.values().each() { build ->
+      copyArtifacts(projectName: "apm-agent-ruby/apm-agent-ruby-downstream/${env.BRANCH_NAME}", selector: specific(buildNumber: build.number.toString()))
+    }
+}
+
 /**
   Run benchmarks for a Ruby version, then report the results to the Elasticsearch server.
 */
@@ -271,26 +309,27 @@ def runBenchmark(version){
       //  - docker.elastic.co/observability-ci/jruby:9.2-12-jdk to jruby-9.2-12-jdk
       //  - jruby:9.1 to jruby-9.1
       def transformedVersion = version.replaceAll('.*/', '').replaceAll(':', '-')
-      env.HOME = "${env.WORKSPACE}/${transformedVersion}"
-      dir("${transformedVersion}"){
-        deleteDir()
-        unstash 'source'
-        dir("${BASE_DIR}"){
-          retry(2){
-            sleep randomNumber(min:10, max: 30)
-            dockerLogin(secret: "${DOCKER_SECRET}", registry: "${DOCKER_REGISTRY}")
-          }
-          try{
-            sh """./spec/scripts/benchmarks.sh "${version}" "${REFERENCE_REPO}" """
-          } catch(e){
-            throw e
-          } finally {
-            archiveArtifacts(
-              allowEmptyArchive: true,
-              artifacts: "**/benchmark-${transformedVersion}.raw,**/benchmark-${transformedVersion}.error",
-              onlyIfSuccessful: false)
-            sendBenchmarks(file: "benchmark-${transformedVersion}.bulk",
-              index: "benchmark-ruby", archive: true)
+      withEnv(["HOME=${env.WORKSPACE}/${transformedVersion}"]){
+        dir("${transformedVersion}"){
+          deleteDir()
+          unstash 'source'
+          dir("${BASE_DIR}"){
+            retry(2){
+              sleep randomNumber(min:10, max: 30)
+              dockerLogin(secret: "${DOCKER_SECRET}", registry: "${DOCKER_REGISTRY}")
+            }
+            try{
+              sh """./spec/scripts/benchmarks.sh "${version}" "${REFERENCE_REPO}" """
+            } catch(e){
+              throw e
+            } finally {
+              archiveArtifacts(
+                allowEmptyArchive: true,
+                artifacts: "**/benchmark-${transformedVersion}.raw,**/benchmark-${transformedVersion}.error",
+                onlyIfSuccessful: false)
+              sendBenchmarks(file: "benchmark-${transformedVersion}.bulk",
+                index: "benchmark-ruby", archive: true)
+            }
           }
         }
       }
@@ -300,12 +339,14 @@ def runBenchmark(version){
 
 def runJob(String rubyVersion, int sleep = 1){
   def buildObject
+  def branch = env.CHANGE_ID?.trim() ? env.CHANGE_TARGET : env.BRANCH_NAME
   try {
     def quiet = (sleep * randomNumber(min: 2, max: 6)) + 5
     buildObject = build(job: "apm-agent-ruby/apm-agent-ruby-downstream/${env.BRANCH_NAME}",
                         parameters: [
                           string(name: 'RUBY_VERSION', value: "${rubyVersion}"),
-                          string(name: 'BRANCH_SPECIFIER', value: "${env.GIT_BASE_COMMIT}")
+                          string(name: 'BRANCH_SPECIFIER', value: "${env.GIT_BASE_COMMIT}"),
+                          string(name: 'MERGE_TARGET', value: "${branch}")
                         ],
                         quietPeriod: quiet)
   } catch(e) {
@@ -324,8 +365,7 @@ def prepareRelease(Closure body){
     docker.image("${env.RUBY_DOCKER_TAG}").inside('-v ${REFERENCE_REPO}:${REFERENCE_REPO} -v /etc/passwd:/etc/passwd -v ${HOME}/.ssh:${HOME}/.ssh') {
       withEnv(["HOME=${env.WORKSPACE}/${env.BASE_DIR ?: ''}"]) {
         rubygemsLogin.withApi(secret: "${env.RELEASE_SECRET}") {
-          sshagent(['f6c7695a-671e-4f4f-a331-acdce44ff9ba']) {
-            sh '.ci/prepare-git-context.sh'
+          withGitRelease(credentialsId: '2a9602aa-ab9f-4e52-baf3-b71ca88469c7-UserAndToken') {
             sh 'gem install rake yard rspec'
             body()
           }

data/.ci/downstreamTests.groovy

@@ -36,6 +36,7 @@ pipeline {
   parameters {
     string(name: 'RUBY_VERSION', defaultValue: "ruby:2.6", description: "Ruby version to test")
     string(name: 'BRANCH_SPECIFIER', defaultValue: "master", description: "Git branch/tag to use")
+    string(name: 'MERGE_TARGET', defaultValue: "master", description: "Git branch/tag where to merge this code")
   }
   stages {
     /**
@@ -43,12 +44,31 @@ pipeline {
     */
     stage('Checkout') {
       options { skipDefaultCheckout() }
+      when {
+        beforeAgent true
+        not {
+          tag pattern: 'v\\d+.*', comparator: "REGEXP"
+        }
+      }
       steps {
         deleteDir()
         gitCheckout(basedir: "${BASE_DIR}",
           branch: "${params.BRANCH_SPECIFIER}",
           repo: "${REPO}",
-          credentialsId: "${JOB_GIT_CREDENTIALS}")
+          credentialsId: "${JOB_GIT_CREDENTIALS}",
+          mergeTarget: "${params.MERGE_TARGET}")
+        stash allowEmpty: true, name: 'source', useDefaultExcludes: false
+      }
+    }
+    stage('Checkout tag') {
+      options { skipDefaultCheckout() }
+      when {
+        beforeAgent true
+        tag pattern: 'v\\d+.*', comparator: "REGEXP"
+      }
+      steps {
+        deleteDir()
+        gitCheckout(basedir: "${BASE_DIR}")
         stash allowEmpty: true, name: 'source', useDefaultExcludes: false
       }
     }
@@ -83,7 +103,7 @@ pipeline {
           }
         }
       }
-      notifyBuildResult()
+      notifyBuildResult(prComment: false)
     }
   }
 }
@@ -118,16 +138,11 @@ class RubyParallelTaskGenerator extends DefaultParallelTaskGenerator {
           steps.junit(allowEmptyResults: true,
             keepLongStdio: true,
             testResults: "**/spec/junit-reports/**/ruby-agent-junit.xml")
-          if (steps.isCodecovEnabled(x, y)) {
-            steps.codecov(repo: "${steps.env.REPO}", basedir: "${steps.env.BASE_DIR}",
-                          secret: "${steps.env.CODECOV_SECRET}")
-          }
         }
       }
     }
   }
 }
-
 /**
   Run tests for a Ruby version and framework version.
 */
@@ -145,21 +160,13 @@ def runScript(Map params = [:]){
       sleep randomNumber(min:10, max: 30)
       dockerLogin(secret: "${DOCKER_SECRET}", registry: "${DOCKER_REGISTRY}")
       sh("./spec/scripts/spec.sh ${ruby} ${framework}")
+      script{
+        archiveArtifacts(artifacts: "coverage/matrix_results/", defaultExcludes: false)
+      }
     }
   }
 }
 
-/**
-* Whether the given ruby version and framework are in charge of sending the
-* codecov results. It does require the workspace.
-*/
-def isCodecovEnabled(ruby, framework){
-  dir(BASE_DIR){
-    def codecovVersions = readYaml(file: '.ci/.jenkins_codecov.yml')
-    return codecovVersions['ENABLED'].any { it.trim() == "${ruby?.trim()}#${framework?.trim()}" }
-  }
-}
-
 /**
   Run all the tests for the given ruby version and file with the frameworks to test
 */
@@ -178,8 +185,8 @@ def runTests(frameworkFile) {
         name: 'Ruby',
         steps: this
       )
-      def mapPatallelTasks = rubyTasksGen.generateParallelTests()
-      parallel(mapPatallelTasks)
+      def mapParallelTasks = rubyTasksGen.generateParallelTests()
+      parallel(mapParallelTasks)
     }
   }
 }

data/.ci/jobs/defaults.yml

@@ -17,7 +17,7 @@
     days-to-keep: '30'
     concurrent: true
     node: linux
-    periodic-folder-trigger: 1d
+    periodic-folder-trigger: 1w
     prune-dead-branches: true
     publishers:
     - email:

data/.rubocop.yml

@@ -107,3 +107,6 @@ Style/HashTransformKeys:
 Style/HashTransformValues:
   Enabled: true
 
+Style/FrozenStringLiteralComment:
+  Enabled: false
+

data/CHANGELOG.asciidoc

@@ -35,6 +35,33 @@ endif::[]
 [[release-notes-3.x]]
 === Ruby Agent version 3.x
 
+[float]
+[[release-notes-3.7.0]]
+==== 3.7.0 (2020-05-14)
+
+[float]
+===== Changed
+
+- Make config values dynamic so they can be changed via the remote config {pull}747[#747]
+- Log the updated options from central config in addition to cumulative modifications {pull}758[#758]
+
+[float]
+===== Fixed
+
+- Ensure that the log level is updated for the config's logger when value is changed {pull}755[#755]
+- Set config `false` values to `false`, not `nil` {pull}761[#761]
+- Ensure that the previously running agent's config is used in `ElasticAPM.restart` {pull}763[#763]
+- Handle the Resque spy's payload class value being a String or Class and update docs {pull}768[#768]
+- Add finalizer on ProxyPipe::Write so Zlib::GzipWriter is properly closed {pull}787[#787]
+
+[float]
+===== Added
+
+- Add enabled config option, replacing active {pull}669[#669]
+- Add recording config option {pull}765[#765]
+- Add support for `SuckerPunch` {pull}775[#775]
+- Support forking: Detect forking and restart agent tasks and background threads {pull}783[#783]
+
 [[release-notes-3.6.0]]
 ==== 3.6.0 (2020-03-10)
 

data/Gemfile

@@ -1,3 +1,20 @@
+# Licensed to Elasticsearch B.V. under one or more contributor
+# license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright
+# ownership. Elasticsearch B.V. licenses this file to you under
+# the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
 # frozen_string_literal: true
 
 source 'https://rubygems.org'
@@ -34,6 +51,7 @@ gem 'sidekiq', require: nil
 gem 'simplecov', require: false
 gem 'simplecov-cobertura', require: false
 gem 'sneakers', '~> 2.12', require: nil
+gem 'sucker_punch', '~> 2.0', require: nil
 gem 'yard', require: nil
 gem 'yarjuf'
 

data/Rakefile

@@ -1,3 +1,20 @@
+# Licensed to Elasticsearch B.V. under one or more contributor
+# license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright
+# ownership. Elasticsearch B.V. licenses this file to you under
+# the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
 # frozen_string_literal: true
 
 require 'bundler/gem_tasks'
@@ -7,7 +24,7 @@ Update `3.x` branch to be at released commit and push it to GitHub.
 """
 namespace :release do
   task :update_branch do
-    `echo hi && false && git checkout 3.x &&
+    `git checkout 3.x &&
     git rebase master &&
     git push origin 3.x &&
     git checkout master`
@@ -22,3 +39,13 @@ YARD::Rake::YardocTask.new
 task docs: :yard
 
 task default: :spec
+
+namespace :coverage do
+    desc "Collates all result sets generated by the different test runners"
+    task :report do
+      require 'simplecov'
+      require 'simplecov-cobertura'
+      SimpleCov.formatter = SimpleCov::Formatter::CoberturaFormatter
+      SimpleCov.collate Dir["coverage/matrix_results/**/.resultset.json"]
+    end
+  end

data/docs/configuration.asciidoc

@@ -8,9 +8,7 @@ endif::[]
 == Configuration
 
 There are several ways to configure how Elastic APM behaves.
-
-The recommended way to configure Elastic APM is to create a file
-`config/elastic_apm.yml` and specify options in there:
+The recommended way is to specify options in a `config/elastic_apm.yml` file:
 
 [source,yaml]
 ----
@@ -18,17 +16,38 @@ server_url: 'http://localhost:8200'
 secret_token: <%= ENV["VERY_SECRET_TOKEN"] %>
 ----
 
+Some options can be set with `ENV` variables.
+When using this method, strings are split by comma, e.g.,
+`ELASTIC_APM_SANITIZE_FIELD_NAMES="a,b" # => [/a/, /b/]`.
+
+[float]
+[[configuration-precedence]]
+=== Configuration precedence
+
 Options are applied in the following order (last one wins):
 
 1. Defaults
 2. Arguments to `ElasticAPM.start` / `Config.new`
-3. Config file eg. `config/elastic_apm.yml`
+3. Config file, e.g., `config/elastic_apm.yml`
 4. Environment variables
+5. {apm-app-ref}/agent-configuration.html[Central configuration]
+(supported options are marked with <<dynamic-configuration, image:./images/dynamic-config.svg[] >>)
+
+[float]
+[[dynamic-configuration]]
+=== Dynamic configuration
+
+Configuration options marked with the image:./images/dynamic-config.svg[] badge can be changed at runtime
+when set from a supported source.
+
+The Agent supports {apm-app-ref}/agent-configuration.html[Central configuration],
+which allows you to fine-tune certain configurations via the APM app.
+This feature is enabled in the Agent by default, with <<config-central-config>>.
 
 [float]
 === Ruby on Rails
 
-When using Rails it's also possible to specify options inside
+When using Rails, it's possible to specify options inside
 `config/application.rb`:
 
 [source,ruby]
@@ -40,7 +59,7 @@ config.elastic_apm.service_name = 'MyApp'
 [float]
 === Sinatra and Rack
 
-When using APM with Sinatra and Rack you can configure it when starting
+When using Sinatra and Rack, you can configure when starting
 the agent:
 
 [source,ruby]
@@ -52,7 +71,7 @@ ElasticAPM.start(
 )
 ----
 
-Alternatively, you can use the `ElasticAPM::Sinatra.start` API.
+Alternatively, you can use the `ElasticAPM::Sinatra.start` API:
 
 [source,ruby]
 ----
@@ -68,7 +87,7 @@ See <<getting-started-rack>>.
 [float]
 === Grape and Rack
 
-When using APM with Grape and Rack (without Rails), you can configure it when starting
+When using Grape and Rack (without Rails), you can configure when starting
 the agent:
 
 [source,ruby]
@@ -85,12 +104,6 @@ See <<getting-started-rack>>.
 [float]
 === Options
 
-Some options can be set with `ENV` variables and all of them may be set in
-your source code.
-
-When setting values for lists using `ENV` variables, strings are split by comma
-eg `ELASTIC_APM_SANITIZE_FIELD_NAMES="a,b" # => [/a/, /b/]`.
-
 [float]
 [[config-config-file]]
 ==== `config_file`
@@ -165,7 +178,7 @@ WARNING: Api keys only provide any real security if your APM server uses TLS.
 
 [float]
 [[config-active]]
-==== `active`
+==== `active` deprecated:[3.7.0,See <<config-enabled>> instead.]
 |============
 | Environment          | `Config` key | Default
 | `ELASTIC_APM_ACTIVE` | `active`     | `true`
@@ -174,6 +187,8 @@ WARNING: Api keys only provide any real security if your APM server uses TLS.
 Whether or not to start the agent.
 If `active` is `false`, `ElasticAPM.start` will do nothing and all calls to the root API will return `nil`.
 
+NOTE: This option is being removed. See <<config-enabled>> instead.
+
 [float]
 [[config-api-buffer-size]]
 ==== `api_buffer_size`
@@ -192,6 +207,9 @@ went wrong.
 [float]
 [[config-api-request-size]]
 ==== `api_request_size`
+
+<<dynamic-configuration, image:./images/dynamic-config.svg[] >>
+
 |============
 | Environment                    | `Config` key       | Default
 | `ELASTIC_APM_API_REQUEST_SIZE` | `api_request_size` | `"750kb"`
@@ -205,6 +223,9 @@ It has to be provided in *<<config-format-size, size format>>*.
 [float]
 [[config-api-request-time]]
 ==== `api_request_time`
+
+<<dynamic-configuration, image:./images/dynamic-config.svg[] >>
+
 |============
 | Environment                    | `Config` key       | Default
 | `ELASTIC_APM_API_REQUEST_TIME` | `api_request_time` | `"10s"`
@@ -233,6 +254,9 @@ NOTE: This feature requires APM Server and Kibana >= 7.3.
 [float]
 [[config-capture-body]]
 ==== `capture_body`
+
+<<dynamic-configuration, image:./images/dynamic-config.svg[] >>
+
 |============
 | Environment                | `Config` key   | Default | Example |
 | `ELASTIC_APM_CAPTURE_BODY` | `capture_body` | `"off"` | `"all"`
@@ -253,6 +277,9 @@ If your service handles data like this, we advise to only enable this feature wi
 [float]
 [[config-capture-headers]]
 ==== `capture_headers`
+
+<<dynamic-configuration, image:./images/dynamic-config.svg[] >>
+
 |============
 | Environment                   | `Config` key      | Default
 | `ELASTIC_APM_CAPTURE_HEADERS` | `capture_headers` | `true`
@@ -278,7 +305,7 @@ Whether or not to attach `ENV` from Rack to transactions and errors.
 | `ELASTIC_APM_CENTRAL_CONFIG` | `central_config` | `true`
 |============
 
-Enable {apm-app-ref}/agent-configuration.html[APM Agent Configuration via Kibana].
+Enables {apm-app-ref}/agent-configuration.html[APM Agent Configuration via Kibana].
 If set to `true`, the client will poll the APM Server regularly for new agent configuration.
 
 Usually APM Server determines how often to poll, but if not the default interval is 5 minutes.
@@ -383,6 +410,18 @@ Use this option to disable any of these.
 
 Get an array of enabled instrumentations with `ElasticAPM.agent.config.enabled_instrumentations`.
 
+[float]
+[[config-enabled]]
+==== `enabled`
+[options="header"]
+|============
+| Environment          | `Config` key | Default
+| `ELASTIC_APM_ENABLED` | `enabled`     | `true`
+|============
+
+Whether or not to start the agent.
+If `enabled` is `false`, `ElasticAPM.start` will do nothing and all calls to the root API will return `nil`.
+
 [float]
 [[config-environment]]
 ==== `environment`
@@ -514,6 +553,8 @@ Elastic APM can instrument your Rake tasks but given that they are used for a mu
 [[config-log-level]]
 ==== `log_level`
 
+<<dynamic-configuration, image:./images/dynamic-config.svg[] >>
+
 [options="header"]
 |============
 | Environment             | `Config` key | Default
@@ -610,6 +651,23 @@ There are also `ENV` version of these following the same pattern of putting `ELA
 
 See https://github.com/httprb/http/wiki/Proxy-Support[Http.rb's docs].
 
+[float]
+[[config-recording]]
+==== `recording`
+
+<<dynamic-configuration, image:./images/dynamic-config.svg[] >>
+
+[options="header"]
+|============
+| Environment          | `Config` key | Default
+| `ELASTIC_APM_RECORDING` | `recording`     | `true`
+|============
+
+Enable or disable the recording of events.
+If set to false, then the agent does not create or send any events to the Elastic APM server,
+and instrumentation overhead is minimized. The agent continues to poll the server for configuration changes
+when this option is false.
+
 [float]
 [[config-sanitize-field-names]]
 ==== `sanitize_field_names`
@@ -694,6 +752,8 @@ storage use in your Elasticsearch cluster.
 [[config-span-frames-min-duration-ms]]
 ==== `span_frames_min_duration`
 
+<<dynamic-configuration, image:./images/dynamic-config.svg[] >>
+
 |============
 | Environment                            | `Config` key               | Default
 | `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` | `span_frames_min_duration` | `"5ms"`
@@ -737,6 +797,8 @@ The maximum number of stack trace lines per span/error.
 [[config-transaction-max-spans]]
 ==== `transaction_max_spans`
 
+<<dynamic-configuration, image:./images/dynamic-config.svg[] >>
+
 |============
 | Environment                         | `Config` key            | Default
 | `ELASTIC_APM_TRANSACTION_MAX_SPANS` | `transaction_max_spans` | `500`
@@ -752,6 +814,8 @@ too much work for such edge cases.
 [[config-transaction-sample-rate]]
 ==== `transaction_sample_rate`
 
+<<dynamic-configuration, image:./images/dynamic-config.svg[] >>
+
 |============
 | Environment                           | `Config` key              | Default
 | `ELASTIC_APM_TRANSACTION_SAMPLE_RATE` | `transaction_sample_rate` | `1.0`