Edit APM user settingsedit

Change how Elastic APM runs by providing your own user settings. Starting in Elastic Stack version 8.0, how you change APM settings and the settings that are available to you depend on how you spin up Elastic APM. There are two modes:

Fleet-managed APM integration

New deployments created in Elastic Stack version 8.0 and later will be managed by Fleet.

Check APM integration input settings for information on how to configure Elastic APM in this mode.

Standalone APM Server (legacy)

Deployments created prior to Elastic Stack version 8.0 are in legacy mode. Upgrading to or past Elastic Stack 8.0 will not remove you from legacy mode.

Check Edit standalone APM settings (legacy) and Supported standalone APM settings (legacy) for information on how to configure Elastic APM in this mode.

To learn more about the differences between these modes, or to switch from Standalone APM Server (legacy) mode to Fleet-managed, check Switch to the Elastic APM integration.

Edit standalone APM settings (legacy)edit

User settings are appended to the apm-server.yml configuration file for your instance and provide custom configuration options.

To add user settings:

  1. Log in to the Elasticsearch Add-On for Heroku console.
  2. 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.

  3. From your deployment menu, go to the Edit page.
  4. In the APM section, select Edit user settings. (For existing deployments with user settings, you may have to expand the Edit apm-server.yml caret instead.)
  5. Update the user settings.
  6. Select 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 standalone APM settings (legacy)edit

Elasticsearch Add-On for Heroku supports the following setting when running APM in standalone mode (legacy).

Some settings that could break your cluster if set incorrectly are blocklisted. The following settings are generally safe in cloud environments. For detailed information about APM settings, check the APM documentation.

For version 7.17 and later:

This stack version includes all of the settings from 7.16 and the following:

Allow anonymous access only for specified agents and/or services. This is primarily intended to allow limited access for untrusted agents, such as Real User Monitoring. Anonymous auth is automatically enabled when RUM is enabled. Otherwise, anonymous auth is disabled. When anonymous auth is enabled, only agents matching allow_agent and services matching allow_service are allowed. See below for details on default values for these.

apm-server.auth.anonymous.allow_agent
Allow anonymous access only for specified agents.
apm-server.auth.anonymous.allow_service
Allow anonymous access only for specified service names. By default, all service names are allowed. This will be replacing the config option apm-server.rum.allow_service_names from 8.0 on.
apm-server.auth.anonymous.rate_limit.event_limit
Rate limiting is defined per unique client IP address, for a limited number of IP addresses. Sites with many concurrent clients should consider increasing this limit. Defaults to 1000. This will be replacing the config option`apm-server.rum.event_rate.limit` from 8.0 on.
apm-server.auth.anonymous.rate_limit.ip_limit
Defines the maximum amount of events allowed per IP per second. Defaults to 300. The overall maximum event throughput for anonymous access is (event_limit * ip_limit). This will be replacing the config option apm-server.rum.event_rate.lru_size from 8.0 on.
apm-server.auth.api_key.enabled
Enables agent authorization using Elasticsearch API Keys. This will be replacing the config option apm-server.api_key.enabled from 8.0 on.
apm-server.auth.api_key.limit
Restrict how many unique API keys are allowed per minute. Should be set to at least the amount of different API keys configured in your monitored services. Every unique API key triggers one request to Elasticsearch. This will be replacing the config option apm-server.api_key.limit from 8.0 on.

For version 7.14 and later:

This stack version includes all of the settings from 7.13 and the following:

apm-server.aggregation.transactions.*
This functionality is experimental and may be changed or removed completely in a future release. When enabled, APM Server produces transaction histogram metrics that are used to power the APM app. Shifting this responsibility from APM app to APM Server results in improved query performance and removes the need to store unsampled transactions.

For version 7.13 and later:

This stack version includes all of the settings from 7.12 and the following:

apm-server.default_service_environment
If specified, APM Server will record this value in events which have no service environment defined, and add it to agent configuration queries to Kibana when none is specified in the request from the agent.
apm-server.rum.allow_service_names
A list of service names to allow, to limit service-specific indices and data streams created for unauthenticated RUM events. If the list is empty, any service name is allowed.

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 an index_suffix based on the event_type, which can be one of span, transaction, error, or metric.

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".
setup.template.append_fields
A list of fields to be added to the Elasticsearch template and Kibana data view (formerly index pattern).

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.
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 a policy.
apm-server.ilm.setup.mapping
Array of mappings of ILM policies to event types. Each entry has a policy_name and an event_type, which can be one of span, transaction, error, or metric.

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 set setup.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 and setup.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.