elastic-apm 3.3.0 → 3.8.0

data/bench/sql.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'json'
+require 'benchmark'
+include Benchmark # rubocop:disable Style/MixinUsage
+
+require 'elastic_apm/sql_summarizer'
+require 'elastic_apm/sql/signature'
+
+examples =
+  JSON
+  .parse(File.read('../apm/tests/random_sql_query_set.json'))
+  .map { |ex| ex['input'] }
+
+puts "#{'=' * 14} Parsing #{examples.length} examples #{'=' * 14}"
+
+summarizer = ElasticAPM::SqlSummarizer.new
+
+result_old = nil
+result_new = nil
+
+benchmark(CAPTION, 7, FORMAT, 'avg/ex:') do |bm|
+  old = bm.report('old:') do
+    result_old = examples.map { |i| summarizer.summarize(i) }
+  end
+  new = bm.report('new:') do
+    result_new = examples.map { |i| ElasticAPM::Sql::Signature.parse(i) }
+  end
+
+  [(new - old) / examples.length]
+end
+
+pp(result_old.count { |res| res == 'SQL' })
+pp(result_new.count { |res| res =~ /(--|\/\*\*)/ })
+
+## Stackprof
+
+require 'stackprof'
+
+puts 'Running stackprof'
+profile = StackProf.run(mode: :wall, interval: 1) do
+  examples.each { |i| ElasticAPM::Sql::Signature.parse(i) }
+end
+puts ''
+
+StackProf::Report.new(profile).print_text

data/bin/build_docs

@@ -2,4 +2,4 @@
 set -ex
 
 # Requires elastic/docs to be checked out at ../docs
-../docs/build_docs.pl --doc docs/index.asciidoc --chunk 1
+../docs/build_docs --doc docs/index.asciidoc --chunk 1

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 <
 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?`
@@ -146,11 +158,30 @@ Arguments:
   * `action`: The action type of span eg. `connect` or `query`.
   * `context`: An instance of `Span::Context`.
   * `include_stacktrace`: Whether or not to collect a Stacktrace.
+  * `trace_context:`: An optional `TraceContext` object for Distributed Tracing.
+  * `parent:`: An optional parent transaction or span. Relevant when the span is created in another thread.
+  * `sync:`: An boolean to indicate whether the span is created synchronously or not.
   * `&block`: An optional block to wrap with the span.
   The block is passed the span as an optional argument.
 
 Returns the created span.
 
+If you'd like to create an asynchronous span, you have to pass the parent `Span` or `Transaction` to the `start_span` method.
+You can also set the `sync` flag to `false`, if you'd like the span to be marked as asynchronous. This has no effect other than being queryable in Elasticsearch.
+
+[source,ruby]
+----
+transaction = ElasticAPM.current_transaction # or start one with `.start_transaction`
+Thread.new do
+  ElasticAPM.start_span(
+    'job 1',
+    parent: transaction,
+    sync: false
+  ) { Worker.perform }
+  ElasticAPM.end_span
+end
+----
+
 [float]
 [[api-agent-end_span]]
 ==== `ElasticAPM.end_span`
@@ -171,11 +202,29 @@ Arguments:
   * `action`: The action type of span eg. `connect` or `query`.
   * `context`: An instance of `Span::Context`.
   * `include_stacktrace`: Whether or not to collect a Stacktrace.
+  * `trace_context:`: An optional `TraceContext` object for Distributed Tracing.
+  * `parent:`: An optional parent transaction or span. Relevant when the span is created in another thread.
+  * `sync:`: An boolean to indicate whether the span is created synchronously or not.
   * `&block`: An optional block to wrap with the span.
   The block is passed the span as an optional argument.
 
 Returns the return value of the given block.
 
+If you'd like to create an asynchronous span, you have to pass the parent `Span` or `Transaction` to the `with_span` method.
+You can also set the `sync` flag to `false`, if you'd like the span to be marked as asynchronous.
+
+[source,ruby]
+----
+transaction = ElasticAPM.current_transaction # or start one with `.start_transaction`
+Thread.new do
+  ElasticAPM.with_span(
+    'job 1',
+    parent: transaction,
+    sync: false
+  ) { Worker.perform }
+end
+----
+
 [float]
 [[api-agent-build-context]]
 ==== `ElasticAPM.build_context`
@@ -388,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
@@ -409,7 +458,7 @@ JavaScript RUM agent with the value of this method allows analyzing the time
 spent in the browser vs in the backend services.
 
 To enable the JavaScript RUM agent, initilialize the RUM agent with the Ruby
-agent'a current transaction:
+agent's current transaction:
 
 [source,html]
 ----

data/docs/configuration.asciidoc

@@ -8,28 +8,46 @@ 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]
 ----
----
 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]
@@ -41,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]
@@ -53,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]
 ----
@@ -69,7 +87,7 @@ See <>.
 [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]
@@ -86,12 +104,6 @@ See <>.
 [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_CUSTOM_KEY_FILTERS="a,b" # => [/a/, /b/]`.
