Logging Configuration
========================================
Overview
----------------------------
There are two ways in which you can configure logging for Galaxy servers:
1. Basic/automatic configuration with control over log level and log destination (standard output or a named log file).
2. More complex configuration using the Python :mod:`logging` module's :func:`logging.config.dictConfig` or :func:`logging.config.fileConfig`.
Basic Configuration
----------------------------
Basic logging configuration can be used to modify the level of log messages and the file to which Galaxy logs.
The logging level is controlled by the ``log_level`` configuration option. By default, Galaxy logs all messages at the
``DEBUG`` level.
Galaxy logs all messages to standard output by default if running in the foreground. If running in the background (e.g.
by passing the ``--daemon`` argument to ``run.sh``), the log is written to a location configured in
`gravity `_.
Gravity and related terminology are explained in detail in the :doc:`Scaling and Load Balancing ` documentation.
**Setting the log level:**
In ``galaxy.yml``, set ``log_level``:
.. code-block:: yaml
galaxy:
log_level: LEVEL
Where ``LEVEL`` is one of the `logging levels`_ documented in the :mod:`logging` module.
**Logging to a file:**
To change the log file name or location, use the ``$GALAXY_LOG`` environment variable like so:
.. code-block:: shell-session
$ GALAXY_LOG=/path/to/galaxy/logfile sh run.sh --daemon
It is also possible to specify the path to the log file using the ``log_destination`` configuration option in
``galaxy.yml``. Additionally, it is possible to automatically rotate logs once the log file reaches a given size, using
the ``log_rotate_size`` and ``log_rotate_count`` options, which control the size at which the log is rotated, and the
number of rotated logs to keep, respectively:
.. code-block:: yaml
galaxy:
# Set log file path
log_destination: /srv/galaxy/log/galaxy.log
# Rotate once log reaches 100 MB
log_rotate_size: 100 MB
# Keep the 10 most recent log files
log_rotate_count: 10
Advanced Configuration
----------------------------
For more useful and manageable logging when running Galaxy with forking application stacks where multiple
Galaxy server processes are forked after the Galaxy application is loaded, a custom ``filename_template`` config option
is available to :class:`logging.FileHandler` (or derivative class) log handler definitions so that multiple file logging is possible.
Without this custom option, all forked Galaxy server processes would only be able to log to a single combined log file,
which can be very difficult to work with.
YAML
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Advanced logging configuration is performed under the ``logging`` key in the ``galaxy`` section of ``galaxy.yml``. The
syntax is a YAML dictionary in the syntax of Python's :func:`logging.config.dictConfig`. This section covers a few of
the most common configurations as well as Galaxy's customizations. Consult the :func:`logging.config.dictConfig`
documentation for a complete explanation of the syntax and possibilities.
Default
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default as of this Galaxy release can be found (in Python syntax) in the
:data:`galaxy.config.LOGGING_CONFIG_DEFAULT` constant and (in YAML) below:
.. include:: config_logging_default_yaml.rst
.. _logging levels: https://docs.python.org/library/logging.html#logging-levels
.. _fileConfig file format: https://docs.python.org/library/logging.config.html#configuration-file-format