# 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
## How to test
To avoid publishing to pypi unnecessarily you can do as follows
* Tag your branch however you like
* Use the chosen tag in the requirements.txt-file of the project you want to test this library in, eg. `sag_py_logging==<your tag>`
* Rebuild/redeploy your project
Raw data
{
"_id": null,
"home_page": "https://github.com/SamhammerAG/sag_py_logging",
"name": "sag-py-logging",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "logging, extra, fields",
"author": "Samhammer AG",
"author_email": "support@samhammer.de",
"download_url": "https://files.pythonhosted.org/packages/1f/fe/fa28501b1d0382b4e912da3c0efb531e5a9cb52d32cc647ff19ff3b8ddf9/sag_py_logging-0.3.4.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\n## How to test\n\nTo avoid publishing to pypi unnecessarily you can do as follows\n\n* Tag your branch however you like\n* Use the chosen tag in the requirements.txt-file of the project you want to test this library in, eg. `sag_py_logging==<your tag>`\n* Rebuild/redeploy your project\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Initialize logging from a configuration json",
"version": "0.3.4",
"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": "d6182c845d63267fb595dcf5e3f6681dc2e17246b276a01edc8c5501331b8661",
"md5": "e527ebfd32803d815ace774d61aa9ace",
"sha256": "f9fa3d3d402792689f99a1ff32d2bb4434f1f789b34f7a8810e9dc21137b73c5"
},
"downloads": -1,
"filename": "sag_py_logging-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e527ebfd32803d815ace774d61aa9ace",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7661,
"upload_time": "2024-05-06T10:25:21",
"upload_time_iso_8601": "2024-05-06T10:25:21.351762Z",
"url": "https://files.pythonhosted.org/packages/d6/18/2c845d63267fb595dcf5e3f6681dc2e17246b276a01edc8c5501331b8661/sag_py_logging-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1ffefa28501b1d0382b4e912da3c0efb531e5a9cb52d32cc647ff19ff3b8ddf9",
"md5": "14a5d76e36ce28cc4765ad2a12003b61",
"sha256": "60ee1e4b47aeeb37bac7d01d71bc949c3d45fd6249065e7850e6c1ae813d7fcb"
},
"downloads": -1,
"filename": "sag_py_logging-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "14a5d76e36ce28cc4765ad2a12003b61",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8457,
"upload_time": "2024-05-06T10:25:22",
"upload_time_iso_8601": "2024-05-06T10:25:22.405893Z",
"url": "https://files.pythonhosted.org/packages/1f/fe/fa28501b1d0382b4e912da3c0efb531e5a9cb52d32cc647ff19ff3b8ddf9/sag_py_logging-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-06 10:25:22",
"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
