Logging
Configuration
Configuration of logging is done through the logging.yml
.
During the first start a default configuration will be created.
It is recommended to extend the default configuration.
The complete description of the file format can be found here, but the format should be pretty straight forward.
Hint
HABApp.log
/HABApp/logs/habapp.log
or c:\HABApp\logs\habapp.log
Provided loggers
The HABApp.config.logging
module provides additional loggers which can be used
- class MidnightRotatingFileHandler(*args, **kwargs)
A rotating file handler that checks once after midnight if the configured size has been exceeded and then rotates the file
- class CompressedMidnightRotatingFileHandler(*args, **kwargs)
Same as
MidnightRotatingFileHandler
but rotates the file to a gzipped archive (.gz
)
Example
Usage
The logging library is the standard python library and an extensive description can be found in the official documentation.
import logging
import HABApp
log = logging.getLogger('MyRule')
class MyLoggingRule(HABApp.Rule):
def __init__(self) -> None:
super().__init__()
# different levels are available
log.debug('Debug Message')
log.info('Info Message')
log.warning('Warning Message')
log.error('Error Message')
MyLoggingRule()
To make the logging output work properly an output file and an output format has to be configured for the logger.
The logging library supports a logging hierarchy so the configuration for the logger MyRule
will also work
logger MyRule.SubLogger
and MyRule.SubLogger.SubSubLogger
.
The output of our logger from the example shall be in a separate file so we add a new output file
to the file configuration under handlers
in the logging.yml
.
handlers:
...
MyRuleHandler: # <-- This is the name of the handler
class: HABApp.config.logging.MidnightRotatingFileHandler
filename: 'c:\HABApp\Logs\MyRule.log'
maxBytes: 10_000_000
backupCount: 3
formatter: HABApp_format # use this format
level: DEBUG
The output file is now available for logging but the configuration for the logger is still missing.
It has to be added under loggers
and reference the handler we created
loggers:
...
MyRule: # <-- Name of the logger
level: DEBUG # <-- minimum Logging level, e.g. use INFO if you don't want the output of log.debug()
handlers:
- MyRuleHandler # This logger uses the MyRuleHandler
propagate: False
Now the logger works as expected and writes all output to the new file.
Full Example configuration
# -----------------------------------------------------------------------------------
# Configuration of the available output formats
# -----------------------------------------------------------------------------------
formatters:
HABApp_format:
format: '[%(asctime)s] [%(name)25s] %(levelname)8s | %(message)s'
# -----------------------------------------------------------------------------------
# Configuration of the available file handlers (output files)
# -----------------------------------------------------------------------------------
handlers:
HABApp_default:
class: HABApp.config.logging.MidnightRotatingFileHandler
filename: 'HABApp.log'
maxBytes: 10_000_000
backupCount: 3
formatter: HABApp_format # use the specified formatter (see above)
level: DEBUG
MyRuleHandler:
class: HABApp.config.logging.MidnightRotatingFileHandler
filename: 'c:\HABApp\Logs\MyRule.log' # absolute filename is recommended
maxBytes: 10_000_000
backupCount: 3
formatter: HABApp_format # use the specified formatter (see above)
level: DEBUG
# -----------------------------------------------------------------------------------
# Configuration of all available loggers and their configuration
# -----------------------------------------------------------------------------------
loggers:
HABApp:
level: DEBUG
handlers:
- HABApp_default # This logger does log with the default handler
propagate: False
MyRule: # <-- Name of the logger
level: DEBUG
handlers:
- MyRuleHandler # This logger uses the MyRuleHandler
propagate: False
Custom log levels
It is possible to add custom log levels or rename existing levels.
This is possible via the optional levels
entry in the logging configuration file.
levels:
WARNING: WARN # Changes WARNING to WARN
5: TRACE # Adds a new loglevel "TRACE" with value 5
formatters:
HABApp_format:
...
Logging to stdout
The following handler writes to stdout
handlers:
StdOutHandler:
class: logging.StreamHandler
stream: ext://sys.stdout
formatter: HABApp_format
level: DEBUG
Add custom filters to loggers
It’s possible to filter out certain parts of log files with a filter. The recommendation is to create the filter during startup.
This example ignores all messages for the HABApp.EventBus
logger that contain MyIgnoredString
.
import logging
# False to skip, True to log record
def filter(record: logging.LogRecord) -> bool:
return 'MyIgnoredString' not in record.msg
logging.getLogger('HABApp.EventBus').addFilter(filter)
Note
re.compile
for performance reasons.