elastic-apm 3.6.0 → 3.10.1

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'
@@ -17,12 +34,15 @@ gem 'timecop'
 gem 'webmock'
 
 # Integrations
+gem 'aws-sdk-dynamodb', require: nil
 gem 'aws-sdk-sqs', require: nil
 gem 'elasticsearch', require: nil
 gem 'fakeredis', require: nil
 gem 'faraday', require: nil
 gem 'graphql', require: nil
-gem 'grpc' if !defined?(JRUBY_VERSION) && RUBY_VERSION < '2.7'
+gem 'google-protobuf', '< 3.12' if !defined?(JRUBY_VERSION) && RUBY_VERSION < '2.5'
+gem 'grpc' if !defined?(JRUBY_VERSION)
+gem 'json'
 gem 'json-schema', require: nil
 gem 'mongo', require: nil
 gem 'opentracing', require: nil
@@ -34,6 +54,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/bin/run-tests

@@ -8,7 +8,10 @@ runRspec(){
   if [ -n "${case}" ]; then
     bn="$(basename ${case} _spec.rb)/"
   fi
-  bundle exec rspec -f progress -f JUnit -o spec/junit-reports/${bn}ruby-agent-junit.xml ${case}
+  bundle exec rspec \
+    -f progress \
+    -r yarjuf -f JUnit -o spec/junit-reports/${bn}ruby-agent-junit.xml \
+    ${case}
 }
 specific_spec=$1
 

data/docker-compose.yml

@@ -26,11 +26,13 @@ services:
       - /tmp:exec,mode=1777
     depends_on:
       - mongodb
+    user: ${USER_ID}
 
   ruby_rspec:
     image: apm-agent-ruby:${RUBY_VERSION}
     environment:
       MONGODB_URL: 'mongodb:27017'
+    user: ${USER_ID}
 
 volumes:
   vendor:

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`
@@ -260,6 +287,16 @@ If your service handles data like this, we advise to only enable this feature wi
 
 Whether or not to attach the request headers to transactions and errors.
 
+[float]
+[[config-capture-elasticsearch-queries]]
+==== `capture_elasticsearch_queries`
+|============
+| Environment                                 | `Config` key                    | Default
+| `ELASTIC_APM_CAPTURE_ELASTICSEARCH_QUERIES` | `capture_elasticsearch_queries` | `false`
+|============
+
+Whether or not to capture the body from requests in Elasticsearch.
+
 [float]
 [[config-capture-env]]
 ==== `capture_env`
@@ -278,7 +315,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 +420,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 +563,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 +661,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`
@@ -649,6 +717,23 @@ NOTE: The service name must conform to this regular expression: `^[a-zA-Z0-9 _-]
 In layman's terms: Your service name must only contain characters from the ASCII
 alphabet, numbers, dashes, underscores and spaces.
 
+[float]
+[[config-service-node-name]]
+==== `service_node_name`
+
+ [options="header"]
+|============
+| Environment                     | `Config` key        | Default | Example
+| `ELASTIC_APM_SERVICE_NODE_NAME` | `service_node_name` | `nil`   | `"my-app-1"`
+|============
+
+The name of the given service node. This is optional, and if omitted, the APM
+Server will fall back on `system.container.id` if available, and finally
+`host.name` if necessary.
+
+This option allows you to set the node name manually to ensure uniqueness and
+meaningfulness.
+
 [float]
 [[config-service-version]]
 ==== `service_version`
@@ -694,6 +779,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 +824,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 +841,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`
@@ -826,3 +917,13 @@ The unit is provided as suffix directly after the number, without any separation
  * `gb` (gigabytes)
 
 NOTE: we use the power-of-two sizing convention, e.g. `1 kilobyte == 1024 bytes`
+
+[float]
+[[special-configuration]]
+=== Special configuration
+
+Elastic APM patches `Kernel#require` to auto-detect and instrument supported third party libraries. It does so with the utmost care but in rare cases it can conflict with some libraries.
+
+To get around this patch, set the environment variable `ELASTIC_APM_SKIP_REQUIRE_PATCH` to `"1"`.
+
+If you choose to do so, the agent might need some additional tweaking to make sure the third party libraries are picked up and instrumented. Make sure you require the agent _after_ you require your other dependencies.

data/docs/debugging.asciidoc

@@ -28,3 +28,17 @@ Things to consider:
   - Experiencing high load? The agent can spawn multiple instances of its Workers that pick off the queue by changing the option `pool_size` (default is `1`).
   - If you have high load you may also consider setting `transaction_sample_rate` to something smaller than `1.0`. This determines whether to include _spans_ for every _transaction_. If you have enough traffic, skipping some (probably) identical spans won't have a noticeable effect on your data.
 
+[float]
+[[disable-agent]]
+=== Disable the Agent
+
+In the unlikely event the agent causes disruptions to a production application,
+you can disable the agent while you troubleshoot.
+
+If you have access to <<dynamic-configuration,dynamic configuration>>,
+you can disable the recording of events by setting <<config-recording,`recording`>> to `false`.
+When changed at runtime from a supported source, there's no need to restart your application.
+
+If that doesn't work, or you don't have access to dynamic configuration, you can disable the agent by setting
+<<config-enabled,`enabled`>> to `false`.
+You'll need to restart your application for the changes to apply.

data/docs/getting-started-rails.asciidoc

@@ -25,4 +25,6 @@ server_url: http://localhost:8200
 secret_token: ''
 ----
 
+Or if you prefer environment variables, skip the file and set `ELASTIC_APM_SERVER_URL` and `ELASTIC_APM_SECRET_TOKEN` in your local or server environment.
+
 This automatically sets up error logging and performance tracking but of course there are knobs to turn if you'd like to. See <<configuration>>.

data/docs/images/dynamic-config.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="59" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="59" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#9f9f9f" d="M0 0h0v20H0z"/><path fill="#9f9f9f" d="M0 0h59v20H0z"/><path fill="url(#b)" d="M0 0h59v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"> <text x="295" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="490">Dynamic</text><text x="295" y="140" transform="scale(.1)" textLength="490">Dynamic</text></g> </svg>

data/docs/index.asciidoc

@@ -29,9 +29,10 @@ include::./graphql.asciidoc[]
 
 include::./log-correlation.asciidoc[]
 
+include::./performance-tuning.asciidoc[]
+
 include::./debugging.asciidoc[]
 
 include::./upgrading.asciidoc[]
 
 include::./release-notes.asciidoc[]
-

data/docs/introduction.asciidoc

@@ -32,4 +32,5 @@ You can then use the APM app in Kibana to gain insight into latency issues and e
 === Additional Components
 
 APM Agents work in conjunction with the {apm-server-ref-v}/index.html[APM Server], {ref}/index.html[Elasticsearch], and {kibana-ref}/index.html[Kibana].
-Please view the {apm-overview-ref-v}/index.html[APM Overview] for details on how these components work together. 
+The {apm-overview-ref-v}/index.html[APM Overview] provides details on how these components work together,
+and provides a matrix outlining {apm-overview-ref-v}/agent-server-compatibility.html[Agent and Server compatibility].