Configurationedit

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:

---
server_url: 'http://localhost:8200'
secret_token: 'very_very_secret'

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
  4. Environment variables

Ruby on Railsedit

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

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

Sinatra and Rackedit

When using APM with Sinatra and Rack you can configure it when starting the agent:

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

See Getting started with Rack.

Optionsedit

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_ENABLED_ENVIRONMENTS=development,production.

config_fileedit

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.

server_urledit

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_tokenedit

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'
Warning

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

api_buffer_sizeedit

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_sizeedit

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_timeedit

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.

custom_key_filtersedit

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

default_tagsedit

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 Mapping explosion.

disable_sendedit

Environment

Config key

Default

N/A

disable_send

false

Disables sending payloads to APM Server.

disabled_spiesedit

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.

environmentedit

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

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

Note

Kibana will not differentiate between different environments. To avoid mixing data from multiple environments, consider appending the environment to service_name.

filter_exception_typesedit

Environment

Config key

Default

Example

N/A

filter_exception_types

[]

[MyApp::Errors::IgnoredError]

Use this to filter error tracking for specific error constants.

framework_nameedit

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_versionedit

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.

hostnameedit

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_patternsedit

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

instrumentedit

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_tasksedit

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_leveledit

Environment Config key Default

ELASTIC_APM_LOG_LEVEL

log_level

Logger::DEBUG # => 0

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

log_pathedit

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.

loggeredit

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.

pool_sizeedit

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.

service_nameedit

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.

service_versionedit

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_framesedit

source_lines_error_library_framesedit

source_lines_span_app_framesedit

source_lines_span_library_framesedit

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.

Warning

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

span_frames_min_durationedit

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.

transaction_max_spansedit

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_rateedit

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.

verify_server_certedit

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 formatsedit

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

Duration formatedit

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 formatedit

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)
Note

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