elastic-apm 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e4d23e9be2ca2a869a03d54424544c63978b38b13799ed46da429812762affb
-  data.tar.gz: 6952d04574e879c03a9abdad3833978a4c86710db81c188ca3e7891d619d54d6
+  metadata.gz: bfb206def6af3e002dc6b946add05afddaa93909016ca654711a6efd4a9353c9
+  data.tar.gz: fc4edd5a2209f1babfe9277865024eb71eb24a7713b2f77c8d80a4ed6c12117f
 SHA512:
-  metadata.gz: d617dadc865b556eb60a0d6e0004ab762a45463c1acef373407898b69cc8d3a54dc578bca312b33d9f16ee5f2b3a14bfee452ea71143caebc2faf6be456a0cd2
-  data.tar.gz: f28c617a638546575bfe7bac445fb4ed0aa31df8c5daae83e7c4b1b7c22bc0c3e2d2560643bfa22acde3c4c97601c66f1e55c3e69d3e9b925a30a681f1ee7a46
+  metadata.gz: 464029e0c25e3a1b3ab9417f16e3b73ca8c6f5e779f37a4e45d0648c76bd2a58ff417fa95fa55adb97c5da465e637dc270df63e4b86ed2a1584ccc9040d32bbd
+  data.tar.gz: ddebff0d47f88aaa983b46764ecafd4e12073c33434d8c7bb275e3f0655466fb237bf72ea2a3ebc8dc6583c97bf97e6903699e49efd39e74143981e3d608b8aa

data/.gitignore

@@ -14,3 +14,4 @@ Gemfile.lock
 /html_docs/
 spec/elastic_apm.log
 spec/ruby-agent-junit.xml
+.gem

data/.rspec

@@ -1,2 +1,3 @@
 --color
 --require spec_helper
+--format documentation

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 2.2
+  TargetRubyVersion: 2.3
   Exclude:
     - 'elastic-apm.gemspec'
     - 'vendor/**/*'
@@ -59,3 +59,9 @@ Style/EmptyMethod:
 
 Rails/Delegate:
   Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false

