Configuration
editConfiguration
editUtilize configuration options to adapt the Elastic APM agent to your needs.
One way to configure settings is with the php.ini
file:
elastic_apm.server_url=http://localhost:8200 elastic_apm.service_name="My service"
The agent can also be configured using environment variables:
export ELASTIC_APM_SERVER_URL="http://localhost:8200" export ELASTIC_APM_SERVICE_NAME="My service"
If you use environment variables to configure the agent, make sure the process running your PHP code inherits those environment variables after they were set.
Elasticsearch Service on Elastic Cloud
editThe agent can be configured to send data to an Elasticsearch Service APM instance by
setting the server_url
and secret_token
options
to the corresponding values found in the APM & Fleet section of Elastic Cloud.
Configure the agent, for example via php.ini
:
elastic_apm.server_url=APM_SERVER_URL elastic_apm.secret_token=TOKEN elastic_apm.service_name=SERVICE_NAME
Control the amount of APM data emitted by the agent
editThe following configuration settings control the amount of APM data emitted by the agent. They can be tuned to reduce the agent overhead on the monitored application, network utilization, and the amount of storage required by Elasticsearch.
Logging
editConfiguration settings described in this section are related to logs emitted by the agent itself and not the logs emitted by the monitored application. The intended use case for these configuration settings is for the agent’s supportability. The logs emitted by the agent are not stored in Elasticsearch by default, so reducing the level for these logs will not reduce the amount of storage used in Elasticsearch-- see Control the amount of APM data emitted by the agent instead.
The easiest way to configure the logging is by using the log_level_syslog
configuration option.
Available log levels are:
OFF CRITICAL ERROR WARNING INFO DEBUG TRACE
For example, if you specify a WARNING
log level, only log records with levels WARNING
, ERROR
, and CRITICAL
will be emitted.
OFF
is only used to disable agent logging.
The agent supports logging to the following sinks: syslog and stderr.
Control the level of logging for individual sinks with the
log_level_syslog
and log_level_stderr
options.
When a sink-specific logging level is not explicitly set, the fallback setting
log_level
will be used.
For example, the following configuration sets the log level to WARNING
for all the sinks:
elastic_apm.log_level=WARNING
Alternatively, the following configuration sets log level to WARNING
for all the sinks
except for syslog
, where the log level is set to TRACE
.
elastic_apm.log_level=WARNING elastic_apm.log_level_syslog=TRACE
PHP errors as APM error events
editThe agent automatically creates APM error events for PHP errors triggered by the monitored application.
APM error events are created only for PHP errors which level is included in
PHP error_reporting
setting.
In addition capture_errors
configuration option controls
if the agent captures any PHP errors.
Duration format
editThe duration format is used for configuration options like timeouts. The units are provided as a suffix either directly after the number or separated by any amount of whitespace. The units are case insensitive so they can be provided in either lower, upper or even mixed case.
Supported units:
-
ms
(milliseconds) -
s
(seconds) -
m
(minutes)
Example: 5m
(interpreted as 5 minutes) or 10 mS
(interpreted as 10 milliseconds).
Default units: Each configuration option with value specifiying a duration has default units.
This allows omitting the units in option value.
For example if option’s default units are s
(seconds) then value 10
is interpreted as 10 seconds.
Different configuration options might have different default units so it’s always preferable to provide units explicitly.
Size format
editThe size format is used for options such as maximum buffer sizes. The units are provided as a suffix either directly after the number or separated by any amount of whitespace. The units are case insensitive so they can be provided in either lower, upper or even mixed case.
Supported units:
- B (bytes)
- KB (kilobytes)
- MB (megabytes)
- GB (gigabytes)
We use the power-of-two sizing convention, e.g. 1KB = 1024B.
Example: 34KB
(interpreted as 34 kilobytes) or 78 mB
(interpreted as 78 megabytes).
Default units: Each configuration option with value specifiying a size has default units.
This allows omitting the units in option value.
For example if option’s default units are KB
(kilobytes) then value 10
is interpreted as 10 kilobytes.
Different configuration options might have different default units so it’s always preferable to provide units explicitly.
Wildcard
editSome options (for example url_groups
) support use of wildcard.
A valid value for such configuration options is a comma separated list of wildcard expressions.
Only the wildcard *
, which matches zero or more characters, is supported.
Examples: *foo*
, /foo/*/bar, /*/baz*
.
Matching is case insensitive by default.
Prepending an element with (?-i)
makes the matching case sensitive.
For example (?-i)/bar, /foo
matches /bar
and /FOO
but it doesn’t match /BAR
.
On the other hand (?-i)/bar, (?-i)/foo
matches /bar
and /foo
but doesn’t match neither /BAR
nor /FOO
.
Whitespace around commas separating wildcard expressions in the list is ignored.
For example foo , bar
is the same as foo,bar
.
On the other hand whitespace inside wildcard expressions is significant.
For example *a b*
matches a string only if it contains a
followed by space and then b
.
The input string is matched against wildcard expressions in the order they are listed and the first expression that matches is selected.
When configuration option is intended to matched against a input URL
(for example url_groups
and transaction_ignore_urls
)
only path part of the URL is tested against wildcard expressions.
Other parts of the URL (such as query string, etc.) are not taken into account
so including them in the wildcard expressions might lead to unexpected result.
For example /user/*
matches http://my_site.com/user/Alice?lang=en
while /user/*?lang=*
does not match http://my_site.com/user/Alice?lang=en