Logging configuration optionsedit

log_leveledit

Sets the logging level for the agent. This option is case-insensitive.

CRITICAL is a valid option, but it is mapped to ERROR; WARN and WARNING are equivalent; OFF is only available since version 1.16.0

dynamic config

Valid options: OFF, ERROR, CRITICAL, WARN, WARNING, INFO, DEBUG, TRACE

Default Type Dynamic

INFO

LogLevel

true

Java System Properties Property file Environment

elastic.apm.log_level

log_level

ELASTIC_APM_LOG_LEVEL

log_fileedit

Sets the path of the agent logs. The special value _AGENT_HOME_ is a placeholder for the folder the elastic-apm-agent.jar is in. Example: _AGENT_HOME_/logs/elastic-apm.log

When set to the special value System.out, the logs are sent to standard out.

When logging to a file, the log will be formatted in new-line-delimited JSON. When logging to std out, the log will be formatted as plain-text.

Default Type Dynamic

System.out

String

false

Java System Properties Property file Environment

elastic.apm.log_file

log_file

ELASTIC_APM_LOG_FILE

enable_log_correlationedit

A boolean specifying if the agent should integrate into SLF4J’s MDC to enable trace-log correlation. If set to true, the agent will set the trace.id and transaction.id for the currently active spans and transactions to the MDC. Since version 1.16.0, the agent also adds error.id of captured error to the MDC just before the error message is logged. See Log correlation for more details.

While it’s allowed to enable this setting at runtime, you can’t disable it without a restart.

dynamic config

Default Type Dynamic

false

Boolean

true

Java System Properties Property file Environment

elastic.apm.enable_log_correlation

enable_log_correlation

ELASTIC_APM_ENABLE_LOG_CORRELATION

log_ecs_reformatting ( [1.22.0] Added in 1.22.0. experimental)edit

This feature is currently experimental, which means it is disabled by default and it is not guaranteed to be backwards compatible in future releases.

Specifying whether and how the agent should automatically reformat application logs into ECS-compatible JSON, suitable for ingestion into Elasticsearch for further Log analysis. This functionality is available for log4j1, log4j2 and Logback. Once this option is enabled with any valid option, log correlation will be activated as well, regardless of the enable_log_correlation configuration.

Available options:

  • OFF - application logs are not reformatted.
  • SHADE - agent logs are reformatted and "shade" ECS-JSON-formatted logs are automatically created in addition to the original application logs. Shade logs will have the same name as the original logs, but with the ".ecs.json" extension instead of the original extension. Destination directory for the shade logs can be configured through the log_ecs_reformatting_dir configuration. Shade logs do not inherit file-rollover strategy from the original logs. Instead, they use their own size-based rollover strategy according to the log_file_size configuration and while allowing maximum of two shade log files.
  • REPLACE - similar to SHADE, but the original logs will not be written. This option is useful if you wish to maintain similar logging-related overhead, but write logs to a different location and/or with a different file extension.
  • OVERRIDE - same log output is used, but in ECS-compatible JSON format instead of the original format.

while SHADE and REPLACE options are only relevant to file log appenders, the OVERRIDE option is also valid for other appenders, like System out and console

dynamic config

Valid options: OFF, SHADE, REPLACE, OVERRIDE

Default Type Dynamic

OFF

LogEcsReformatting

true

Java System Properties Property file Environment

elastic.apm.log_ecs_reformatting

log_ecs_reformatting

ELASTIC_APM_LOG_ECS_REFORMATTING

log_ecs_formatter_allow_listedit

Only formatters that match an item on this list will be automatically reformatted to ECS when log_ecs_reformatting is set to any option other than OFF. A formatter is the logging-framework-specific entity that is responsible for the formatting of log events. For example, in log4j it would be a Layout implementation, whereas in Logback it would be an Encoder implementation.

This option supports the wildcard *, which matches zero or more characters. Examples: /foo/*/bar/*/baz*, *foo*. Matching is case insensitive by default. Prepending an element with (?-i) makes the matching case sensitive.

Default Type Dynamic

*PatternLayout*, org.apache.log4j.SimpleLayout, ch.qos.logback.core.encoder.EchoEncoder

List

false

Java System Properties Property file Environment

elastic.apm.log_ecs_formatter_allow_list

log_ecs_formatter_allow_list

ELASTIC_APM_LOG_ECS_FORMATTER_ALLOW_LIST

log_ecs_reformatting_diredit

If log_ecs_reformatting is set to SHADE or REPLACE, the shade log files will be written alongside the original logs in the same directory by default. Use this configuration in order to write the shade logs into an alternative destination. Omitting this config or setting it to an empty string will restore the default behavior. If relative path is used, this path will be used relative to the original logs directory.

Default Type Dynamic

<none>

String

false

Java System Properties Property file Environment

elastic.apm.log_ecs_reformatting_dir

log_ecs_reformatting_dir

ELASTIC_APM_LOG_ECS_REFORMATTING_DIR

log_file_size ( [1.17.0] Added in 1.17.0. )edit

The size of the log file.

The agent always keeps one history file so that the max total log file size is twice the value of this setting.

Default Type Dynamic

50mb

ByteValue

false

Java System Properties Property file Environment

elastic.apm.log_file_size

log_file_size

ELASTIC_APM_LOG_FILE_SIZE

log_format_sout ( [1.17.0] Added in 1.17.0. )edit

Defines the log format when logging to System.out.

When set to JSON, the agent will format the logs in an ECS-compliant JSON format where each log event is serialized as a single line.

Valid options: PLAIN_TEXT, JSON

Default Type Dynamic

PLAIN_TEXT

LogFormat

false

Java System Properties Property file Environment

elastic.apm.log_format_sout

log_format_sout

ELASTIC_APM_LOG_FORMAT_SOUT

log_format_file ( [1.17.0] Added in 1.17.0. )edit

Defines the log format when logging to a file.

When set to JSON, the agent will format the logs in an ECS-compliant JSON format where each log event is serialized as a single line.

Valid options: PLAIN_TEXT, JSON

Default Type Dynamic

PLAIN_TEXT

LogFormat

false

Java System Properties Property file Environment

elastic.apm.log_format_file

log_format_file

ELASTIC_APM_LOG_FORMAT_FILE