data/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## 2.0.0 (2018-11-14)
+
+Version adds support for APM Server 6.5 and needs at least that.
+
+### Added
+
+- Support for APM Server 6.5 (Intake v2)
+- Support for Distributed Tracing (beta)
+- Support for RUM Agent correlation (Distributed Tracing)
+- Support for [HTTP.rb](https://github.com/httprb/http) (Instrumentation + Distributed Tracing)
+
+### Changed
+
+- Custom instrumentation APIs ([#209](https://github.com/elastic/apm-agent-ruby/pull/209))
+- Tag keys will convert disallowed chars to `_`
+- Default log level changed to `info`
+- Laxed version requirement of concurrent-ruby
+- Change `log_level` to only concern agent log
+
+### Deprecated
+
+#### APIs:
+
+- `ElasticAPM.transaction`
+- `ElasticAPM.span`
+
+#### Options:
+
+- `compression_level`
+- `compression_minimum_size`
+- `debug_http`
+- `debug_transactions`
+- `flush_interval`
+- `http_open_timeout`
+- `http_read_timeout`
+- `enabled_environments`
+- `disable_environment_warning`
+
+Some options that used to take a certain unit for granted now expects explicit units – but will fall back to old default.
+
+### Removed
+
+- Support for APM Server versions prior to 6.5.
+- Support for Ruby 2.2 (eol)
+
 ## 1.1.0 (2018-09-07)
 
 ### Added

data/Gemfile

@@ -6,21 +6,22 @@ git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 gemspec
 
-gem 'elasticsearch'
-gem 'fakeredis', require: nil
-gem 'json-schema'
-gem 'mongo'
 gem 'pry'
 gem 'rack-test'
-gem 'rake'
-gem 'redis', require: nil
 gem 'rspec'
-gem 'rubocop'
-gem 'sequel'
-gem 'sidekiq'
+gem 'rspec-its'
+gem 'rubocop', require: nil
 gem 'timecop'
 gem 'webmock'
-gem 'yard'
+
+gem 'elasticsearch', require: nil
+gem 'fakeredis', require: nil
+gem 'json-schema', require: nil
+gem 'mongo', require: nil
+gem 'rake', require: nil
+gem 'sequel', require: nil
+gem 'sidekiq', require: nil
+gem 'yard', require: nil
 gem 'yarjuf'
 
 if RUBY_PLATFORM == 'java'
@@ -41,7 +42,11 @@ else
   gem framework
 end
 
+unless version == 'master'
+  gem 'delayed_job', require: nil
+end
+
 group :bench do
-  gem 'ruby-prof', platforms: %i[ruby]
-  gem 'stackprof', platforms: %i[ruby]
+  gem 'ruby-prof', require: nil, platforms: %i[ruby]
+  gem 'stackprof', require: nil, platforms: %i[ruby]
 end

data/bench/app.rb

@@ -20,11 +20,10 @@ class App
     @config = ElasticAPM::Config.new(
       {
         environment: 'bench',
-        enabled_environments: ['bench'],
         disable_send: true
       }.merge(config)
     )
-    @serializer = ElasticAPM::Serializers::Transactions.new(@config)
+    # @serializer = ElasticAPM::Serializers::Transactions.new(@config)
     @mock_env = Rack::MockRequest.env_for('/')
   end
 

data/bench/benchmark.rb

@@ -23,7 +23,7 @@ def perform(app, count: 1000)
     end
   end
 
-  app.serializer.build_all(transactions)
+  # app.serializer.build_all(transactions)
 
   app.stop
 end

data/bench/stackprof.rb

@@ -8,7 +8,7 @@ require 'stackprof'
 require 'rack/test'
 require 'elastic-apm'
 
-ElasticAPM.start environment: 'bench', enabled_environments: ['bench']
+ElasticAPM.start environment: 'bench'
 
 env = Rack::MockRequest.env_for('/')
 

data/docs/api.asciidoc

@@ -1,8 +1,8 @@
 [[api]]
 == Public API
 
-Although most usage is covered automatically, Elastic APM also has a public API that
-allows custom usage.
+Although most usage is covered automatically, Elastic APM also has a public
+API that allows custom usage.
 
 [float]
 [[agent-life-cycle]]
@@ -24,7 +24,8 @@ ElasticAPM.start(server_url: 'http://localhost:8200')
   * `config`: An optional hash or `ElasticAPM::Config` instance with configuration
   options.  See <<configuration,Configuration>>.
 
-If you are using <<getting-started-rails,Ruby on Rails>> this is done automatically for you.
+If you are using <<getting-started-rails,Ruby on Rails>> this is done
+automatically for you.
 If not see <<getting-started-rack,Getting started with Rack>>.
 
 [float]
@@ -56,61 +57,103 @@ Returns the currently running agent or nil.
 Returns the current `ElasticAPM::Transaction` or nil.
 
 [float]
-[[api-agent-transaction]]
-==== `ElasticAPM.transaction`
+[[api-agent-start_transaction]]
+==== `ElasticAPM.start_transaction`
 
-Start a _transaction_ eg. a web request or background job.
-
-If called without a block you are expected to end the transaction yourself.
-If given a block, the code inside will be wrapped in a transaction.
-
-You need to submit it yourself with `transaction.submit(status)`.
+Start a _transaction_ eg. an incoming web request or a background job.
 
 [source,ruby]
 ----
 # call with block
-transaction = ElasticAPM.transaction('Do things') do
-  do_work # ...
-end # .done is called when block ends
-
-transaction.submit(200)
-
-# without block
-transaction = ElasticAPM.transaction('Do things')
-do_work
-transaction.submit(200) # .submit(result) will also .done(result)
+ElasticAPM.start_transaction('Name')
+do_work # ...
+ElasticAPM.end_transaction('result')
 ----
 
 Arguments:
 
   * `name`: A name for your transaction. Transactions are grouped by name. **Required**.
   * `type`: A `type` for your transaction eg. `db.postgresql.sql`.
-  * `context:`: An optional <<api-context,Context>> used to enrich the transaction with
-  information about the current request.
-  * `&block`: An optional block to wrap with the transaction. The block is passed the
-  transaction as an optional argument.
+  * `context:`: An optional <<api-context,Context>> used to enrich the
+  transaction with information about the current request.
+  * `traceparent:`: An optional `Traceparent` object for Distributed Tracing.
 
 Returns the transaction.
 
 [float]
-[[api-agent-span]]
-==== `ElasticAPM.span`
+[[api-agent-end_transaction]]
+==== `ElasticAPM.end_transaction`
+
+Ends the currently running transaction.
+
+Arguments:
 
-Most transactions have nested spans signifying work of a specific sort eg. database
-queries or external web requests.
+  * `result`: A `String` result of the transaction, eg. `'success'`.
 
-If given a block, wrap the code inside in a span.
-If not you are expected to close the span yourself with `span.done(result)`.
+[float]
+[[api-agent-with_transaction]]
+==== `ElasticAPM.with_transaction`
+
+Wrap a block in a Transaction, starting and ending around the block
 
 [source,ruby]
 ----
-ElasticAPM.transaction 'Do things' do
-  ElasticAPM.span 'Do one of the things' do
-    Database.query # ...
-  end
+ElasticAPM.transaction 'Do things' do |transaction|
+  do_work # ...
+
+  transaction.result = 'success'
 end
 ----
 
+Arguments: 
+
+  * `name`: A name for your transaction. Transactions are grouped by name. **Required**.
+  * `type`: A `type` for your transaction eg. `db.postgresql.sql`.
+  * `context:`: An optional <<api-context,Context>> used to enrich the
+  transaction with information about the current request.
+  * `traceparent:`: An optional `Traceparent` object for Distributed Tracing.
+  * `&block`: A block to wrap. Optionally yields the transaction.
+
+Returns the return value of the given block.
+
+[float]
+[[api-agent-start_span]]
+==== `ElasticAPM.start_span`
+
+Start a new span.
+
+[source,ruby]
+----
+ElasticAPM.with_transaction 'Do things' do
+  ElasticAPM.start_span 'Do one of the things'
+  Database.query # ...
+  ElasticAPM.end_span
+end
+----
+
+Arguments:
+
+  * `name`: A name for your span. **Required**.
+  * `type`: The type of work eg. `db.postgresql.query`.
+  * `context`: An instance of `Span::Context`.
+  * `include_stacktrace`: Whether or not to collect a Stacktrace.
+  * `&block`: An optional block to wrap with the span.
+  The block is passed the span as an optional argument.
+
+Returns the created span.
+
+[float]
+[[api-agent-end_span]]
+==== `ElasticAPM.end_span`
+
+Ends the currently running span.
+
+[float]
+[[api-agent-with_span]]
+==== `ElasticAPM.with_span`
+
+Wraps a block in a Span.
+
 Arguments:
 
   * `name`: A name for your span. **Required**.
@@ -120,7 +163,7 @@ Arguments:
   * `&block`: An optional block to wrap with the span.
   The block is passed the span as an optional argument.
 
-Return the span or the return value of the given block.
+Returns the return value of the given block.
 
 [float]
 [[api-agent-build-context]]
@@ -191,8 +234,8 @@ Returns `[ElasticAPM::Error]`.
 ==== `ElasticAPM.set_tag`
 
 Add a tag to the current transaction.
-Tags are basic key-value pairs that are indexed in your Elasticsearch database and
-therefore searchable.
+Tags are basic key-value pairs that are indexed in your Elasticsearch database
+and therefore searchable.
 
 [source,ruby]
 ----
@@ -203,7 +246,7 @@ end
 
 Arguments:
 
-  * `key`: A string key.
+  * `key`: A string key. Note that `.`, `*` or `"` will be converted to `_`.
   * `value`: A string value.
 
 Returns the set `value`.
@@ -287,51 +330,48 @@ end
 
 - `name`: String
 - `type`: String
+- `result`: String
+- `trace_id`: String (readonly)
 
 [float]
-[[api-transaction-release]]
-==== `#release`
-
-Makes sure the transaction is no longer `ElasticAPM.current_transaction`.
-
-[float]
-[[api-transaction-done]]
-==== `#done(result)`
-
-*Args:*
-
-- `result`: String result of transaction, eg. `success`. Default: `nil`.
-
-Ends the transaction, settings its `duration` to µs since it began and sets its result.
-
-Returns `self`.
-
-[float]
-[[api-transaction-done_]]
-==== `#done?`
+[[api-transaction-sampled_]]
+==== #sampled?
 
-Returns whether the transaction is done.
+Whether the transaction is _sampled_ eg. it includes stacktraces for its spans.
 
 [float]
-[[api-transaction-submit]]
-==== `#submit(result, status:, headers:)`
+[[api-transaction-ensure_parent_id]]
+==== #ensure_parent_id
 
-*Args:*
+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
+`String`.
 
-- `result`: String result of transaction, eg. `success`. Default: `nil`.
-- `status`: HTTP status code (for request transactions). Default: `nil`.
-- `headers`: HTTP headers (for request transactions). Default: `{}`.
+This enables the correlation of the spans the JavaScript Real User Monitoring
+(RUM) agent creates for the initial page load with the transaction of the
+backend service.
 
-Ends transaction with done, adds HTTP request information, releases it and submits
-it to the queue of transactions waiting to be sent to APM Server.
+If your service generates the HTML page dynamically, initializing the
+JavaScript RUM agent with the value of this method allows analyzing the time
+spent in the browser vs in the backend services.
 
-Returns `self`.
+To enable the JavaScript RUM agent, initilialize the RUM agent with the Ruby
+agent'a current transaction:
 
-[float]
-[[api-transaction-sampled_]]
-==== #sampled?
-
-Whether the transaction is _sampled_ eg. it includes stacktraces for its spans.
+[source,html]
+----
+<script src="elastic-apm-js-base/dist/bundles/elastic-apm-js-base.umd.min.js"></script>
+<script>
+  var elasticApm = initApm({
+    serviceName: '',
+    serverUrl: 'http://localhost:8200',
+    pageLoadTraceId: "<%= ElasticAPM.current_transaction&.trace_id %>",
+    pageLoadSpanId: "<%= ElasticAPM.current_transaction&.ensure_parent_id %>",
+    pageLoadSampled: <%= ElasticAPM.current_transaction&.sampled? %>
+  })
+</script>
+----
+See the {apm-rum-ref}[JavaScript RUM agent documentation] for more information.
 
 [float]
 [[api-span]]
@@ -347,5 +387,4 @@ Whether the transaction is _sampled_ eg. it includes stacktraces for its spans.
 [[api-context]]
 === Context
 
-A `Context` provides more information to transactions. Build one with `ElasticAPM.build_context`.
-
+See https://www.elastic.co/guide/en/apm/server/current/transaction-api.html#transaction-context-schema[APM Server API Specs].

data/docs/configuration.asciidoc

@@ -56,7 +56,7 @@ 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_ENBALED_ENVIRONMENTS=development,production`.
+eg `ELASTIC_APM_ENABLED_ENVIRONMENTS=development,production`.
 
 [float]
 [[config-config-file]]
@@ -68,7 +68,7 @@ eg `ELASTIC_APM_ENBALED_ENVIRONMENTS=development,production`.
 | `ELASTIC_APM_CONFIG_FILE` | `config_file` | `config/elastic_apm.yml`
 |============
 
-Path to the configuration Yaml-file.
+Path to the configuration YAML-file.
 Elastic APM will load config options from this if the file exists.
 
 [float]
@@ -107,37 +107,103 @@ ruby -r securerandom -e 'print SecureRandom.uuid'
 WARNING: Secret tokens only provide any real security if your APM server use TLS.
 
 [float]
-[[config-service-name]]
-==== `service_name`
+[[config-api-buffer-size]]
+==== `api_buffer_size`
+|============
+| Environment                   | `Config` key      | Default
+| `ELASTIC_APM_API_BUFFER_SIZE` | `api_buffer_size` | `256`
+|============
+
+Maximum amount of objects kept in queue, before sending to APM Server.
+
+If you hit this limit you either have to increase the agent's 
+<<config-pool-size,worker pool size>> or it could mean the agent has trouble
+connecting to APM Server. The <<config-log-path,logs>> should tell you what
+went wrong.
+
+[float]
+[[config-api-request-size]]
+==== `api_request_size`
+|============
+| Environment                    | `Config` key       | Default
+| `ELASTIC_APM_API_REQUEST_SIZE` | `api_request_size` | `"750kb"`
+|============
+
+Maximum amount of bytes sent over one request to APM Server. When reached the agent
+will open a new request.
+
+It has to be provided in *<<config-format-size, size format>>*.
+
+[float]
+[[config-api-request-time]]
+==== `api_request_time`
+|============
+| Environment                    | `Config` key       | Default
+| `ELASTIC_APM_API_REQUEST_TIME` | `api_request_time` | `"10s"`
+|============
+
+Maximum duration of a single streaming request to APM Server before opening
+a new one.
+
+APM Server has its own limit of 30 seconds before it will close requests.
 
+It has to be provided in *<<config-format-duration, duration format>>*.
+
+[float]
+[[config-custom-key-filters]]
+==== `custom_key_filters`
 [options="header"]
 |============
-| Environment                | `Config` key   | Default    | Example
-| `ELASTIC_APM_SERVICE_NAME` | `service_name` | App's name | `MyApp`
+| Environment                      | `Config` key         | Default | Example
+| `ELASTIC_APM_CUSTOM_KEY_FILTERS` | `custom_key_filters` | `[]`    | `['MyAuthHeader']`
 |============
 
-The name of your service.
-This is used to keep all the errors and transactions of your service together and is
-the primary filter in the Elastic APM user interface.
+Elastic APM strips
+https://github.com/elastic/apm-agent-ruby/blob/1.x/lib/elastic_apm/filters/secrets_filter.rb[
+what looks like confidential information] from the request/response headers.
+Use this option to add your own custom header keys to the list of filtered keys.
 
-If you're using Ruby on Rails this will default to your app's name.
-If you're using Sinatra it will default to the name of your app's class.
+When setting this option via `ENV`, use a comma separated string.
+Eg. `ELASTIC_APM_CUSTOM_KEY_FILTERS="a,b" # => [/a/, /b/]`
 
-NOTE: The service name must conform to this regular expression: `^[a-zA-Z0-9 _-]+$`.
-In less regexy terms: Your service name must only contain characters from the ASCII
-alphabet, numbers, dashes, underscores and spaces.
+[float]
+[[config-default-tags]]
+==== `default_tags`
+
+[options="header"]
+|============
+| Environment                | `Config` key   | Default | Example
+| `ELASTIC_APM_DEFAULT_TAGS` | `default_tags` | `{}`    | `region=us1`
+|============
+
+Add default tags to add to every transaction.
+
+WARNING: Be aware that tags are indexed in Elasticsearch. Using too many unique keys will result in *https://www.elastic.co/blog/found-crash-elasticsearch#mapping-explosion[Mapping explosion]*.
 
 [float]
-[[config-service-version]]
-==== `service_version`
+[[config-disable-send]]
+==== `disable_send`
+|============
+| Environment | `Config` key   | Default
+| N/A         | `disable_send` | `false`
+|============
+
+Disables sending payloads to APM Server.
+
+[float]
+[[config-disabled-spies]]
+==== `disabled_spies`
+
 [options="header"]
 |============
-| Environment                    | `Config` key      | Default   | Example
-| `ELASTIC_APM_SERVICE_VERSION`  | `service_version` | `git` sha | A string indicating the version of the deployed service
+| Environment                  | `Config` key     | Default
+| `ELASTIC_APM_DISABLED_SPIES` | `disabled_spies` | `['json']`
 |============
 
-Deployed version of your service.
-Defaults to `git rev-parse --verify HEAD`.
+Elastic APM automatically instruments select third party libraries.
+Use this option to disable any of these.
+
+Get an array of enabled spies with `ElasticAPM.agent.config.enabled_spies`.
 
 [float]
 [[config-environment]]
@@ -154,22 +220,19 @@ e.g. "production" or "staging".
 
 Defaults to `ENV['RAILS_ENV'] || ENV['RACK_ENV']`.
 
-[float]
-[[config-enabled-environments]]
-==== `enabled-environments`
+NOTE: Kibana will not differentiate between different environments. To avoid
+mixing data from multiple environments, consider appending the environment to
+`service_name`.
 
-[options="header"]
+[float]
+[[config-filter-exception-types]]
+==== `filter_exception_types`
 |============
-| Environment                        | `Config` key           | Default
-| `ELASTIC_APM_ENABLED_ENVIRONMENTS` | `enabled_environments` | `['production']`
+| Environment | `Config` key             | Default | Example
+| N/A         | `filter_exception_types` | `[]`    | `[MyApp::Errors::IgnoredError]`
 |============
 
-Specify which environments to enable APM in.
-
-If the current envrironment isn't included, the agent will effectively be a _noop_
-and do nothing.
-So you can keep in your custom instrumentation code without the agent sending
-anything nor complain.
+Use this to filter error tracking for specific error constants.
 
 [float]
 [[config-framework-name]]
@@ -210,20 +273,44 @@ otherwise, the default is `nil`.
 The host name to use when sending error and transaction data to the APM server.
 
 [float]
-[[config-log-path]]
-==== `log_path`
+[[config-custom-ignore-url-patterns]]
+==== `ignore_url_patterns`
+[options="header"]
+|============
+| Environment                       | `Config` key          | Default | Example
+| `ELASTIC_APM_IGNORE_URL_PATTERNS` | `ignore_url_patterns` | `[]`    | `['^/ping', %r{^/admin}]`
+|============
+
+Use this option to ignore certain URL patterns eg. healthchecks or admin sections.
+
+_Ignoring_ in this context means _don't wrap in a <<api-transaction,Transaction>>_.
+Errors will still be reported.
 
+When setting this option via `ENV`, use a comma separated string.
+Eg. `ELASTIC_APM_IGNORE_URL_PATTERNS="a,b" # => [/a/, /b/]`
+
+[float]
+[[config-instrument]]
+==== `instrument`
 [options="header"]
 |============
-| Environment            | `Config` key | Default | Example
-| `ELASTIC_APM_LOG_PATH` | `log_path`   | `nil`   | `log/elastic_apm.log`
+| Environment              | `Config` key | Default | Example
+| `ELASTIC_APM_INSTRUMENT` | `instrument` | `true`  | `0`
 |============
 
-A path to a log file.
+Use this option to ignore certain URL patterns eg. healthchecks or admin sections.
 
-By default Elastic APM logs to `stdout` or uses `Rails.log` when used with Rails.
+[float]
+[[config-instrumented-rake-tasks]]
+==== `instrumented_rake_tasks`
 
-Should support both absolute and relative paths. Just make sure the directory exists.
+[options="header"]
+|============
+| Environment                           | `Config` key              | Default | Example
+| `ELASTIC_APM_INSTRUMENTED_RAKE_TASKS` | `instrumented_rake_tasks` | `[]`    | `['my_task']`
+|============
+
+Elastic APM can instrument your Rake tasks but given that they are used for a multitude of sometimes very different and not always relevant things, this is opt in.
 
 [float]
 [[config-log-level]]
@@ -237,6 +324,22 @@ Should support both absolute and relative paths. Just make sure the directory ex
 
 By default Elastic APM logs to `stdout` or uses `Rails.log` when used with Rails.
 
+[float]
+[[config-log-path]]
+==== `log_path`
+
+[options="header"]
+|============
+| Environment            | `Config` key | Default | Example
+| `ELASTIC_APM_LOG_PATH` | `log_path`   | `nil`   | `log/elastic_apm.log`
+|============
+
+A path to a log file.
+
+By default Elastic APM logs to `stdout` or uses `Rails.log` when used with Rails.
+
+Should support both absolute and relative paths. Just make sure the directory exists.
+
 [float]
 [[config-logger]]
 ==== `logger`
@@ -251,6 +354,56 @@ By default Elastic APM logs to `stdout` or uses `Rails.log` when used with Rails
 
 Use this to provide another logger. Expected to have the same API as Ruby's built-in `Logger`.
 
+[float]
+[[config-pool-size]]
+==== `pool_size`
+
+[options="header"]
+|============
+| Environment             | `Config` key | Default | Example
+| `ELASTIC_APM_POOL_SIZE` | `pool_size`  | `1`     | `2`
+|============
+
+Elastic APM uses a thread pool to send its data to APM Server.
+
+This makes sure the agent doesn't block the main thread any more than necessary.
+
+If you have high load and get warnings about the buffer being full, increasing
+the worker pool size might help.
+
+[float]
+[[config-service-name]]
+==== `service_name`
+
+[options="header"]
+|============
+| Environment                | `Config` key   | Default    | Example
+| `ELASTIC_APM_SERVICE_NAME` | `service_name` | App's name | `MyApp`
+|============
+
+The name of your service.
+This is used to keep all the errors and transactions of your service together and is
+the primary filter in the Elastic APM user interface.
+
+If you're using Ruby on Rails this will default to your app's name.
+If you're using Sinatra it will default to the name of your app's class.
+
+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-version]]
+==== `service_version`
+[options="header"]
+|============
+| Environment                    | `Config` key      | Default   | Example
+| `ELASTIC_APM_SERVICE_VERSION`  | `service_version` | `git` sha | A string indicating the version of the deployed service
+|============
+
+Deployed version of your service.
+Defaults to `git rev-parse --verify HEAD`.
+
 [float]
 [[config-source-lines-error-app-frames]]
 ==== `source_lines_error_app_frames`
@@ -286,51 +439,33 @@ storage use in your Elasticsearch cluster.
 
 |============
 | Environment                            | `Config` key               | Default
-| `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` | `span_frames_min_duration` | `5`
+| `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` | `span_frames_min_duration` | `"5ms"`
 |============
 
-Use this to disable stacktrace collection for spans with a duration shorter than or equal to the given amount of milleseconds.
-
-The default is 5ms.
-
-Set it to `-1` to disable the feature and collect stack traces for all spans.
-Setting it to a positive value, e.g. `5`, will limit stack trace collection to spans
-with durations equal or longer than the given value in milliseconds, e.g. 5 milliseconds.
-
-To disable stack trace collection for spans completely, set the value to `0`.
-
-[float]
-[[config-max-queue-size]]
-==== `max_queue_size`
+Use this to disable stacktrace frame collection for spans with a duration shorter
+than or equal to the given amount of milleseconds.
 
-|============
-| Environment                  | `Config` key     | Default
-| `ELASTIC_APM_MAX_QUEUE_SIZE` | `max_queue_size` | `500`
-|============
+The default is `"5ms"`.
 
-Maximum queue length of transactions before sending transactions to the APM server.
-A lower value will increase the load on your APM server,
-while a higher value can increase the memory pressure of your app.
-A higher value also impacts the time until transactions are indexed and searchable
-in Elasticsearch.
+Set it to `-1` to collect stack traces for all spans.
+Set it to `0` to disable stack trace collection for all spans.
 
-This setting is useful to limit memory consumption if you experience a sudden spike
-of traffic.
+It has to be provided in *<<config-format-duration, duration format>>*.
 
 [float]
-[[config-flush-interval]]
-==== `flush_interval`
+[[config-transaction-max-spans]]
+==== `transaction_max_spans`
 
 |============
-| Environment                  | `Config` key     | Default
-| `ELASTIC_APM_FLUSH_INTERVAL` | `flush_interval` | `10`
+| Environment                         | `Config` key            | Default
+| `ELASTIC_APM_TRANSACTION_MAX_SPANS` | `transaction_max_spans` | `500`
 |============
 
-Interval with which transactions should be sent to the APM server, in seconds.
-A lower value will increase the load on your APM server,
-while a higher value can increase the memory pressure on your app.
-A higher value also impacts the time until transactions are indexed and searchable
-in Elasticsearch.
+Limits the amount of spans that are recorded per transaction.
+This is helpful in cases where a transaction creates a very high amount of spans
+(e.g. thousands of SQL queries).
+Setting an upper limit will prevent overloading the agent and the APM server with
+too much work for such edge cases.
 
 [float]
 [[config-transaction-sample-rate]]
@@ -347,21 +482,6 @@ between `0.0` and `1.0`.
 We still record overall time and the result for unsampled transactions, but no
 context information, tags, or spans.
 
-[float]
-[[config-transaction-max-spans]]
-==== `transaction_max_spans`
-
-|============
-| Environment                         | `Config` key            | Default
-| `ELASTIC_APM_TRANSACTION_MAX_SPANS` | `transaction_max_spans` | `500`
-|============
-
-Limits the amount of spans that are recorded per transaction.
-This is helpful in cases where a transaction creates a very high amount of spans
-(e.g. thousands of SQL queries).
-Setting an upper limit will prevent overloading the agent and the APM server with
-too much work for such edge cases.
-
 [float]
 [[config-verify-server-cert]]
 ==== `verify_server_cert`
@@ -375,97 +495,42 @@ the APM server.
 Verification can be disabled by changing this setting to `false`.
 
 [float]
-[[config-disabled-spies]]
-==== `disabled_spies`
+[[config-formats]]
+=== Configuration formats
 
-[options="header"]
-|============
-| Environment                  | `Config` key     | Default
-| `ELASTIC_APM_DISABLED_SPIES` | `disabled_spies` | `['json']`
-|============
-
-Elastic APM automatically instruments select third party libraries.
-Use this option to disable any of these.
-
-Get an array of enabled spies with `ElasticAPM.agent.config.enabled_spies`.
+Some options require a unit, either duration or size.
+These need to be provided in a specific format.
 
 [float]
-[[config-instrumented-rake-tasks]]
-==== `instrumented_rake_tasks`
-
-[options="header"]
-|============
-| Environment                           | `Config` key              | Default | Example
-| `ELASTIC_APM_INSTRUMENTED_RAKE_TASKS` | `instrumented_rake_tasks` | `[]`    | `['my_task']`
-|============
+[[config-format-duration]]
+==== Duration format
 
-Elastic APM can instrument your Rake tasks but given that they are used for a multitude of sometimes very different and not always relevant things, this is opt in.
-
-[float]
-[[config-default-tags]]
-==== `default_tags`
+The _duration_ format is used for options like timeouts.
+The unit is provided as suffix directly after the number, without any separation by whitespace.
 
-[options="header"]
-|============
-| Environment                | `Config` key   | Default | Example
-| `ELASTIC_APM_DEFAULT_TAGS` | `default_tags` | `{}`    | `region=us1`
-|============
+*Example*: `"5ms"`
 
-Add default tags to add to every transaction.
+*Supported units*
 
-WARNING: Be aware that tags are indexed in Elasticsearch. Using too many unique keys will result in *https://www.elastic.co/blog/found-crash-elasticsearch#mapping-explosion[Mapping explosion]*.
+ * `ms` (milliseconds)
+ * `s` (seconds)
+ * `m` (minutes)
 
 [float]
-[[config-custom-key-filters]]
-==== `custom_key_filters`
-[options="header"]
-|============
-| Environment                      | `Config` key         | Default | Example
-| `ELASTIC_APM_CUSTOM_KEY_FILTERS` | `custom_key_filters` | `[]`    | `['MyAuthHeader']`
-|============
+[[config-format-size]]
+==== Size format
 
-Elastic APM strips
-https://github.com/elastic/apm-agent-ruby/blob/1.x/lib/elastic_apm/filters/secrets_filter.rb[
-what looks like confidential information] from the request/response headers.
-Use this option to add your own custom header keys to the list of filtered keys.
+The _size_ format is used for options like maximum buffer sizes.
+The unit is provided as suffix directly after the number, without any separation by whitespace.
 
