Add APM user settingsedit
Change how the APM Server runs by providing your own user settings. User settings are appended to the apm-server.yml
configuration file for your instance and provide custom configuration options.
Some settings that could break your cluster if set incorrectly are blacklisted. Review the list of settings that are generally safe in cloud environments. For detailed information about APM settings, see the APM documentation.
To add user settings:
- Log in to the Elasticsearch Add-On for Heroku console.
-
On the deployments page, select your deployment.
Narrow your deployments by name, ID, or choose from several other filters. To customize your view, use a combination of filters, or change the format from a grid to a list.
- From your deployment menu, go to the Edit page.
- At the bottom of the APM instance, expand the User settings overrides caret.
- Update the user settings.
- Click Save changes.
If a setting is not supported by Elasticsearch Add-On for Heroku, you will get an error message when you try to save.
Supported APM settingsedit
Elasticsearch Add-On for Heroku supports the following APM settings.
For version 7.9 and later:
This stack version includes all of the settings from 7.7 and the following:
-
apm-server.ilm.setup.mapping
-
ILM policies now support configurable index suffixes. You can append the
policy_name
with anindex_suffix
based on theevent_type
, which can be one ofspan
,transaction
,error
, ormetric
.
For version 7.7 and later:
This stack version includes all of the settings from 7.6 and the following:
-
apm-server.rum.allow_headers
- List of Access-Control-Allow-Headers to allow RUM requests, in addition to "Content-Type", "Content-Encoding", and "Accept".
For version 7.6 and later:
This stack version includes all of the settings from 7.5 and the following:
-
apm-server.api_key.enabled
-
Enabled by default. For any requests where APM Server accepts a
secret_token
in the authorization header, it now alternatively accepts an API Key. This feature is currently experimental. -
apm-server.api_key.limit
- Configure how many unique API keys are allowed per minute. Should be set to at least the amount of different API keys used in monitored services. Default value is 100.
For version 7.5 and later:
This stack version includes all of the settings from 7.4 and the following:
-
apm-server.ilm.setup.enabled
- When enabled, APM Server creates aliases, event type specific settings and ILM policies. If disabled, event type specific templates need to be managed manually.
-
apm-server.ilm.setup.overwrite
-
Set to
true
to apply custom policies and to properly overwrite templates when switching between using ILM and not using ILM. -
apm-server.ilm.setup.require_policy
-
Set to
false
when policies are set up outside of APM Server but referenced in this configuration. -
apm-server.ilm.setup.policies
-
Array of ILM policies. Each entry has a
name
and apolicy
. -
apm-server.ilm.setup.mapping
-
Array of mappings of ILM policies to event types. Each entry has a
policy_name
and anevent_type
, which can be one ofspan
,transaction
,error
, ormetric
.
For version 7.4 and later:
This stack version includes all of the settings from 7.3 and the following:
-
apm-server.rum.source_mapping.enabled
- When events are monitored using the RUM agent, APM Server tries to apply source mapping by default. This configuration option allows you to disable source mapping on stack traces.
-
apm-server.rum.source_mapping.cache.expiration
- Sets how long a source map should be cached before being refetched from Elasticsearch. Default value is 5m.
For version 7.3 and later:
This stack version includes all of the settings from 7.2 and the following:
-
output.elasticsearch.pipeline
-
APM comes with a default pipeline definition. This allows overriding it. To disable, you can set
pipeline: _none
-
apm-server.agent.config.cache.expiration
-
When using APM agent configuration, determines cache expiration from information fetched from Kibana. Defaults to
30s
.
For version 7.2 and later:
This stack version includes all of the settings from 6.5 and the following:
-
apm-server.ilm.enabled
-
Enables index lifecycle management (ILM) for the indices created by the APM Server. Defaults to
false
. If you’re updating an existing APM Server, you must also setsetup.template.overwrite: true
. If you don’t, the index template will not be overridden and ILM changes will not take effect.
For version 6.5 and later:
This stack version includes all of the settings from 6.4 and the following:
-
apm-server.max_event_size
-
Specifies the maximum allowed size of an event for processing by the server, in bytes. Defaults to
307200
. -
output.elasticsearch.pipelines
- Adds an array for pipeline selector configurations that support conditionals, format string-based field access, and name mappings used to parse data using ingest node pipelines.
-
apm-server.register.ingest.pipeline.enabled
-
Loads the pipeline definitions to Elasticsearch when the APM Server starts up. Defaults to
false
. -
apm-server.register.ingest.pipeline.overwrite
-
Overwrites the existing pipeline definitions in Elasticsearch. Defaults to
true
. -
apm-server.rum.event_rate.lru_size
-
Defines the number of unique IP addresses that can be tracked in the LRU cache, which keeps a rate limit for each of the most recently seen IP addresses. Defaults to
1000
. -
apm-server.rum.event_rate.limit
-
Sets the rate limit per second for each IP address for events sent to the APM Server v2 RUM endpoint. Defaults to
300
.
With the version 6.5 release, we recommend verifying that your agents continue to be compatible with your APM Server.
For version 6.4 and later:
-
apm-server.rum.enabled
-
Enables/disables Real User Monitoring (RUM) support. Defaults to
true
(enabled). -
apm-server.rum.allow_origins
-
Specifies a list of permitted origins from user agents. The default is
*
, which allows everything. -
apm-server.rum.library_pattern
-
Differentiates library frames against specific attributes. The default value is
"node_modules|bower_components|~"
. -
apm-server.rum.exclude_from_grouping
-
Configures the RegExp to be matched against a stacktrace frame’s
file_name
. -
apm-server.rum.rate_limit
-
Sets the rate limit per second for each IP address for requests sent to the RUM endpoint. Defaults to
10
. -
apm-server.capture_personal_data
-
When set to
true
, the server captures the IP of the instrumented service and its User Agent. Enabled by default. -
setup.template.settings.index.number_of_shards
- Specifies the number of shards for the Elasticsearch template.
-
setup.template.settings.index.number_of_replicas
- Specifies the number of replicas for the Elasticsearch template.
For version 6.3:
-
apm-server.frontend.enabled
- Enables/disables frontend support.
-
apm-server.frontend.allow_origins
-
Specifies the comma-separated list of permitted origins from user agents. The default is
*
, which allows everything. -
apm-server.frontend.library_pattern
-
Differentiates library frames against specific attributes. The default value is
"node_modules|bower_components|~"
. -
apm-server.frontend.exclude_from_grouping
-
Configures the RegExp to be matched against a stacktrace frame’s
file_name
. -
apm-server.frontend.rate_limit
-
Sets the rate limit per second per IP address for requests sent to the frontend endpoint. Defaults to
10
. -
apm-server.capture_personal_data
-
When set to
true
, the server captures the IP address of the instrumented service and its User Agent. Enabled by default. -
max_procs
- Max number of CPUs used simultaneously. Defaults to the number of logical CPUs available.
-
setup.template.enabled
- Set to false to disable loading of Elasticsearch templates used for APM indices. If set to false, you must load the template manually.
-
setup.template.name
-
Name of the template. Defaults to
apm-server
. -
setup.template.pattern
-
The template pattern to apply to the default index settings. Default is
apm-*
-
setup.template.settings.index.number_of_shards
- Specifies the number of shards for the Elasticsearch template.
-
setup.template.settings.index.number_of_replicas
- Specifies the number of replicas for the Elasticsearch template.
-
output.elasticsearch.bulk_max_size
-
Maximum number of events to bulk together in a single Elasticsearch bulk API request. By default, this number changes based on the size of the instance and server version:
Instance size Version 6.5+ Version <6.5 512MB
267
53
1GB
381
68
2GB
533
95
4GB
762
70
8GB
1067
96
-
output.elasticsearch.indices
- Array of index selector rules supporting conditionals and formatted string.
-
output.elasticsearch.index
-
The index to write the events to. If changed,
setup.template.name
andsetup.template.pattern
must be changed accordingly. -
output.elasticsearch.worker
-
Maximum number of concurrent workers publishing events to Elasticsearch. By default, this number changes based on the size of the instance and server version:
Instance size Version 6.5+ Version <6.5 512MB
5
5
1GB
7
5
2GB
10
5
4GB
14
10
8GB
20
10
-
queue.mem.events
-
Maximum number of events to concurrently store in the internal queue. By default, this number changes based on the size of the instance and server version:
Instance size Version 6.5+ Version <6.5 512MB
2000
266
1GB
4000
339
2GB
8000
476
4GB
16000
699
8GB
32000
958
-
queue.mem.flush.min_events
- Minimum number of events to have before pushing them to Elasticsearch. By default, this number changes based on the size of the instance.
-
queue.mem.flush.timeout
-
Maximum duration before sending the events to the output if the
min_events
is not crossed.
- Logging settings
-
logging.level
- Specifies the minimum log level. One of debug, info, warning, or error. Defaults to info.
-
logging.selectors
- The list of debugging-only selector tags used by different APM Server components. Use * to enable debug output for all components. For example, add publish to display all the debug messages related to event publishing.
-
logging.metrics.enabled
- If enabled, APM Server periodically logs its internal metrics that have changed in the last period. Defaults to true.
-
logging.metrics.period
- The period after which to log the internal metrics. Defaults to 30s.
To change logging settings you must first enable deployment logging.