Troubleshooting

Below are some resources and tips for troubleshooting and debugging the python agent.

Before you try anything else, go through the following sections to ensure that the agent is configured correctly. This is not an exhaustive list, but rather a list of common problems that users run into.

Most frameworks support a debug mode. Generally, this mode is intended for non-production environments and provides detailed error messages and logging of potentially sensitive data. Because of these security issues, the agent will not collect traces if the app is in debug mode by default.

You can override this behavior with the DEBUG configuration.

Note that configuration of the agent should occur before creation of any ElasticAPM objects:

app = Flask(__name__)
app.config["ELASTIC_APM"] = {"DEBUG": True}
apm = ElasticAPM(app, service_name="flask-app")

To get CPU and system metrics on non-Linux systems, psutil must be installed. The agent should automatically show a warning on start if it is not installed, but sometimes this warning can be suppressed. Install psutil and metrics should be collected by the agent and sent to the APM Server.

python3 -m pip install psutil

In order for the agent to send data to the APM Server, it may need an API_KEY or a SECRET_TOKEN. Double check your APM Server settings and make sure that your credentials are configured correctly. Additionally, check that SERVER_URL is correct.

When used with Django, the agent provides two management commands to help debug common issues. Head over to the Django troubleshooting section for more information.

To get the agent to log more data, all that is needed is a Handler which is attached either to the elasticapm logger or to the root logger.

Note that if you attach the handler to the root logger, you also need to explicitly set the log level of the elasticapm logger:

import logging
apm_logger = logging.getLogger("elasticapm")
apm_logger.setLevel(logging.DEBUG)

The simplest way to log more data from the agent is to add a console logging Handler to the elasticapm logger. Here’s a (very simplified) example:

LOGGING = {
    'handlers': {
        'console': {
            'level': 'DEBUG',
            'class': 'logging.StreamHandler'
        }
    },
    'loggers': {
        'elasticapm': {
            'level': 'DEBUG',
            'handlers': ['console']
        },
    },
}

Flask recommends using dictConfig() to set up logging. If you’re using this format, adding logging for the agent will be very similar to the instructions for Django above.

Otherwise, you can use the generic instructions below.

Creating a console Handler and adding it to the elasticapm logger is easy:

import logging

elastic_apm_logger = logging.getLogger("elasticapm")
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.DEBUG)
elastic_apm_logger.addHandler(console_handler)

You can also just add the console Handler to the root logger. This will apply that handler to all log messages from all modules.

import logging

logger = logging.getLogger()
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.DEBUG)
logger.addHandler(console_handler)

See the python logging docs for more details about Handlers (and information on how to format your logs using Formatters).

In the unlikely event the agent causes disruptions to a production application, you can disable the agent while you troubleshoot.

If you have access to dynamic configuration, you can disable the recording of events by setting recording to false. When changed at runtime from a supported source, there’s no need to restart your application.

If that doesn’t work, or you don’t have access to dynamic configuration, you can disable the agent by setting enabled to false. You’ll need to restart your application for the changes to take effect.