-When setting this option via `ENV`, use a comma separated string.
-Eg. `ELASTIC_APM_CUSTOM_KEY_FILTERS="a,b" # => [/a/, /b/]`
-
-[float]
-[[config-custom-ignore-url-patterns]]
-==== `ignore_url_patterns`
-[options="header"]
-|============
-| Environment                       | `Config` key          | Default | Example
-| `ELASTIC_APM_IGNORE_URL_PATTERNS` | `ignore_url_patterns` | `[]`    | `['^/ping', %r{^/admin}]`
-|============
 
-Use this option to ignroe certain URL patterns eg. healthchecks or admin sections.
+*Example*: `10kb`
 
-_Ignoring_ in this context means _don't wrap in a <<api-transaction,Transaction>>_.
-Errors will still be reported.
+*Supported units*:
 
-When setting this option via `ENV`, use a comma separated string.
-Eg. `ELASTIC_APM_IGNORE_URL_PATTERNS="a,b" # => [/a/, /b/]`
-
-[float]
-[[config-filter-exception-types]]
-==== `filter_exception_types`
-|============
-| Environment | `Config` key             | Default | Example
-| N/A         | `filter_exception_types` | `[]`    | `[MyApp::Errors::IgnoredError]`
-|============
-
-Use this to filter error tracking for specific error constants.
-
-[float]
-[[config-disable-send]]
-==== `disable_send`
-|============
-| Environment | `Config` key   | Default
-| N/A         | `disable_send` | `false`
-|============
-
-Disables sending payloads to APM Server.
+ * `b` (bytes)
+ * `kb` (kilobytes)
+ * `mb` (megabytes)
+ * `gb` (gigabytes)
 
+NOTE: we use the power-of-two sizing convention, e.g. `1 kilobyte == 1024 bytes`