Logging system¶

Note

The Astropy logging system is meant for internal astropy usage. For use in other packages, we recommend implementing your own logger instead.

Overview¶

The Astropy logging system is designed to give users flexibility in deciding which log messages to show, to capture them, and to send them to a file.

All messages printed by Astropy routines should use the built-in logging facility (normal print() calls should only be done by routines that are explicitly requested to print output). Messages can have one of several levels:

DEBUG: Detailed information, typically of interest only when diagnosing problems.
INFO: An message conveying information about the current task, and confirming that things are working as expected
WARNING: An indication that something unexpected happened, and that user action may be required.
ERROR: indicates a more serious issue, including exceptions

By default, INFO, WARNING and ERROR messages are displayed, and are sent to a log file located at ~/.astropy/astropy.log (if the file is writeable).

Configuring the logging system¶

First, import the logger:

from astropy import log

The threshold level (defined above) for messages can be set with e.g.:

log.setLevel('DEBUG')

Color (enabled by default) can be disabled with:

log.disable_color()

and enabled with:

log.enable_color()

Warnings from warnings.warn can be logged with:

log.enable_warnings_logging()

which can be disabled with:

log.disable_warnings_logging()

and exceptions can be included in the log with:

log.enable_exception_logging()

which can be disabled with:

log.disable_exception_logging()

It is also possible to set these settings from the Astropy configuration file, which also allows an overall log file to be specified. See Using the configuration file for more information.

Context managers¶

In some cases, you may want to capture the log messages, for example to check whether a specific message was output, or to log the messages from a specific section of code to a file. Both of these are possible using context managers.

To add the log messages to a list, first import the logger if you have not already done so:

from astropy import log

then enclose the code in which you want to log the messages to a list in a with statement:

with log.log_to_list() as log_list:
    # your code here

In the above example, once the block of code has executed, log_list will be a Python list containing all the Astropy logging messages that were raised. Note that messages continue to be output as normal.

Similarly, you can output the log messages of a specific section of code to a file using:

with log.log_to_file('myfile.log'):
    # your code here

which will add all the messages to myfile.log (this is in addition to the overall log file mentioned in Using the configuration file).

While these context managers will include all the messages emitted by the logger (using the global level set by log.setLevel), it is possible to filter a subset of these using filter_level=, and specifying one of 'DEBUG', 'INFO', 'WARN', 'ERROR'. Note that if filter_level is a lower level than that set via setLevel, only messages with the level set by setLevel or higher will be included (i.e. filter_level is only filtering a subset of the messages normally emitted by the logger).

Similarly, it is possible to filter a subset of the messages by origin by specifying filter_origin= followed by a string. If the origin of a message starts with that string, the message will be included in the context manager. For example, filter_origin='astropy.wcs' will include only messages emitted in the astropy.wcs sub-package.

Using the configuration file¶

Options for the logger can be set in the [logger] section of the Astropy configuration file:

[logger]

# Threshold for the logging messages. Logging messages that are less severe
# than this level will be ignored. The levels are 'DEBUG', 'INFO', 'WARNING',
# 'ERROR'
log_level = 'INFO'

# Whether to use color for the level names
use_color = True

# Whether to log warnings.warn calls
log_warnings = False

# Whether to log exceptions before raising them
log_exceptions = False

# Whether to always log messages to a log file
log_to_file = True

# The file to log messages to. If empty string is given, it defaults to a
# file `astropy.log` in the astropy config directory.
log_file_path = '~/.astropy/astropy.log'

# Threshold for logging messages to log_file_path
log_file_level = 'INFO'

# Format for log file entries
log_file_format = '%(asctime)s, %(origin)s, %(levelname)s, %(message)s'

# The encoding (e.g., UTF-8) to use for the log file.  If empty string is
# given, it defaults to the platform-preferred encoding.
log_file_encoding = ""

Reference/API¶

astropy.logger Module¶

This module defines a logging class based on the built-in logging module.

Note

This module is meant for internal astropy usage. For use in other packages, we recommend implementing your own logger instead.

Classes¶

`Conf`()	Configuration parameters for `astropy.logger`.
`AstropyLogger`(name[, level])	This class is used to set up the Astropy logging.
`LoggingError`	This exception is for various errors that occur in the astropy logger, typically when activating or deactivating logger-related features.

Navigation