Configuration

edit

There are several ways to configure how Elastic APM behaves. The recommended way is to specify options in a config/elastic_apm.yml file:

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/].

Configuration precedence

edit

Options are applied in the following order (last one wins):

  1. Defaults
  2. Arguments to ElasticAPM.start / Config.new
  3. Config file, e.g., config/elastic_apm.yml
  4. Environment variables
  5. Central configuration (supported options are marked with dynamic config )

Dynamic configuration

edit

Configuration options marked with the dynamic config badge can be changed at runtime when set from a supported source.

The Agent supports Central configuration, which allows you to fine-tune certain configurations via the APM app. This feature is enabled in the Agent by default, with central_config.

Ruby on Rails

edit

When using Rails, it’s possible to specify options inside config/application.rb:

# config/application.rb
config.elastic_apm.service_name = 'MyApp'

Sinatra and Rack

edit

When using Sinatra and Rack, you can configure when starting the agent:

# config.ru or similar
ElasticAPM.start(
  app: MyApp,
  service_name: 'SomeOtherName'
)

Alternatively, you can use the ElasticAPM::Sinatra.start API:

# config.ru or similar
ElasticAPM::Sinatra.start(
  MyApp,
  service_name: 'SomeOtherName'
)

See Getting started with Rack.

Grape and Rack

edit

When using Grape and Rack (without Rails), you can configure when starting the agent:

# config.ru or similar
ElasticAPM::Grape.start(
  MyApp,
  service_name: 'SomeOtherName'
)

See Getting started with Rack.

Options

edit

config_file

edit
Environment Config key Default

ELASTIC_APM_CONFIG_FILE

config_file

config/elastic_apm.yml

Path to the configuration YAML-file. Elastic APM will load config options from this if the file exists. The file will be evaluated as ERB, so you can include ENV variables like in your database.yml, eg:

secret_token: <%= ENV['VERY_SECRET_TOKEN'] %>

server_url

edit
Environment Config key Default

ELASTIC_APM_SERVER_URL

server_url

'http://localhost:8200'

The URL for your APM Server. The URL must be fully qualified, including protocol (http or https) and port.

secret_token

edit
Environment Config key Default Example

ELASTIC_APM_SECRET_TOKEN

secret_token

nil

A random string

This string is used to ensure that only your agents can send data to your APM server. Both the agents and the APM server have to be configured with the same secret token. One example to generate a secure secret token is:

ruby -r securerandom -e 'print SecureRandom.uuid'

Secret tokens only provide any real security if your APM server uses TLS.

api_key

edit
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.

Api keys only provide any real security if your APM server uses TLS.

active [3.7.0] Deprecated in 3.7.0. See enabled instead.

edit

Environment

Config key

Default

ELASTIC_APM_ACTIVE

active

true

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.

This option is being removed. See enabled instead.

api_buffer_size

edit

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 worker pool size or it could mean the agent has trouble connecting to APM Server. The logs should tell you what went wrong.

api_request_size

edit

dynamic config

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 size format.

api_request_time

edit

dynamic config

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 duration format.

breakdown-metrics

edit

Environment

Config key

Default

ELASTIC_APM_BREAKDOWN_METRICS

breakdown_metrics

true

Enable/disable the tracking and collection of breakdown metrics. By setting this to False, tracking this metric is completely disabled, which can reduce the overhead of the agent.

This feature requires APM Server and Kibana >= 7.3.

capture_body

edit

dynamic config

Environment

Config key

Default

Example

For transactions that are HTTP requests, the Ruby agent can optionally capture the request body (e.g. POST variables or JSON data).

Possible values: "errors", "transactions", "all", "off".

If the request has a body and this setting is disabled, the body will be shown as [SKIPPED].

request bodies often contain sensitive values like passwords, credit card numbers etc. We try to strip sensitive looking data from form bodies but don’t touch text bodies like JSON. If your service handles data like this, we advise to only enable this feature with care.

capture_headers

edit

dynamic config

Environment

Config key

Default

ELASTIC_APM_CAPTURE_HEADERS

capture_headers

true

Whether or not to attach the request headers to transactions and errors.

capture_elasticsearch_queries

edit

Environment

Config key

Default

ELASTIC_APM_CAPTURE_ELASTICSEARCH_QUERIES

capture_elasticsearch_queries

false

Whether or not to capture the body from requests in Elasticsearch.

capture_env

edit

Environment

Config key

Default

ELASTIC_APM_CAPTURE_ENV

capture_env

true

Whether or not to attach ENV from Rack to transactions and errors.

central_config

edit

Environment

Config key

Default

ELASTIC_APM_CENTRAL_CONFIG

central_config

true

Enables 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.

This feature requires APM Server v7.3 or later and that the APM Server is configured with kibana.enabled: true.

