elastic-apm 3.4.0 → 3.9.0

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
@@ -446,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 <<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]
@@ -86,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_CUSTOM_KEY_FILTERS="a,b" # => [/a/, /b/]`.
-
 [float]
 [[config-config-file]]
 ==== `config_file`
@@ -147,9 +159,26 @@ ruby -r securerandom -e 'print SecureRandom.uuid'
 
 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 uses TL
 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 *<<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"`
@@ -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`
@@ -728,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]]
@@ -795,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.