# sag_py_logging
[![Maintainability][codeclimate-image]][codeclimate-url]
[![Coverage Status][coveralls-image]][coveralls-url]
[](https://snyk.io/test/github/SamhammerAG/sag_py_logging)
[coveralls-image]:https://coveralls.io/repos/github/SamhammerAG/sag_py_logging/badge.svg?branch=master
[coveralls-url]:https://coveralls.io/github/SamhammerAG/sag_py_logging?branch=master
[codeclimate-image]:https://api.codeclimate.com/v1/badges/74139973d3df4567a67b/maintainability
[codeclimate-url]:https://codeclimate.com/github/SamhammerAG/sag_py_logging/maintainability
This library can be used to initialize the python logging by loading a config json.
Furthermore it provides a way to log extra fields.
## What it does
* Initialize logging from configuration json
* Placeholder support for the config json
* A log filter to log extra fields
## How to use
### Installation
pip install sag-py-logging
pip install sag-py-logging[jinia] (optional for templating)
pip install sag-py-logging[toml] (optional for toml file support)
### Initialize logging from json
Add the following as early as possible to your application code:
```python
from sag_py_logging.log_config_initializer import init_logging
from sag_py_logging.log_config_loader import JsonLoader, TomlLoader
from sag_py_logging.log_config_processors import FormatProcessor, JinjaProcessor
placeholder_container = { "host": "myhost.com", ...}
# For toml config with jinja templating
init_logging(
"./log_config.toml",
loader=TomlLoader(),
processors=[JinjaProcessor(placeholder_container)]
)
# For json config with format templating
init_logging(
"./log_config.json",
loader=JsonLoader(),
processors=[FormatProcessor(placeholder_container)]
)
```
Init logging returns the log configuration as dictionary if needed for further processing.
### The configuration
Json config:
```json
{
"version": 1,
"disable_existing_loggers": false,
"root": {
"handlers": ["myhandler"],
"level": "INFO"
},
"handlers": {
"myhandler": {
"host": "${host}",
"formatter": "handler_formatter"
}
}
}
```
Toml config:
```toml
version = 1
disable_existing_loggers = false
[root]
handlers = ["myhandler"]
level = "INFO"
[handlers.myhandler]
host = "${host}"
formatter = "handler_formatter"
```
This is a very basic sample on the format of the file including placeholders.
Read the following for a full schema reference: https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema
Read more on string templating here: https://docs.python.org/3/library/string.html#template-strings
Or if you use jinja templating there: https://jinja.palletsprojects.com/en/3.1.x/templates/#template-designer-documentation
### Configure extra field logging
It is possible to add a filter that extends log entries by a field for extra fields.
The filter is added like that if you initialize logging by code:
```python
from sag_py_logging.console_extra_field_filter import ConsoleExtraFieldFilter
console_handler = logging.StreamHandler(sys.stdout)
console_handler.addFilter(ConsoleExtraFieldFilter())
```
If you init logging by config file the filter is added like that:
```json
{
"formatters": {
"myformatter": {
"format": "s%(asctime)s - %(name)s - %(message)s - %(stringified_extra)s",
},
},
"filters": {
"console_extra_field_filter": {"()": "sag_py_logging.console_extra_field_filter.ConsoleExtraFieldFilter"}
},
"handlers": {
"myhandler": {
"formatter": "myformatter",
"filters": ["console_extra_field_filter"]
}
}
}
```
Afterwards you can use the field "stringified_extra" in your format string.
If you for example log the following:
```python
logging.warning('Watch out!', extra={"keyOne": "valueOne", "keyTwo": 2})
```
The resulting log entry would look like that if stringified_extra is added to the end of the format string:
```
Watch out! {"keyOne": "valueOne", "keyTwo": 2}
```
Note: Internally json.dumps is used to convert the object/data to a string
## How to start developing
### With vscode
Just install vscode with dev containers extension. All required extensions and configurations are prepared automatically.
### With pycharm
* Install latest pycharm
* Install pycharm plugin BlackConnect
* Install pycharm plugin Mypy
* Configure the python interpreter/venv
* pip install requirements-dev.txt
* pip install black[d]
* Ctl+Alt+S => Check Tools => BlackConnect => Trigger when saving changed files
* Ctl+Alt+S => Check Tools => BlackConnect => Trigger on code reformat
* Ctl+Alt+S => Click Tools => BlackConnect => "Load from pyproject.yaml" (ensure line length is 120)
* Ctl+Alt+S => Click Tools => BlackConnect => Configure path to the blackd.exe at the "local instance" config (e.g. C:\Python310\Scripts\blackd.exe)
* Ctl+Alt+S => Click Tools => Actions on save => Reformat code
* Restart pycharm
## How to publish
* Update the version in setup.py and commit your change
* Create a tag with the same version number
* Let github do the rest
Raw data
{
"_id": null,
"home_page": "https://github.com/SamhammerAG/sag_py_logging",
"name": "sag-py-logging",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "logging,extra,fields",
"author": "Samhammer AG",
"author_email": "support@samhammer.de",
"download_url": "https://files.pythonhosted.org/packages/4c/c3/a3c78dcc1691b6046491e3abd887dd2b83bc0d5624ca08511c16c2266034/sag-py-logging-0.3.3.tar.gz",
"platform": null,
"description": "# sag_py_logging\n\n[![Maintainability][codeclimate-image]][codeclimate-url]\n[![Coverage Status][coveralls-image]][coveralls-url]\n[](https://snyk.io/test/github/SamhammerAG/sag_py_logging)\n\n[coveralls-image]:https://coveralls.io/repos/github/SamhammerAG/sag_py_logging/badge.svg?branch=master\n[coveralls-url]:https://coveralls.io/github/SamhammerAG/sag_py_logging?branch=master\n[codeclimate-image]:https://api.codeclimate.com/v1/badges/74139973d3df4567a67b/maintainability\n[codeclimate-url]:https://codeclimate.com/github/SamhammerAG/sag_py_logging/maintainability\n\nThis library can be used to initialize the python logging by loading a config json.\nFurthermore it provides a way to log extra fields.\n\n## What it does\n* Initialize logging from configuration json\n* Placeholder support for the config json\n* A log filter to log extra fields\n\n## How to use\n\n### Installation\n\npip install sag-py-logging\n\npip install sag-py-logging[jinia] (optional for templating)\n\npip install sag-py-logging[toml] (optional for toml file support)\n\n### Initialize logging from json\n\nAdd the following as early as possible to your application code:\n\n```python\nfrom sag_py_logging.log_config_initializer import init_logging\nfrom sag_py_logging.log_config_loader import JsonLoader, TomlLoader\nfrom sag_py_logging.log_config_processors import FormatProcessor, JinjaProcessor\n\nplaceholder_container = { \"host\": \"myhost.com\", ...}\n\n# For toml config with jinja templating\ninit_logging(\n \"./log_config.toml\",\n loader=TomlLoader(),\n processors=[JinjaProcessor(placeholder_container)]\n)\n\n# For json config with format templating\ninit_logging(\n \"./log_config.json\",\n loader=JsonLoader(),\n processors=[FormatProcessor(placeholder_container)]\n)\n\n```\n\nInit logging returns the log configuration as dictionary if needed for further processing.\n\n### The configuration\n\nJson config:\n```json\n{\n \"version\": 1,\n \"disable_existing_loggers\": false,\n \"root\": {\n \"handlers\": [\"myhandler\"],\n \"level\": \"INFO\"\n },\n \"handlers\": {\n \"myhandler\": {\n \"host\": \"${host}\",\n \"formatter\": \"handler_formatter\"\n }\n }\n}\n```\n\nToml config:\n```toml\nversion = 1\ndisable_existing_loggers = false\n\n[root]\nhandlers = [\"myhandler\"]\nlevel = \"INFO\"\n\n[handlers.myhandler]\nhost = \"${host}\"\nformatter = \"handler_formatter\"\n\n```\nThis is a very basic sample on the format of the file including placeholders.\n\nRead the following for a full schema reference: https://docs.python.org/3/library/logging.config.html#configuration-dictionary-schema\n\nRead more on string templating here: https://docs.python.org/3/library/string.html#template-strings\n\nOr if you use jinja templating there: https://jinja.palletsprojects.com/en/3.1.x/templates/#template-designer-documentation\n\n\n### Configure extra field logging\n\nIt is possible to add a filter that extends log entries by a field for extra fields.\n\nThe filter is added like that if you initialize logging by code:\n```python\nfrom sag_py_logging.console_extra_field_filter import ConsoleExtraFieldFilter\n\nconsole_handler = logging.StreamHandler(sys.stdout)\nconsole_handler.addFilter(ConsoleExtraFieldFilter())\n```\n\nIf you init logging by config file the filter is added like that:\n```json\n{\n \"formatters\": {\n \"myformatter\": {\n \"format\": \"s%(asctime)s - %(name)s - %(message)s - %(stringified_extra)s\",\n },\n },\n \"filters\": {\n \"console_extra_field_filter\": {\"()\": \"sag_py_logging.console_extra_field_filter.ConsoleExtraFieldFilter\"}\n },\n \"handlers\": {\n \"myhandler\": {\n \"formatter\": \"myformatter\",\n \"filters\": [\"console_extra_field_filter\"]\n }\n }\n}\n```\n\nAfterwards you can use the field \"stringified_extra\" in your format string.\n\nIf you for example log the following:\n```python\nlogging.warning('Watch out!', extra={\"keyOne\": \"valueOne\", \"keyTwo\": 2})\n```\n\nThe resulting log entry would look like that if stringified_extra is added to the end of the format string:\n\n```\nWatch out! {\"keyOne\": \"valueOne\", \"keyTwo\": 2}\n```\n\nNote: Internally json.dumps is used to convert the object/data to a string\n\n\n## How to start developing\n\n### With vscode\n\nJust install vscode with dev containers extension. All required extensions and configurations are prepared automatically.\n\n### With pycharm\n\n* Install latest pycharm\n* Install pycharm plugin BlackConnect\n* Install pycharm plugin Mypy\n* Configure the python interpreter/venv\n* pip install requirements-dev.txt\n* pip install black[d]\n* Ctl+Alt+S => Check Tools => BlackConnect => Trigger when saving changed files\n* Ctl+Alt+S => Check Tools => BlackConnect => Trigger on code reformat\n* Ctl+Alt+S => Click Tools => BlackConnect => \"Load from pyproject.yaml\" (ensure line length is 120)\n* Ctl+Alt+S => Click Tools => BlackConnect => Configure path to the blackd.exe at the \"local instance\" config (e.g. C:\\Python310\\Scripts\\blackd.exe)\n* Ctl+Alt+S => Click Tools => Actions on save => Reformat code\n* Restart pycharm\n\n## How to publish\n* Update the version in setup.py and commit your change\n* Create a tag with the same version number\n* Let github do the rest\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Initialize logging from a configuration json",
"version": "0.3.3",
"project_urls": {
"Bug Reports": "https://github.com/SamhammerAG/sag_py_logging/issues",
"Documentation": "https://github.com/SamhammerAG/sag_py_logging",
"Homepage": "https://github.com/SamhammerAG/sag_py_logging",
"Source": "https://github.com/SamhammerAG/sag_py_logging"
},
"split_keywords": [
"logging",
"extra",
"fields"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4222b67035ca5f3fc9346c9ec82934eb8a1fff95942210b1715f195124b72208",
"md5": "d8e6d006bae63fff6e83386798b6f434",
"sha256": "47ea09c7c2870395fb3834e5b65b751d57d1bd33984cf20f17523a56ea0275e7"
},
"downloads": -1,
"filename": "sag_py_logging-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8e6d006bae63fff6e83386798b6f434",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7527,
"upload_time": "2023-05-12T12:00:18",
"upload_time_iso_8601": "2023-05-12T12:00:18.170660Z",
"url": "https://files.pythonhosted.org/packages/42/22/b67035ca5f3fc9346c9ec82934eb8a1fff95942210b1715f195124b72208/sag_py_logging-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4cc3a3c78dcc1691b6046491e3abd887dd2b83bc0d5624ca08511c16c2266034",
"md5": "a17e422eaa33a305d0d95e2c7260c79b",
"sha256": "5b0a5f9e9bc46f44fc400e9288d14c09c445064f832a1753bf861a88873c5355"
},
"downloads": -1,
"filename": "sag-py-logging-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "a17e422eaa33a305d0d95e2c7260c79b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7952,
"upload_time": "2023-05-12T12:01:02",
"upload_time_iso_8601": "2023-05-12T12:01:02.450728Z",
"url": "https://files.pythonhosted.org/packages/4c/c3/a3c78dcc1691b6046491e3abd887dd2b83bc0d5624ca08511c16c2266034/sag-py-logging-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-12 12:01:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SamhammerAG",
"github_project": "sag_py_logging",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "sag-py-logging"
}
JSON
