Python logging utilities
Project description
logdog
Python package with logging
utilities
This package is grouped into three main functionalities:
- Encoders
They are the "core" of this package. They are fully functional, but can still be extended and replaced as needed - Formatters
They allow you to bring structured logging to your app. Keys present in log lines (such astime
,level
ormessage
) can be easily configured by using a custom format - Wrappers
They are just utilities that you can use to simplify the use of logging functions
Documentation
Documentation is hosted by GitHub Pages - click here
Requirements
- Python >= 3.10
Installation
pip install -U python-logdog
Usage
[!NOTE] These are only basic examples. More advanced ones can be found in documentation and the
examples/
directory
Wrappers
LogMessageWrapper
Message wrapper wraps log message (obviously) and adds context to logs
You can specify prefix
and suffix
for this values. Default prefix is single space and no suffix
import logging
from logdog import LogMessageWrapper
logging.basicConfig(level=logging.INFO, format="%(asctime)s : %(levelname)-8s : %(message)s")
logger = logging.getLogger("mylogger")
user_id = 1
some_value = "some string"
logger.info("user login", extra={"not": "included", "user": user_id, "value": some_value})
# output: 2023-09-05 12:01:09,836 : INFO : user login
log = LogMessageWrapper(logger, prefix=" : ")
log.info("user login", user=user_id, action="login", value=some_value)
# output: 2023-09-05 12:01:09,836 : INFO : user login : user=1 action=login value="some string"
LogExtraWrapper
Extra wrapper wraps kwargs
into logging.Record
's extra
property
It is recommended to use it together with some formatter
# so this
logger.info("user login", extra={"user": user_id, "value": some_value})
log = LogMessageWrapper(logger)
# is the same as this
log.info("user login", user=user_id, value=some_value)
Formatters
JsonFormatter
This formatter encodes log as JSON. Internally it uses JsonEncoder
import logging
from logdog import JsonFormatter, LogExtraWrapper
logger = logging.getLogger(__name__)
handler = logging.StreamHandler()
formatter = JsonFormatter() # no arguments -> using default format
handler.setFormatter(formatter)
# without wrapper
user_id = 1
logger.info("user login", extra={"user": user_id, "action": "login"})
# output: {"time": "2023-09-09 13:39:31,191", "level": "INFO", "message": "user login", "user": 1, "action": "login"}
# with wrapper - optional but recommended
log = LogExtraWrapper(logger)
user_id = 2
log.info("user login", user=user_id, action="login")
# output: {"time": "2023-09-09 13:39:31,191", "level": "INFO", "message": "user login", "user": 2, "action": "login"}
LogfmtFormatter
This formatter encodes log with logfmt format. Internally it uses LogfmtEncoder
import logging
from logdog import LogExtraWrapper, LogfmtFormatter
logger = logging.getLogger(__name__)
handler = logging.StreamHandler()
formatter = LogfmtFormatter(
"time:ts level:at message:msg exception:exc filename:file lineno:line",
time_fmt="iso",
)
handler.setFormatter(formatter)
log = LogExtraWrapper(logger)
user_id = 12
action = "login"
log.info("user performed action", user=user_id, action=action)
# output:
# ts=2023-09-09T13:39:31,191 at=INFO msg="user performed action" file=login.py line=75 user=12 action=login
File config
Check the examples/logging_config_formatter.py
file
TL;DR
{
"formatters": {
"logfmt": {
"()": "logdog.LogfmtFormatter", # or logdog.JsonFormatter
"keys": "time level message exception lineno:line filename:file", # optional
"time_fmt": "default", # optional
"include_ms": True, # optional
},
},
}
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for python_logdog-0.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 106b2ff847d47678ba054d27c966d238482e179a1dea805babe46664fee3569f |
|
MD5 | 823e417c1ce7ae38e73dce4a7276ec11 |
|
BLAKE2b-256 | 58a515ba6ac0f0816879d26299047b23377d6e43fb17f2c2053bf94d238b7dc6 |