ifdef::env-github[] NOTE: For the best reading experience, please view this documentation at https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html[elastic.co] endif::[] [[configuration]] == 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: [source,yaml] ---- server_url: 'http://localhost:8200' secret_token: <%= ENV["VERY_SECRET_TOKEN"] %> ---- 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 [float] === Ruby on Rails When using Rails it's also possible to specify options inside `config/application.rb`: [source,ruby] ---- # config/application.rb config.elastic_apm.service_name = 'MyApp' ---- [float] === Sinatra and Rack When using APM with Sinatra and Rack you can configure it when starting the agent: [source,ruby] ---- # config.ru or similar ElasticAPM.start( app: MyApp, service_name: 'SomeOtherName' ) ---- Alternatively, you can use the `ElasticAPM::Sinatra.start` API. [source,ruby] ---- # config.ru or similar ElasticAPM::Sinatra.start( MyApp, service_name: 'SomeOtherName' ) ---- See <>. [float] === Grape and Rack When using APM with Grape and Rack (without Rails), you can configure it when starting the agent: [source,ruby] ---- # config.ru or similar ElasticAPM::Grape.start( MyApp, service_name: 'SomeOtherName' ) ---- 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_SANITIZE_FIELD_NAMES="a,b" # => [/a/, /b/]`. [float] [[config-config-file]] ==== `config_file` [options="header"] |============ | 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: [source,ruby] ---- secret_token: <%= ENV['VERY_SECRET_TOKEN'] %> ---- [float] [[config-server-url]] ==== `server_url` [options="header"] |============ | 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. [float] [[config-secret-token]] ==== `secret_token` [options="header"] |============ | 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: [source,bash] ---- 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` |============ | 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`. [float] [[config-api-buffer-size]] ==== `api_buffer_size` |============ | 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 <> or it could mean the agent has trouble connecting to APM Server. The <> should tell you what went wrong. [float] [[config-api-request-size]] ==== `api_request_size` |============ | 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 *<>*. [float] [[config-api-request-time]] ==== `api_request_time` |============ | 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 *<>*. [float] [[config-breakdown-metrics]] ==== `breakdown-metrics` |============ | 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. NOTE: This feature requires APM Server and Kibana >= 7.3. [float] [[config-capture-body]] ==== `capture_body` |============ | Environment | `Config` key | Default | Example | | `ELASTIC_APM_CAPTURE_BODY` | `capture_body` | `"off"` | `"all"` |============ 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]`. WARNING: 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. [float] [[config-capture-headers]] ==== `capture_headers` |============ | Environment | `Config` key | Default | `ELASTIC_APM_CAPTURE_HEADERS` | `capture_headers` | `true` |============ Whether or not to attach the request headers to transactions and errors. [float] [[config-capture-env]] ==== `capture_env` |============ | Environment | `Config` key | Default | `ELASTIC_APM_CAPTURE_ENV` | `capture_env` | `true` |============ Whether or not to attach `ENV` from Rack to transactions and errors. [float] [[config-central-config]] ==== `central_config` |============ | Environment | `Config` key | Default | `ELASTIC_APM_CENTRAL_CONFIG` | `central_config` | `true` |============ Enable {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. NOTE: This feature requires APM Server v7.3 or later and that the APM Server is configured with `kibana.enabled: true`. [float] [[config-custom-key-filters]] ==== `custom_key_filters` deprecated:[3.5.0,See <> instead.] [options="header"] |============ | Environment | `Config` key | Default | Example | `ELASTIC_APM_CUSTOM_KEY_FILTERS` | `custom_key_filters` | `[]` | `['MyAuthHeader']` |============ Elastic APM strips https://github.com/elastic/apm-agent-ruby/blob/1.x/lib/elastic_apm/filters/secrets_filter.rb[ 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/]` NOTE: This option is being removed. See <> instead. [float] [[config-default-tags]] ==== `default_tags` [options="header"] |============ | 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`. WARNING: Be aware that labels are indexed in Elasticsearch. Using too many unique keys will result in *https://www.elastic.co/blog/found-crash-elasticsearch#mapping-explosion[Mapping explosion]*. NOTE: `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`. [options="header"] |============ | 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`. WARNING: Be aware that tags are indexed in Elasticsearch. Using too many unique keys will result in *https://www.elastic.co/blog/found-crash-elasticsearch#mapping-explosion[Mapping explosion]*. NOTE: `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`. [float] [[config-disable_metrics]] ==== `disable_metrics` |============ | 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. [float] [[config-disable-send]] ==== `disable_send` |============ | Environment | `Config` key | Default | `ELASTIC_APM_DISABLE_SEND` | `disable_send` | `false` |============ Disables sending payloads to APM Server. [float] [[config-disable-start-message]] ==== `disable_start_message` |============ | Environment | `Config` key | Default | `ELASTIC_APM_DISABLE_START_MESSAGE` | `disable_start_message` | `false` |============ Disables the agent's startup message announcing itself. [float] [[config-disabled-instrumentations]] ==== `disable_instrumentations` [options="header"] |============ | 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`. [float] [[config-environment]] ==== `environment` [options="header"] |============ | 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 {apm-app-ref}/filters.html#environment-selector[environment selector] in the APM app for more information. Defaults to `ENV['RAILS_ENV'] || ENV['RACK_ENV']`. NOTE: 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. [float] [[config-filter-exception-types]] ==== `filter_exception_types` |============ | Environment | `Config` key | Default | Example | N/A | `filter_exception_types` | `[]` | `[MyApp::Errors::IgnoredError]` |============ Use this to filter error tracking for specific error constants. [float] [[config-framework-name]] ==== `framework_name` [options="header"] |============ | 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`. [float] [[config-framework-version]] ==== `framework_version` [options="header"] |============ | 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`. [float] [[config-global-labels]] ==== `global_labels` [options="header"] |============ | 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[,...]]. NOTE: 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. [float] [[config-hostname]] ==== `hostname` [options="header"] |============ | 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. [float] [[config-custom-ignore-url-patterns]] ==== `ignore_url_patterns` [options="header"] |============ | 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 <>_. 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/]` [float] [[config-instrument]] ==== `instrument` [options="header"] |============ | Environment | `Config` key | Default | Example | `ELASTIC_APM_INSTRUMENT` | `instrument` | `true` | `0` |============ Use this option to ignore certain URL patterns eg. healthchecks or admin sections. [float] [[config-instrumented-rake-tasks]] ==== `instrumented_rake_tasks` [options="header"] |============ | 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. [float] [[config-log-level]] ==== `log_level` [options="header"] |============ | 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. [float] [[config-log-path]] ==== `log_path` [options="header"] |============ | 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. [float] [[config-logger]] ==== `logger` [options="header"] |============ | 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`. [float] [[config-metrics-interval]] ==== `metrics_interval` [options="header"] |============ | 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`. [float] [[config-pool-size]] ==== `pool_size` [options="header"] |============ | 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. [float] [[config-proxy-address]] ==== `proxy_address` [options="header"] |============ | 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 https://github.com/httprb/http/wiki/Proxy-Support[Http.rb's docs]. [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` [options="header"] |============ | 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. [float] [[config-service-version]] ==== `service_version` [options="header"] |============ | 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`. [float] [[config-source-lines-error-app-frames]] ==== `source_lines_error_app_frames` [float] [[config-source-lines-error-library-frames]] ==== `source_lines_error_library_frames` [float] [[config-source-lines-span-app-frames]] ==== `source_lines_span_app_frames` [float] [[config-source-lines-span-library-frames]] ==== `source_lines_span_library_frames` |============ | 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. [float] [[config-span-frames-min-duration-ms]] ==== `span_frames_min_duration` |============ | 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 *<>*. [float] [[config-ssl-ca-cert]] ==== `server_ca_cert` [options="header"] |============ | Environment | `Config` key | Default | Example | `ELASTIC_APM_SERVER_CA_CERT` | `server_ca_cert` | `nil` | `'/path/to/ca.pem'` |============ The path to a custom CA certificate for connecting to APM Server. [float] [[config-stack-trace-limit]] ==== `stack_trace_limit` [options="header"] |============ | Environment | `Config` key | Default | `ELASTIC_APM_STACK_TRACE_LIMIT` | `stack_trace_limit` | `999999` |============ The maximum number of stack trace lines per span/error. [float] [[config-transaction-max-spans]] ==== `transaction_max_spans` |============ | 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. [float] [[config-transaction-sample-rate]] ==== `transaction_sample_rate` |============ | 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. [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` |============ | 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`. [float] [[config-formats]] === Configuration formats Some options require a unit, either duration or size. These need to be provided in a specific format. [float] [[config-format-duration]] ==== Duration format 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) [float] [[config-format-size]] ==== Size format 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`