Configuration referenceedit

api_keyedit

Environment variable name Option name in php.ini

ELASTIC_APM_API_KEY

elastic_apm.api_key

Default Type

None

String

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

api_key is an alternative to secret_token. If both secret_token and api_key are configured, then api_key has precedence and secret_token is ignored.

This feature is fully supported in the APM Server versions >= 7.6.

The api_key value is sent as plain-text in every request to the server, so you should also secure your communications using HTTPS. Unless you do so, your API Key could be observed by an attacker.

breakdown_metricsedit

Environment variable name Option name in php.ini

ELASTIC_APM_BREAKDOWN_METRICS

elastic_apm.breakdown_metrics

Default Type

true

Boolean

If this configuration option is set to true the agent will collect and report breakdown metrics (span.self_time) used for "Time spent by span type" chart. Set it to false to disable the collection and reporting of breakdown metrics, which can reduce the overhead of the agent.

This feature requires APM Server and Kibana >= 7.3.

disable_instrumentationsedit

Environment variable name Option name in php.ini

ELASTIC_APM_DISABLE_INSTRUMENTATIONS

elastic_apm.disable_instrumentations

Default Type

empty list

List of strings

A comma-separated list of wildcard expressions to match instrumentation names which should be disabled. When an instrumentation is disabled, no spans will be created for that instrumentation. An instrumentation may match more than one name - for example PDO instrumentation matches both db and pdo.

Valid instrumentation names are curl, db, http-client, pdo.

disable_sendedit

Environment variable name Option name in php.ini

ELASTIC_APM_DISABLE_SEND

elastic_apm.disable_send

Default Type

false

Boolean

If set to true, the agent will work as usual, except for any task requiring communication with the APM server. Events will be dropped and the agent won’t be able to receive central configuration, which means that any other configuration cannot be changed in this state without restarting the service. Example uses for this setting are: maintaining the ability to create traces and log trace/transaction/span IDs through the log correlation feature, and getting automatic distributed tracing via the W3C HTTP headers.

enablededit

Environment variable name Option name in php.ini

ELASTIC_APM_ENABLED

elastic_apm.enabled

Default Type

true

Boolean

Setting to false will completely disable the agent.

environmentedit

Environment variable name Option name in php.ini

ELASTIC_APM_ENVIRONMENT

elastic_apm.environment

Default Type

None

String

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 environment selector in the Kibana UI for more information.

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.

hostnameedit

Hostname variable name Option name in php.ini

ELASTIC_APM_HOSTNAME

elastic_apm.hostname

Default Type

the local machine’s host name

String

This option allows for the reported host name to be configured. If this option is not set the local machine’s host name is used.

log_leveledit

Environment variable name Option name in php.ini

ELASTIC_APM_LOG_LEVEL

elastic_apm.log_level

Default Type

None

Log level

A fallback configuration setting to control the logging level for the agent. Only used when a sink-specific option is not explicitly set. See Logging for details.

log_level_stderredit

Environment variable name Option name in php.ini

ELASTIC_APM_LOG_LEVEL_STDERR

elastic_apm.log_level_stderr

Default Type

CRITICAL

Log level

The logging level for stderr logging sink. See Logging for details.

log_level_syslogedit

Environment variable name Option name in php.ini

ELASTIC_APM_LOG_LEVEL_SYSLOG

elastic_apm.log_level_syslog

Default Type

INFO

Log level

The logging level for syslog logging sink. See Logging for details.

secret_tokenedit

Environment variable name Option name in php.ini

ELASTIC_APM_SECRET_TOKEN

elastic_apm.secret_token

Default Type

None

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.

See the relevant APM Server’s documentation on how to configure APM Server’s secret token.

Use this setting if the APM Server requires a token, like in Elasticsearch Service.

secret_token is an alternative to api_key. If both secret_token and api_key are configured then api_key has precedence and secret_token is ignored.

The secret_token is sent as plain-text in every request to the server, so you should also secure your communications using HTTPS. Unless you do so, your secret token could be observed by an attacker.

