elastic-apm 3.5.0 → 3.10.0

data/CONTRIBUTING.md

@@ -41,10 +41,12 @@ $ spec/scripts/spec.sh ruby:2.6 rails-5.2
 To release a new version:
 
 1. Update `VERSION` in `lib/elastic_apm/version.rb` according to the changes (major, minor, patch).
-2. Update `CHANGELOG.md` to reflect the new version – change _Unreleased_ section to _Version (release date)_.
-3. Make a new commit with the changes above, with a message in the style of `vX.X.X`.
-4. Run `rake release`. This will...
+1. Update `CHANGELOG.md` to reflect the new version – change _Unreleased_ section to _Version (release date)_.
+1. For Majors: Add a new row to the EOL table in `docs/upgrading.asciidoc`. The EOL date is the release date plus 18 months. 
+1. Make a new commit with the changes above, with a message in the style of `vX.X.X`.
+1. Run `rake release`. This will...
     1. Tag the current commit as new version.
     2. Push the tag to GitHub.
     3. Build the gem and upload to Rubygems (local user needs to be signed in and authorized.)
-    4. Update `2.x` branch to be at released commit and push it to GitHub.
+1. Run `rake release:update_branch`. This will...
+    1. Update `3.x` branch to be at released commit and push it to GitHub.

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,30 +34,30 @@ 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 '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
 gem 'rake', require: nil
+gem 'resque', require: nil
 gem 'sequel', require: nil
 gem 'shoryuken', require: nil
 gem 'sidekiq', require: nil
-gem 'sneakers', '~> 2.12', 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'
 
-if RUBY_PLATFORM == 'java'
-  gem 'activerecord-jdbcsqlite3-adapter'
-  gem 'jdbc-sqlite3'
-else
-  gem 'sqlite3'
-end
-
 ## Install Framework
 GITHUB_REPOS = {
   'grape' => 'ruby-grape/grape',
@@ -59,7 +76,7 @@ end
 frameworks_versions.each do |framework, version|
   case version
   when 'master'
-    gem framework, github: GITHUB_REPOS.fetch[framework]
+    gem framework, github: GITHUB_REPOS.fetch(framework)
   when /.+/
     gem framework, "~> #{version}.0"
   else
@@ -73,6 +90,15 @@ if frameworks_versions.key?('rails')
   end
 end
 
+if RUBY_PLATFORM == 'java'
+  gem 'activerecord-jdbcsqlite3-adapter'
+  gem 'jdbc-sqlite3'
+elsif frameworks_versions['rails'] =~ /^(4|5)/
+  gem 'sqlite3', '~> 1.3.6'
+else
+  gem 'sqlite3' # rubocop:disable Bundler/DuplicatedGem
+end
+
 group :bench do
   gem 'ruby-prof', require: nil, platforms: %i[ruby]
   gem 'stackprof', require: nil, platforms: %i[ruby]

data/Rakefile

@@ -1,12 +1,34 @@
+# 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'
 
-Rake::Task[:release].enhance do
-  `git checkout 3.x &&
-  git rebase master &&
-  git push origin 3.x &&
-  git checkout master`
+desc """Post release action:
+Update `3.x` branch to be at released commit and push it to GitHub.
+"""
+namespace :release do
+  task :update_branch do
+    `git checkout 3.x &&
+    git rebase master &&
+    git push origin 3.x &&
+    git checkout master`
+  end
 end
 
 require 'rspec/core/rake_task'
@@ -17,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,6 +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/api.asciidoc

@@ -42,6 +42,18 @@ If you're not using Rails, see <<getting-started-rack,Getting started with Rack>
 Stop the currently running agent. Use this inside `at_exit` in your
 <<getting-started-rack,Rack app>> to gracefully shut down.
 
+[float]
+[[api-agent-restart]]
+==== `ElasticAPM.restart`
+
+If the agent is already running, this method will stop and start the agent.
+
+If the agent is not already running, this method will start the agent.
+
+A config can be passed to the method that will be used to start the agent. If the agent
+is already running and no config is passed to the `#restart` method, the running agent's
+config will be used.
+
 [float]
 [[api-agent-running]]
 ==== `ElasticAPM.running?`
@@ -425,13 +437,13 @@ end
 
 [float]
 [[api-transaction-sampled_]]
-==== #sampled?
+==== `#sampled?`
 
 Whether the transaction is _sampled_ eg. it includes stacktraces for its spans.
 
 [float]
 [[api-transaction-ensure_parent_id]]
-==== #ensure_parent_id
+==== `#ensure_parent_id`
 
 If the transaction does not have a parent-ID yet, calling this method generates
 a new ID, sets it as the parent-ID of this transaction, and returns it as a

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`
@@ -765,20 +856,14 @@ context information, tags, or spans.
 
 [float]
 [[config-use-experimental-sql-parser]]
-==== `use_experimental_sql_parser`
+==== `use_legacy_sql_parser`
 |============
-| Environment                               | `Config` key                  | Default
-| `ELASTIC_APM_USE_EXPERIMENTAL_SQL_PARSER` | `use_experimental_sql_parser` | `false`
+| Environment                         | `Config` key            | Default
+| `ELASTIC_APM_USE_LEGACY_SQL_PARSER` | `use_legacy_sql_parser` | `false`
 |============
 
-Use a newer, more precise but still experimental approach to generating summaries of
-your app's SQL statements.
-Without this, your SQL statements will still be summarized albeit less accurately.
-
-The summaries become the spans' names -- what it says in the waterfall view in Kibana.
-
-NOTE: This should work just fine but is still deamed experimental. That means it is
-subject to change. Please let us know if you come across any issues.
+Use the older, less precise approach to generating summaries of your app's SQL statements.
+Try this if you're experiencing trouble using the new default.
 
 [float]
 [[config-verify-server-cert]]
@@ -832,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.