cloud_provider

edit

Environment

Config key

Default

ELASTIC_APM_CLOUD_PROVIDER

cloud_provider

"auto"

Specify the cloud provider for metadata collection. Defaults to "auto", which means the agent uses trial and error to collect metadata from all supported cloud providers.

Valid options are "auto", "aws", "gcp", "azure", and "none". If set to "none", no cloud metadata will be collected. If set to any of "aws", "gcp", or "azure", attempts to collect metadata will only be performed from the chosen provider.

custom_key_filters [3.5.0] Deprecated in 3.5.0. See sanitize_field_names instead.

edit
Environment Config key Default Example

ELASTIC_APM_CUSTOM_KEY_FILTERS

custom_key_filters

[]

['MyAuthHeader']

Elastic APM strips 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.

When setting this option via ENV, use a comma separated string. Eg. ELASTIC_APM_CUSTOM_KEY_FILTERS="a,b" # => [/a/, /b/]

This option is being removed. See sanitize_field_names instead.

default_tags

edit
Environment Config key Default Example

ELASTIC_APM_DEFAULT_LABELS

default_labels

{}

region=us1

Add default labels to every transaction. Note that this will eventually be deprecated in favor of global_labels.

Be aware that labels are indexed in Elasticsearch. Using too many unique keys will result in Mapping explosion.

global_labels are supported as of APM server version 7.2. default_tags and default_labels will eventually be deprecated so please transition to using global_labels instead. In the meantime, any default_labels that are set will override global_labels.

Environment Config key Default Example

ELASTIC_APM_DEFAULT_TAGS

default_tags

{}

region=us1

Add default tags to add to every transaction. Note that this option has been deprecated in favor of default_labels.

Be aware that tags are indexed in Elasticsearch. Using too many unique keys will result in Mapping explosion.

global_labels are supported as of APM server version 7.2. default_tags and default_labels will eventually be deprecated so please transition to using global_labels instead. In the meantime, any default_tags that are set will override global_labels.

disable_metrics

edit

Environment

Config key

Default

Example

ELASTIC_APM_DISABLE_METRICS

disable_metrics

[]

"*.cpu.*,system.memory.total"

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.

disable_send

edit

Environment

Config key

Default

ELASTIC_APM_DISABLE_SEND

disable_send

false

Disables sending payloads to APM Server.

disable_start_message

edit

Environment

Config key

Default

ELASTIC_APM_DISABLE_START_MESSAGE

disable_start_message

false

Disables the agent’s startup message announcing itself.

disable_instrumentations

edit
Environment Config key Default

ELASTIC_APM_DISABLE_INSTRUMENTATIONS

disable_instrumentations

['json']

Elastic APM automatically instruments select third party libraries. Use this option to disable any of these.

Get an array of enabled instrumentations with ElasticAPM.agent.config.enabled_instrumentations.

enabled

edit
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.

environment

edit
Environment Config key Default Example

ELASTIC_APM_ENVIRONMENT

environment

From ENV

"production"

The name of the environment this service is deployed in, e.g. "production" or "staging".

Environments allow you to easily filter data on a global level in the APM app. It’s important to be consistent when naming environments across agents. See environment selector in the APM app for more information.

Defaults to ENV['RAILS_ENV'] || ENV['RACK_ENV'].

This feature is fully supported in the APM app in Kibana versions >= 7.2. You must use the query bar to filter for a specific environment in versions prior to 7.2.

filter_exception_types

edit

Environment

Config key

Default

Example

N/A

filter_exception_types

[]

[MyApp::Errors::IgnoredError]

Use this to filter error tracking for specific error constants.

framework_name

edit
Environment Config key Default

ELASTIC_APM_FRAMEWORK_NAME

framework_name

Depending on framework

Name of the used framework. For Rails or Sinatra, this defaults to Ruby on Rails and Sinatra respectively, otherwise defaults to nil.

framework_version

edit
Environment Config key Default

ELASTIC_APM_FRAMEWORK_VERSION

framework_version

Depending on framework

Version number of the used framework. For Ruby on Rails and Sinatra, this defaults to the used version of the framework, otherwise, the default is nil.

global_labels

edit
Environment Config key Default Example

ELASTIC_APM_GLOBAL_LABELS

global_labels

nil

dept=engineering,rack=number8

Labels added to all events, with the format key=value[,key=value[,…​]].

This option requires APM Server 7.2 or greater, and will have no effect when using older server versions. default_tags will eventually be deprecated but in the meantime, their value will override any global_labels. Please transition to using global_labels instead of default_tags in light of this deprecation.

hostname

edit
Environment Config key Default Example

ELASTIC_APM_HOSTNAME

hostname

hostname

app-server01.example.com

