Log correlationedit

Log correlation allows you to navigate to all logs belonging to a particular trace and vice-versa: for a specific log, see in which context it has been logged and which parameters the user provided.

Starting in APM agent version 1.30.0, log correlation is enabled by default. In previous versions, log correlation must be explicitly enabled by setting the enable_log_correlation configuration variable to true.

Here are the 3 main steps required to implement log correlation with a Java application.

Step 1: Inject ID fields in logsedit

In order to correlate logs from your application with transactions captured by the Elastic APM Java Agent, the agent injects the following IDs into slf4j-MDC-equivalents of supported logging frameworks:

For plain text logs, the pattern layout of your logging configuration needs to be modified to write the MDC values into log files. If you are using Logback or log4j, add %X to the format to log all MDC values or %X{trace.id} to only log the trace id.

If your application is already using Java ECS logging or the log_ecs_reformatting configuration option to write ECS formatted logs, then there is no change required as the IDs will be automatically added to the ECS-formatted log lines. In this case You can then skip directly to step 3.

Step 2: Reformat plain text logsedit

This step is optional, but strongly recommended as reformatting makes Elasticsearch ingestion simpler if they are in ECS JSON format.

If you are using Java ECS logging, there’s nothing to do in this step as the application logs will already be formatted in ECS format.

The easiest way to reformat application logs is to use the experimental log_ecs_reformatting configuration option as it will allow to reformat logs without modifying the application nor its configuration.

the log_ecs_reformatting configuration is still experimental and may change in the future. However, since it is effortless, it may be your first choice to try out.

By default, application logs are written in plain-text format, thus they have to be parsed prior storage in Elasticsearch, this transformation is usually implemented through an ingest pipeline and a grok processor or with a combination of Filebeat and Logstash configuration.

With plain-text log files, this parsing will have to extract the IDs added in step 1 from the plain-text log file and store them to their respective fields: transaction.id, trace.id and error.id.

Step 3: Ingest your application logs into Elasticsearchedit

Ingestion of log files into Elasticsearch is the last step and is common to all platforms, thus the general guide should be followed for instructions.

The Filebeat configuration will differ depending on the log file format:

  • for ECS-formatted log files, the JSON logs configuration should be used
  • for plain-text log files, the Parsing unstructured logs configuration should be used.