server_timeoutedit

Environment variable name Option name in php.ini

ELASTIC_APM_SERVER_TIMEOUT

elastic_apm.server_timeout

Default Type

30s

Duration

If a request sending events to the APM server takes longer than the configured timeout, the request is canceled and the events are discarded.

The value has to be provided in duration format.

This option’s default unit is s (seconds).

If the value is 0 (or 0ms, 0s, etc.) the timeout for sending events to the APM Server is disabled.

Negative values are invalid and result in the default value being used instead.

server_urledit

Environment variable name Option name in php.ini

ELASTIC_APM_SERVER_URL

elastic_apm.server_url

Default Type

http://localhost:8200

String

The URL for your APM Server. The URL must be fully qualified, including protocol (http or https) and port.

service_nameedit

Environment variable name Option name in php.ini

ELASTIC_APM_SERVICE_NAME

elastic_apm.service_name

Default Type

unknown-php-service

String

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.

The service name must conform to this regular expression: ^[a-zA-Z0-9 _-]+$. In other words, a service name must only contain characters from the ASCII alphabet, numbers, dashes, underscores, and spaces. Characters in service name that don’t match regular expression will be replaced by _ (underscore) character.

service_node_nameedit

Environment variable name Option name in php.ini

ELASTIC_APM_SERVICE_NODE_NAME

elastic_apm.service_node_name

Default Type

None

String

If it’s set, this name is used to distinguish between different nodes of a service. If it’s not set, data aggregations will be done based on the reported hostname (automatically discovered or manually configured using hostname).

service_versionedit

Environment variable name Option name in php.ini

ELASTIC_APM_SERVICE_VERSION

elastic_apm.service_version

Default Type

None

String

The version of the currently deployed service. If your deployments are not versioned, the recommended value for this field is the commit identifier of the deployed revision, e.g., the output of git rev-parse HEAD.

transaction_ignore_urlsedit

Environment variable name Option name in php.ini

ELASTIC_APM_TRANSACTION_IGNORE_URLS

elastic_apm.transaction_ignore_urls

Default Type

empty list

List of wildcard expressions

This option instructs the agent to ignore requests with certain URLs by not to creating transactions for those requests. It only affects automatic creation of transactions by the agent but user can still create transactions manually by using agent’s public API.

See Wildcard section for more details on how to use wildcard expressions.

transaction_max_spansedit

Environment variable name Option name in php.ini

ELASTIC_APM_TRANSACTION_MAX_SPANS

elastic_apm.transaction_max_spans

Default Type

500

Integer

This 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, for example, thousands of SQL queries. Setting an upper limit helps prevent overloading the Agent and APM server in these edge cases.

If the value is 0 no spans will be collected.

Negative values are invalid and result in the default value being used instead.

transaction_sample_rateedit

Environment variable name Option name in php.ini

ELASTIC_APM_TRANSACTION_SAMPLE_RATE

elastic_apm.transaction_sample_rate

Default Type

1.0

Floating-point number

By default, the agent will sample every transaction (e.g., a request to your service). To reduce overhead and storage requirements, set the sample rate to a value between 0.0 and 1.0. The agent still records the overall time and result for unsampled transactions, but not context information, labels, or spans.

verify_server_certedit

Environment variable name Option name in php.ini

ELASTIC_APM_VERIFY_SERVER_CERT

elastic_apm.verify_server_cert

Default Type

true

Boolean

By default, the agent verifies the SSL certificate if you use an HTTPS connection to the APM server. The verification can be disabled by changing this setting to false.

url_groupsedit

Environment variable name Option name in php.ini

ELASTIC_APM_URL_GROUPS

elastic_apm.url_groups

Default Type

empty list

List of wildcard expressions

With this option, you can group several URL paths together by using wildcard expressions like /user/* - this way /user/Alice and /user/Bob will be mapped to transaction name /user/*.

See Wildcard section for more details on how to use wildcard expressions.