The host name to use when sending error and transaction data to the APM server.

ignore_url_patterns

edit
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 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/]

instrument

edit
Environment Config key Default Example

ELASTIC_APM_INSTRUMENT

instrument

true

0

Use this option to ignore certain URL patterns eg. healthchecks or admin sections.

instrumented_rake_tasks

edit
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.

log_level

edit

dynamic config

Environment Config key Default

ELASTIC_APM_LOG_LEVEL

log_level

Logger::INFO # => 1

By default Elastic APM logs to stdout or uses Rails.log when used with Rails.

log_path

edit
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.

logger

edit
Environment Config key Default Example

N/A

logger

Depends

Logger.new('path/to_file.log')

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.

metrics_interval

edit
Environment Config key Default

ELASTIC_APM_METRICS_INTERVAL

metrics_interval

'30s'

Specify the interval for reporting metrics to APM Server. The interval should be in seconds, or should include a time suffix.

To disable metrics reporting, set the interval to 0.

pool_size

edit
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.

proxy_address

edit
Environment Config key Default Example

ELASTIC_APM_PROXY_ADDRESS

proxy_address

nil

"example.com"

An address to use as a proxy for the HTTP client.

Options available are:

  • proxy_address
  • proxy_headers
  • proxy_password
  • proxy_port
  • proxy_username

There are also ENV version of these following the same pattern of putting ELASTIC_APM_ in front.

See Http.rb’s docs.

recording

edit

dynamic config

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.

sanitize_field_names

edit
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.

service_name

edit
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.

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.

service_node_name

edit
[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.

service_version

edit
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.

source_lines_error_app_frames

edit

source_lines_error_library_frames

edit

source_lines_span_app_frames

edit

source_lines_span_library_frames

edit

Environment

Config key

Default

ELASTIC_APM_SOURCE_LINES_ERROR_APP_FRAMES

source_lines_error_app_frames

5

ELASTIC_APM_SOURCE_LINES_ERROR_LIBRARY_FRAMES

source_lines_error_library_frames

5

ELASTIC_APM_SOURCE_LINES_SPAN_APP_FRAMES

source_lines_span_app_frames

0

ELASTIC_APM_SOURCE_LINES_SPAN_LIBRARY_FRAMES

source_lines_span_library_frames

0

By default, the APM agent collects source code snippets for errors. With the above settings, you can modify how many lines of source code is collected.

We differ between errors and spans, as well as library frames and app frames.

Especially for spans, collecting source code can have a large impact on storage use in your Elasticsearch cluster.

span_frames_min_duration

edit

dynamic config

Environment

Config key

Default

ELASTIC_APM_SPAN_FRAMES_MIN_DURATION

span_frames_min_duration

"5ms"

Use this to disable stacktrace frame 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 collect stack traces for all spans. Set it to 0 to disable stack trace collection for all spans.

It has to be provided in duration format.

server_ca_cert_file

edit
Environment Config key Default Example

ELASTIC_APM_SERVER_CA_CERT_FILE

server_ca_cert_file

nil

'/path/to/ca.pem'

The path to a custom CA certificate for connecting to APM Server.

stack_trace_limit

edit
Environment Config key Default

ELASTIC_APM_STACK_TRACE_LIMIT

stack_trace_limit

999999

The maximum number of stack trace lines per span/error.

transaction_max_spans

edit

dynamic config

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.

transaction_sample_rate

edit

dynamic config

Environment

Config key

Default

ELASTIC_APM_TRANSACTION_SAMPLE_RATE

transaction_sample_rate

1.0

By default, the agent will sample every transaction (e.g. request to your service). To reduce overhead and storage requirements, you can set the sample rate to a value between 0.0 and 1.0. We still record overall time and the result for unsampled transactions, but no context information, tags, or spans. Note that the sample rate will be rounded to 4 digits of precision.

use_legacy_sql_parser

edit

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.

verify_server_cert

edit

Environment

Config key

Default

ELASTIC_APM_VERIFY_SERVER_CERT

verify_server_cert

true

By default, the agent verifies the SSL certificate if you use an HTTPS connection to the APM server. Verification can be disabled by changing this setting to false.

Configuration formats

edit

Some options require a unit, either duration or size. These need to be provided in a specific format.

Duration format

edit

The duration format is used for options like timeouts. The unit is provided as suffix directly after the number, without any separation by whitespace.

Example: "5ms"

Supported units

  • ms (milliseconds)
  • s (seconds)
  • m (minutes)

Size format

edit

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.

Example: 10kb

Supported units:

  • b (bytes)
  • kb (kilobytes)
  • mb (megabytes)
  • gb (gigabytes)

we use the power-of-two sizing convention, e.g. 1 kilobyte == 1024 bytes

Special configuration

edit

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.