Configuration
editConfiguration
editThere 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):
- Defaults
-
Arguments to
ElasticAPM.start
/Config.new
-
Config file eg.
config/elastic_apm.yml
- Environment variables
Ruby on Rails
editWhen using Rails it’s also possible to specify options inside
config/application.rb
:
# config/application.rb config.elastic_apm.service_name = 'MyApp'
Sinatra and Rack
editWhen 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.
Options
editSome 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
.
config_file
editEnvironment | Config key |
Default |
---|---|---|
|
|
|
Path to the configuration Yaml-file. Elastic APM will load config options from this if the file exists.
server_url
editEnvironment | Config key |
Default |
---|---|---|
|
|
|
The URL for your APM Server.
The URL must be fully qualified, including protocol (http
or https
)
and port.
secret_token
editEnvironment | Config key |
Default | Example |
---|---|---|---|
|
|
|
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 use TLS.
service_name
editEnvironment | Config key |
Default | Example |
---|---|---|---|
|
|
App’s name |
|
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 less regexy terms: Your service name must only contain characters from the ASCII
alphabet, numbers, dashes, underscores and spaces.
service_version
editEnvironment | Config key |
Default | Example |
---|---|---|---|
|
|
|
A string indicating the version of the deployed service |
Deployed version of your service.
Defaults to git rev-parse --verify HEAD
.
environment
editEnvironment | Config key |
Default | Example |
---|---|---|---|
|
|
From |
|
The name of the environment this service is deployed in, e.g. "production" or "staging".
Defaults to ENV['RAILS_ENV'] || ENV['RACK_ENV']
.
enabled-environments
editEnvironment | Config key |
Default |
---|---|---|
|
|
|
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.
framework_name
editEnvironment | Config key |
Default |
---|---|---|
|
|
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
editEnvironment | Config key |
Default |
---|---|---|
|
|
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
.
hostname
editEnvironment | Config key |
Default | Example |
---|---|---|---|
|
|
|
|
The host name to use when sending error and transaction data to the APM server.
log_path
editEnvironment | Config key |
Default | Example |
---|---|---|---|
|
|
|
|
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.
log_level
editEnvironment | Config key |
Default |
---|---|---|
|
|
|
By default Elastic APM logs to stdout
or uses Rails.log
when used with Rails.
logger
editEnvironment | Config key |
Default | Example |
---|---|---|---|
N/A |
|
Depends |
|
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
.
source_lines_error_app_frames
editsource_lines_error_library_frames
editsource_lines_span_app_frames
editsource_lines_span_library_frames
editEnvironment |
|
Default |
|
|
|
|
|
|
|
|
|
|
|
|
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
editEnvironment |
|
Default |
|
|
|
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
.
max_queue_size
editEnvironment |
|
Default |
|
|
|
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.
This setting is useful to limit memory consumption if you experience a sudden spike of traffic.
flush_interval
editEnvironment |
|
Default |
|
|
|
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.
transaction_sample_rate
editEnvironment |
|
Default |
|
|
|
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.
transaction_max_spans
editEnvironment |
|
Default |
|
|
|
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.
verify_server_cert
editEnvironment |
|
Default |
|
|
|
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
.
disabled_spies
editEnvironment | Config key |
Default |
---|---|---|
|
|
|
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
.
instrumented_rake_tasks
editEnvironment | Config key |
Default | Example |
---|---|---|---|
|
|
|
|
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.
default_tags
editEnvironment | Config key |
Default | Example |
---|---|---|---|
|
|
|
|
Add default tags to add to every transaction.
Be aware that tags are indexed in Elasticsearch. Using too many unique keys will result in Mapping explosion.
custom_key_filters
editEnvironment | Config key |
Default | Example |
---|---|---|---|
|
|
|
|
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/]
ignore_url_patterns
editEnvironment | Config key |
Default | Example |
---|---|---|---|
|
|
|
|
Use this option to ignroe 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/]
filter_exception_types
editEnvironment |
|
Default |
Example |
N/A |
|
|
|
Use this to filter error tracking for specific error constants.
disable_send
editEnvironment |
|
Default |
N/A |
|
|
Disables sending payloads to APM Server.