# Zirconium Logging (ZrLog)
Logging configuration is often complex and Python is missing a few "nice" features that exist in
other languages logging systems. This package hopes to simplify the experience of configuring logging while adding a few
nice features:
* Loading logging configuration from TOML or YAML (via `zirconium`) instead of the older `configparser` format
* `TRACE` level for very fine-grained output (more so that `DEBUG`)
* `NOTICE` level for normal conditions that should always be output
* `OUT` level for logging user messages
* `AUDIT` level for interacting with Python's audit hooks
* A threaded audit hook that logs most audit messages
* The ability to disable stack trace output
* The ability to set context-specific "extra" variables on all loggers and to provide defaults for these
so that they can be added to all logging messages within that context (e.g. for usernames)
## Basic Usage
```python
# Do this at the start of any run of your code
import zrlog
# Imports logging configuration from TOML and sets up the logging system for you.
zrlog.init_logging()
# Set a default username
zrlog.set_default_extra('username', '**anonymous**')
# logging.getLogger() works as well, this version is a wrapper that (a) makes sure that `zrlog.init_logging()` was
# called and (b) provides a better type hint for the logger class.
logger = zrlog.get_logger(__name__)
```
## Configuration File
By default, logging configuration comes from a TOML file in up to three places:
* `[HOME_DIRECTORY]/.logging.toml`
* `[CURRENT_WORKING_DIRECTORY]/.logging.toml`
* Value of the `ZRLOG_CONFIG_FILE` environment variable. This file may also be a YAML or other formats supported by
`zirconium`
If you use `zirconium` for your project configuration, it can also be in any configuration file specified by your
project.
The logging configuration file is similar to that defined by `logging.config.dictConfig()`, with a few extensions. See
the `.logging.example.toml` file for configuration.
## Performance impact
Testing suggests that the impact of replacing the typical `logging` approach with this module is about 14% slower to
get a logger and 10% slower to make a logging call with extras. However, the time to make a log to `stdout` is
still only 0.013 ms (compared to 0.012 ms for the standard logging package), therefore this performance impact is
probably insignificant in most use cases.
## Log Level Recommendations
| Level | Use Case |
| --- | --- |
| critical | An error so severe has occurred that the application may now crash. |
| error | An error has occurred and may have created unexpected behaviour. |
| warning | Something unexpected happen but it is recoverable, or a problem may occur in the future. |
| notice | Something expected has happened that needs to be tracked in a production environment (e.g. user login). |
| out | Something expected has happened in a command line environment that the user needs to be notified of. |
| info | Something expected has happened that does not need tracking but can be useful to confirm normal operation. |
| debug | Additional detail for debugging an issue |
| trace | Even more detail for debugging an issue |
| audit | Python auditing output only |
## Logging Audit Events
This package provides a system for turning `sys.audit()` events into log records using a thread-based queue. This is
necessary because audit events don't play nicely with the logging subsystem, leading to inconsistent errors if the
logger `log()` method is called directly from the audit hook. Audit logging must be enabled specifically by setting
the `with_audit` flag:
```toml
# .logging.toml
[logging]
with_audit = true
```
While the default level is "AUDIT", you can change this to any of the logging level prefixes by specifying the
audit_level:
```toml
# .logging.toml
[logging]
with_audit = true
audit_level = "INFO"
```
One specific event can cause further problems: `sys._getframe()` is called repeatedly from the logging subsystem in Python
(in 3.8 at least). These audit events are NOT logged by default, but logging of them can be enabled by turning off the
`omit_logging_frames` flag.
```toml
# .logging.toml
[logging]
with_audit = true
omit_logging_frames = false
```
Audit events are logged (by default) at the AUDIT level which is below TRACE; your logger and handler must be set to that level to
see these events:
```toml
[logging.root]
level = "AUDIT"
handlers = ["console"]
[logging.handlers.console]
class = "logging.StreamHandler"
formatter = "brief"
level = "AUDIT"
stream = "ext://sys.stdout"
```
## Change Log
### version 0.3.0
- Added logger extra handling via `set_logger_extra` and `set_default_logger_extra`
- Added the `NOTICE` level to correspond with more typical usage. `OUT` should be used for user output where it needs
to be logged and `NOTICE` for normal conditions that need to be logged even in production.
### version 0.2.0
- Updated the audit handling thread to use a `threading.Event` to end itself rather than a boolean flag.
- Added the `no_config` flag, mostly to be used in test suites to ensure everything still works properly.
- Several documentation cleanup items
Raw data
{
"_id": null,
"home_page": "https://github.com/turnbullerin/zrlog",
"name": "zrlog",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Erin Turnbull",
"author_email": "erin.a.turnbull@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b5/80/3c34e87d647db3305e339a646148c70534bda3e52ff8414eea9347f7a265/zrlog-0.3.0.tar.gz",
"platform": null,
"description": "# Zirconium Logging (ZrLog)\r\nLogging configuration is often complex and Python is missing a few \"nice\" features that exist in \r\nother languages logging systems. This package hopes to simplify the experience of configuring logging while adding a few\r\nnice features:\r\n\r\n* Loading logging configuration from TOML or YAML (via `zirconium`) instead of the older `configparser` format\r\n* `TRACE` level for very fine-grained output (more so that `DEBUG`)\r\n* `NOTICE` level for normal conditions that should always be output\r\n* `OUT` level for logging user messages\r\n* `AUDIT` level for interacting with Python's audit hooks\r\n* A threaded audit hook that logs most audit messages\r\n* The ability to disable stack trace output\r\n* The ability to set context-specific \"extra\" variables on all loggers and to provide defaults for these\r\n so that they can be added to all logging messages within that context (e.g. for usernames)\r\n\r\n## Basic Usage\r\n\r\n```python \r\n# Do this at the start of any run of your code\r\nimport zrlog\r\n\r\n# Imports logging configuration from TOML and sets up the logging system for you.\r\nzrlog.init_logging()\r\n\r\n# Set a default username\r\nzrlog.set_default_extra('username', '**anonymous**')\r\n\r\n# logging.getLogger() works as well, this version is a wrapper that (a) makes sure that `zrlog.init_logging()` was \r\n# called and (b) provides a better type hint for the logger class.\r\nlogger = zrlog.get_logger(__name__)\r\n```\r\n\r\n## Configuration File\r\nBy default, logging configuration comes from a TOML file in up to three places:\r\n\r\n* `[HOME_DIRECTORY]/.logging.toml`\r\n* `[CURRENT_WORKING_DIRECTORY]/.logging.toml`\r\n* Value of the `ZRLOG_CONFIG_FILE` environment variable. This file may also be a YAML or other formats supported by \r\n `zirconium`\r\n \r\nIf you use `zirconium` for your project configuration, it can also be in any configuration file specified by your\r\nproject.\r\n \r\nThe logging configuration file is similar to that defined by `logging.config.dictConfig()`, with a few extensions. See \r\nthe `.logging.example.toml` file for configuration.\r\n\r\n\r\n## Performance impact\r\nTesting suggests that the impact of replacing the typical `logging` approach with this module is about 14% slower to \r\nget a logger and 10% slower to make a logging call with extras. However, the time to make a log to `stdout` is \r\nstill only 0.013 ms (compared to 0.012 ms for the standard logging package), therefore this performance impact is \r\nprobably insignificant in most use cases.\r\n\r\n## Log Level Recommendations\r\n| Level | Use Case |\r\n| --- | --- |\r\n| critical | An error so severe has occurred that the application may now crash. |\r\n| error | An error has occurred and may have created unexpected behaviour. |\r\n| warning | Something unexpected happen but it is recoverable, or a problem may occur in the future. |\r\n| notice | Something expected has happened that needs to be tracked in a production environment (e.g. user login). |\r\n| out | Something expected has happened in a command line environment that the user needs to be notified of. |\r\n| info | Something expected has happened that does not need tracking but can be useful to confirm normal operation. |\r\n| debug | Additional detail for debugging an issue |\r\n| trace | Even more detail for debugging an issue |\r\n| audit | Python auditing output only |\r\n\r\n\r\n## Logging Audit Events\r\nThis package provides a system for turning `sys.audit()` events into log records using a thread-based queue. This is \r\nnecessary because audit events don't play nicely with the logging subsystem, leading to inconsistent errors if the\r\nlogger `log()` method is called directly from the audit hook. Audit logging must be enabled specifically by setting\r\nthe `with_audit` flag:\r\n\r\n```toml\r\n# .logging.toml\r\n[logging]\r\nwith_audit = true\r\n```\r\n\r\nWhile the default level is \"AUDIT\", you can change this to any of the logging level prefixes by specifying the \r\naudit_level:\r\n\r\n```toml\r\n# .logging.toml\r\n[logging]\r\nwith_audit = true\r\naudit_level = \"INFO\"\r\n```\r\n\r\nOne specific event can cause further problems: `sys._getframe()` is called repeatedly from the logging subsystem in Python\r\n(in 3.8 at least). These audit events are NOT logged by default, but logging of them can be enabled by turning off the\r\n`omit_logging_frames` flag.\r\n\r\n```toml\r\n# .logging.toml\r\n[logging]\r\nwith_audit = true\r\nomit_logging_frames = false\r\n```\r\n\r\nAudit events are logged (by default) at the AUDIT level which is below TRACE; your logger and handler must be set to that level to \r\nsee these events:\r\n\r\n```toml\r\n[logging.root]\r\nlevel = \"AUDIT\"\r\nhandlers = [\"console\"]\r\n\r\n[logging.handlers.console]\r\nclass = \"logging.StreamHandler\"\r\nformatter = \"brief\"\r\nlevel = \"AUDIT\"\r\nstream = \"ext://sys.stdout\"\r\n```\r\n\r\n## Change Log\r\n\r\n### version 0.3.0\r\n- Added logger extra handling via `set_logger_extra` and `set_default_logger_extra`\r\n- Added the `NOTICE` level to correspond with more typical usage. `OUT` should be used for user output where it needs\r\n to be logged and `NOTICE` for normal conditions that need to be logged even in production.\r\n\r\n### version 0.2.0\r\n- Updated the audit handling thread to use a `threading.Event` to end itself rather than a boolean flag.\r\n- Added the `no_config` flag, mostly to be used in test suites to ensure everything still works properly.\r\n- Several documentation cleanup items\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Logging with Zirconium-based configuration and supports audit logging",
"version": "0.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/turnbullerin/zrlog/issues",
"Homepage": "https://github.com/turnbullerin/zrlog"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9140bea8795bb364dc9e73d40de73aba48cebc6ad9879be494191fa52c006cd8",
"md5": "4ada1ceff0d9836c83b61492147d1dbf",
"sha256": "0dd7cbb2c2b287fb1fea20d3c1c856b4046a6424b11b1cb7195c5d5fdb0c37f5"
},
"downloads": -1,
"filename": "zrlog-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4ada1ceff0d9836c83b61492147d1dbf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7867,
"upload_time": "2023-05-17T15:35:13",
"upload_time_iso_8601": "2023-05-17T15:35:13.478307Z",
"url": "https://files.pythonhosted.org/packages/91/40/bea8795bb364dc9e73d40de73aba48cebc6ad9879be494191fa52c006cd8/zrlog-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b5803c34e87d647db3305e339a646148c70534bda3e52ff8414eea9347f7a265",
"md5": "6eccee5697e531eab305e59ae2e90130",
"sha256": "f2ac66a3099abbd466211264e407314bed8de6c8f50864f35ecf7c87e7fb3890"
},
"downloads": -1,
"filename": "zrlog-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "6eccee5697e531eab305e59ae2e90130",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7400,
"upload_time": "2023-05-17T15:35:15",
"upload_time_iso_8601": "2023-05-17T15:35:15.018277Z",
"url": "https://files.pythonhosted.org/packages/b5/80/3c34e87d647db3305e339a646148c70534bda3e52ff8414eea9347f7a265/zrlog-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-17 15:35:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "turnbullerin",
"github_project": "zrlog",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "zirconium",
"specs": [
[
">=",
"0.2.2"
]
]
},
{
"name": "autoinject",
"specs": [
[
">=",
"0.2.1"
]
]
},
{
"name": "toml",
"specs": []
}
],
"lcname": "zrlog"
}
JSON
