Logs

Elastic Python APM Agent provides the following log features:

Those features are part of Application log ingestion strategies.

The ecs-logging-python library can also be used to use the ECS logging format without an APM agent. When deployed with the Python APM agent, the agent will provide log correlation IDs.

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.

The Agent provides integrations with both the default Python logging library, as well as structlog.

We use logging.setLogRecordFactory() to decorate the default LogRecordFactory to automatically add new attributes to each LogRecord object:

This factory also adds these fields to a dictionary attribute, elasticapm_labels, using the official ECS tracing fields.

You can disable this automatic behavior by using the disable_log_record_factory setting in your configuration.

We provide a processor for structlog which will add three new keys to the event_dict of any processed event:

from structlog import PrintLogger, wrap_logger
from structlog.processors import JSONRenderer
from elasticapm.handlers.structlog import structlog_processor

wrapped_logger = PrintLogger()
logger = wrap_logger(wrapped_logger, processors=[structlog_processor, JSONRenderer()])
log = logger.new()
log.msg("some_event")

The Elastic APM Python agent uses logging to log internal events and issues. By default, it will use a logging logger. If your project uses structlog, you can tell the agent to use a structlog logger by setting the environment variable ELASTIC_APM_USE_STRUCTLOG to true.

In order to correlate logs from your app with transactions captured by the Elastic APM Python Agent, your logs must contain one or more of the following identifiers:

If you’re using structured logging, either with a custom solution or with structlog (recommended), then this is fairly easy. Throw the JSONRenderer in, and use Filebeat to pull these logs into Elasticsearch.

Without structured logging the task gets a little trickier. Here we recommend first making sure your LogRecord objects have the elasticapm attributes (see logging), and then you’ll want to combine some specific formatting with a Grok pattern, either in Elasticsearch using the grok processor, or in logstash with a plugin.

Say you have a Formatter that looks like this:

import logging

fh = logging.FileHandler('spam.log')
formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
fh.setFormatter(formatter)

You can add the APM identifiers by simply switching out the Formatter object for the one that we provide:

import logging
from elasticapm.handlers.logging import Formatter

fh = logging.FileHandler('spam.log')
formatter = Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
fh.setFormatter(formatter)

This will automatically append apm-specific fields to your format string:

formatstring = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
formatstring = formatstring + " | elasticapm " \
                              "transaction.id=%(elasticapm_transaction_id)s " \
                              "trace.id=%(elasticapm_trace_id)s " \
                              "span.id=%(elasticapm_span_id)s"

Then, you could use a grok pattern like this (for the Elasticsearch Grok Processor):

{
  "description" : "...",
  "processors": [
    {
      "grok": {
        "field": "message",
        "patterns": ["%{GREEDYDATA:msg} | elasticapm transaction.id=%{DATA:transaction.id} trace.id=%{DATA:trace.id} span.id=%{DATA:span.id}"]
      }
    }
  ]
}

Starting in version 6.16.0, the agent can automatically reformat application logs to ECS format with no changes to dependencies. Prior versions must install the ecs_logging dependency.

Log reformatting is controlled by the log_ecs_reformatting configuration option, and is disabled by default.

The reformatted logs will include both the trace and service correlation IDs.