How do I log a Python error with debug information

When developing Python applications, encountering errors is inevitable. A robust error-logging mechanism can make debugging more efficient by capturing critical details about what went wrong and why. This blog post will guide you through the steps of logging Python errors with debug information effectively.

Why Log Errors?

Logging errors is crucial for:

1. Debugging: Understanding what caused the error.
2. Monitoring: Keeping track of issues in production environments.
3. Auditing: Having a record of errors for compliance or reporting purposes.

Let’s go into the practical steps to log Python errors with helpful debug information.

Step 1: Import the Logging Module

Python’s built-in logging module provides a flexible framework for emitting log messages. Start by importing it:

import logging

Step 2: Configure the Logging System

Set up a basic configuration for logging. This determines where the logs will be written (e.g., console, file) and their format.

logging.basicConfig(
level=logging.DEBUG,
format=’%(asctime)s – %(levelname)s – %(message)s’,
filename=’app.log’, # Logs to a file named app.log
filemode=’a’ # Appends logs to the file
)

Here’s what the configuration options mean:

• level: Specifies the minimum severity of logs (DEBUG, INFO, WARNING, ERROR, CRITICAL).
• format: Defines the log message format. Common placeholders include:
  • %(asctime)s: Timestamp
  • %(levelname)s: Log level (e.g., DEBUG, ERROR)
  • %(message)s: The actual log message
• filename: Specifies the log file name.
• filemode: Determines whether to overwrite (w) or append (a) logs to the file.

Step 3: Log Exceptions

When an exception occurs, you can capture it using a try–except block and log the error message with the stack trace.

try:
# Code that may raise an exception
result = 10 / 0
except Exception as e:
logging.error(“An error occurred”, exc_info=True)

The exc_info=True parameter includes the exception’s stack trace in the log, which is crucial for debugging.

Step 4: Add Contextual Debug Information

To make logs more informative, include contextual data:

try:
user_input = “10”
result = int(user_input) / 0
except Exception as e:
logging.debug(“User input: %s”, user_input)
logging.error(“An error occurred”, exc_info=True)

This way, you’ll not only capture the error but also log the value of user_input that might have contributed to the problem.

Step 5: Use Logging Levels Appropriately

Use the appropriate logging level to categorize messages:

• DEBUG: Detailed information for diagnosing issues.
• INFO: Confirmation that things are working as expected.
• WARNING: Something unexpected happened, but the application is still running.
• ERROR: A serious issue that prevents part of the application from functioning.
• CRITICAL: A severe error causing the application to crash or terminate.

Example:

logging.debug(“Starting the process”)
logging.info(“Process running”)
logging.warning(“Low disk space”)
logging.error(“Failed to open file”)
logging.critical(“Application crash”)

Step 6: Rotate Log Files (Optional)

For long-running applications, log files can grow indefinitely. Use logging.handlers.RotatingFileHandler to limit file size and rotate logs.

from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler(
‘app.log’, maxBytes=5000, backupCount=5
)
logging.basicConfig(
level=logging.DEBUG,
format=’%(asctime)s – %(levelname)s – %(message)s’,
handlers=[handler]
)

This configuration:

• Creates a new log file when the current file exceeds 5,000 bytes.
• Keeps up to 5 backup log files.

Step 7: Testing Your Logging Setup

Test your logging system by deliberately triggering errors:

if __name__ == “__main__”:
try:
# Simulate an error
raise ValueError(“Test error”)
except Exception as e:
logging.error(“Caught an exception during testing”, exc_info=True)

Effective error logging with debug information is critical for maintaining and debugging Python applications. By configuring the logging module and including contextual data, you can simplify troubleshooting and improve the reliability of your code. Integrate these practices into your development workflow to ensure your applications are robust and maintainable.