-
 [float]
 [[config-config-file]]
 ==== `config_file`
@@ -145,11 +157,28 @@ One example to generate a secure secret token is:
 ruby -r securerandom -e 'print SecureRandom.uuid'
 ----
 
-WARNING: Secret tokens only provide any real security if your APM server use TLS.
+WARNING: Secret tokens only provide any real security if your APM server uses TLS.
+
+[float]
+[[config-api-key]]
+==== `api_key`
+
+[options="header"]
+|============
+| Environment           | `Config` key | Default | Example
+| `ELASTIC_APM_API_KEY` | `api_key`    | `nil`   | A base64-encoded string
+|============
+
+This base64-encoded string is used to ensure that only your agents can send data to your APM server.
+You must have created the api key using the APM server command line tool. Please see the APM server
+documentation for details on how to do that. Please note that this feature is experimental in the
+APM server in version 7.6.
+
+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`
@@ -158,6 +187,8 @@ WARNING: Secret tokens only provide any real security if your APM server use 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`
@@ -176,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"`
@@ -189,6 +223,9 @@ It has to be provided in *<>*.
 [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"`
@@ -217,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"`
@@ -237,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`
@@ -244,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`
@@ -262,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.
@@ -271,7 +324,7 @@ NOTE: This feature requires APM Server v7.3 or later and that the APM Server is
 
 [float]
 [[config-custom-key-filters]]
-==== `custom_key_filters`
+==== `custom_key_filters` deprecated:[3.5.0,See <<config-sanitize-field-names>> instead.]
 [options="header"]
 |============
 | Environment                      | `Config` key         | Default | Example
@@ -286,6 +339,8 @@ Use this option to add your own custom header keys to the list of filtered keys.
 When setting this option via `ENV`, use a comma separated string.
 Eg. `ELASTIC_APM_CUSTOM_KEY_FILTERS="a,b" # => [/a/, /b/]`
 
+NOTE: This option is being removed. See <<config-sanitize-field-names>> instead.
+
 [float]
 [[config-default-tags]]
 ==== `default_tags`
@@ -328,6 +383,7 @@ that are set will override `global_labels`.
 
 A comma-separated list of dotted metrics names that should not be sent to the APM Server.
 You can use `*` to match multiple metrics.
+Matching is case-insensitive.
 
 [float]
 [[config-disable-send]]
@@ -351,12 +407,12 @@ Disables the agent's startup message announcing itself.
 
 [float]
 [[config-disabled-instrumentations]]
-==== `disabled_instrumentations`
+==== `disable_instrumentations`
 
 [options="header"]
 |============
-| Environment                             | `Config` key                | Default
-| `ELASTIC_APM_DISABLED_INSTRUMENTATIONS` | `disabled_instrumentations` | `['json']`
+| Environment                            | `Config` key               | Default
+| `ELASTIC_APM_DISABLE_INSTRUMENTATIONS` | `disable_instrumentations` | `['json']`
 |============
 
 Elastic APM automatically instruments select third party libraries.
@@ -364,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`
@@ -495,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
@@ -591,6 +661,41 @@ 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`
+
+[options="header"]
+|============
+| Environment                        | `Config` key           | Default | Example
+| `ELASTIC_APM_SANITIZE_FIELD_NAMES` | `sanitize_field_names` | `[]`    | `Auth*tion,abc*,*xyz`
+|============
+
+Sometimes it is necessary to sanitize the data sent to Elastic APM, e.g. remove sensitive data.
+
+Configure a list of wildcard patterns of field names which should be sanitized. These apply to HTTP headers and bodies (if you're capturing those.)
+
+Supports the wildcard `*`, which matches zero or more characters.
+Examples: `/foo/*/bar/*/baz*`, `*foo*`.
+Matching is case insensitive.
+
 [float]
 [[config-service-name]]
 ==== `service_name`
@@ -612,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`
@@ -657,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"`
@@ -700,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`
@@ -715,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`
@@ -726,6 +854,17 @@ 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-use-experimental-sql-parser]]
+==== `use_legacy_sql_parser`
+|============
+| Environment                         | `Config` key            | Default
+| `ELASTIC_APM_USE_LEGACY_SQL_PARSER` | `use_legacy_sql_parser` | `false`
+|============
+
+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]]
 ==== `verify_server_cert`
@@ -778,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.