| Name | logging-json JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | |
| Summary | JSON formatter for python logging |
| upload_time | 2024-01-17 11:08:03 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | MIT License Copyright (c) 2024 Colin Bounouar Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
logging
json
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h2 align="center">JSON formatter for logging</h2>
<p align="center">
<a href="https://pypi.org/project/logging_json/"><img alt="pypi version" src="https://img.shields.io/pypi/v/logging_json"></a>
<a href="https://github.com/Colin-b/logging_json/actions"><img alt="Build status" src="https://github.com/Colin-b/logging_json/workflows/Release/badge.svg"></a>
<a href="https://github.com/Colin-b/logging_json/actions"><img alt="Coverage" src="https://img.shields.io/badge/coverage-100%25-brightgreen"></a>
<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
<a href="https://github.com/Colin-b/logging_json/actions"><img alt="Number of tests" src="https://img.shields.io/badge/tests-25 passed-blue"></a>
<a href="https://pypi.org/project/logging_json/"><img alt="Number of downloads" src="https://img.shields.io/pypi/dm/logging_json"></a>
</p>
This module provides a JSON formatter for the python [`logging`](https://docs.python.org/3/library/logging.html) module that will format to JSON formatted string.
Using this formatter allows to have the proper format for logging to `Splunk` or `ElasticSearch`, but it can also be used for logging to stdout as a string is issued.
- [Features](#features)
- [Custom fields](#adding-additional-fields-and-values)
- [dict logging](#logging-with-a-dictionary)
- [str logging](#logging-with-anything-else-such-as-a-string)
- [Configuration](#configuration)
- [Using dictConfig](#using-loggingconfigdictconfig)
## Features
### Adding additional fields and values
You can add fields to every message that is being logged.
To do so, specify the `fields` parameter to the `logging_json.JSONFormatter` instance.
It must be a dictionary where keys are the keys to be appended to the resulting JSON dictionary (if not already present) and the values can be one of the following:
* An attribute of the logging record (non-exhaustive list can be found on [the python logging documentation](https://docs.python.org/3/library/logging.html#logrecord-attributes)).
* If not found on the record, the value will be linked to the key.
#### Logging exceptions, a specific case
If an exception is logged, the `exception` key will be appended to the resulting JSON dictionary.
This dictionary will contain 3 keys:
* `type`: The name of the exception class (useful when the message is blank).
* `message`: The str representation of the exception (usually the provided error message).
* `stack`: The stack trace, formatted as a string.
You can rename the exception field key by setting the `exception_field_name` parameter with a new name for the key.
It is also possible to disable this behaviour by setting the `exception_field_name` parameter to `None` or an empty string
### Logging with a dictionary
This formatter allows you to log dictionary as in the following:
```python
import logging
logging.info({"key": "value", "other key": "other value"})
```
The resulting JSON dictionary will be the one you provided (with the [additional fields](#adding-additional-fields-and-values)).
### Logging with anything else (such as a string)
Anything not logged using a dictionary will be handled by the standard formatter, and it can result in one of the 2 output:
* A JSON dictionary, if [additional fields](#adding-additional-fields-and-values) are set or if `extra` parameter is used while logging, with the message available in the `message` key of the resulting JSON dictionary.
Default `message` key name can be changed by `message_field_name` parameter of the `logging_json.JSONFormatter` instance.
* The formatted record, if no [additional fields](#adding-additional-fields-and-values) are set.
This handles the usual string logging as in the following:
```python
import logging
logging.info("This is my message")
```
### Changing asctime representation
You can override the default representation of asctime (`2003-07-08 16:49:45,896`) based on two different scenarii:
#### Without milliseconds
Set `datefmt` parameter.
Setting `datefmt` to `%Y-%m-%dT%H:%M:%S` would result in `2003-07-08T16:49:45`.
#### With milliseconds
Set `default_time_format` to something else than `%Y-%m-%d %H:%M:%S` to change the representation part without milliseconds.
Set `default_msec_format` to something else than `%s,%03d` to change the representation milliseconds.
Note that `%s` in `default_msec_format` is going to be replaced by the representation without milliseconds.
Setting `default_time_format` to `%Y-%m-%dT%H:%M:%S` and `default_msec_format` to `%s.%03d` would result in `2003-07-08T16:49:45.896`.
## Configuration
You can create a formatter instance yourself as in the following, or you can use a logging configuration.
```python
import logging_json
formatter = logging_json.JSONFormatter(fields={
"level_name": "levelname",
"thread_name": "threadName",
"process_name": "processName"
})
```
### Using logging.config.dictConfig
You can configure your logging as advertise by python, by using the `logging.config.dictConfig` function.
#### dict configuration
```python
import logging.config
logging.config.dictConfig({
"version": 1,
"formatters": {
"json": {
'()': 'logging_json.JSONFormatter',
'fields':{
"level_name": "levelname",
"thread_name": "threadName",
"process_name": "processName"
}
}
},
"handlers": {
"standard_output": {
'class': 'logging.StreamHandler',
'formatter': 'json',
'stream': 'ext://sys.stdout'
},
},
"loggers": {
"my_app": {"level": "DEBUG"}
},
"root": {
"level": "INFO",
"handlers": ["standard_output"]
}
})
```
#### YAML logging configuration
You can use YAML to store your logging configuration, as in the following sample:
```python
import logging.config
import yaml
with open("path/to/logging_configuration.yaml", "r") as config_file:
logging.config.dictConfig(yaml.load(config_file))
```
Where `logging_configuration.yaml` can be a file containing the following sample:
```yaml
version: 1
formatters:
json:
'()': logging_json.JSONFormatter
fields:
level_name: levelname
thread_name: threadName
process_name: processName
handlers:
standard_output:
class: logging.StreamHandler
formatter: json
stream: ext://sys.stdout
loggers:
my_app:
level: DEBUG
root:
level: INFO
handlers: [standard_output]
```
## How to install
1. [python 3.7+](https://www.python.org/downloads/) must be installed
2. Use pip to install module:
```sh
python -m pip install logging_json
```
Raw data
{
"_id": null,
"home_page": "",
"name": "logging-json",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "Colin Bounouar <colin.bounouar.dev@gmail.com>",
"keywords": "logging,json",
"author": "",
"author_email": "Colin Bounouar <colin.bounouar.dev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c6/25/e57be29b8ceccedd3c271b18b2fd6546bf3a8effa12d74fa116a0993589a/logging_json-0.5.0.tar.gz",
"platform": null,
"description": "<h2 align=\"center\">JSON formatter for logging</h2>\n\n<p align=\"center\">\n<a href=\"https://pypi.org/project/logging_json/\"><img alt=\"pypi version\" src=\"https://img.shields.io/pypi/v/logging_json\"></a>\n<a href=\"https://github.com/Colin-b/logging_json/actions\"><img alt=\"Build status\" src=\"https://github.com/Colin-b/logging_json/workflows/Release/badge.svg\"></a>\n<a href=\"https://github.com/Colin-b/logging_json/actions\"><img alt=\"Coverage\" src=\"https://img.shields.io/badge/coverage-100%25-brightgreen\"></a>\n<a href=\"https://github.com/psf/black\"><img alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"></a>\n<a href=\"https://github.com/Colin-b/logging_json/actions\"><img alt=\"Number of tests\" src=\"https://img.shields.io/badge/tests-25 passed-blue\"></a>\n<a href=\"https://pypi.org/project/logging_json/\"><img alt=\"Number of downloads\" src=\"https://img.shields.io/pypi/dm/logging_json\"></a>\n</p>\n\nThis module provides a JSON formatter for the python [`logging`](https://docs.python.org/3/library/logging.html) module that will format to JSON formatted string.\n\nUsing this formatter allows to have the proper format for logging to `Splunk` or `ElasticSearch`, but it can also be used for logging to stdout as a string is issued.\n\n- [Features](#features)\n - [Custom fields](#adding-additional-fields-and-values)\n - [dict logging](#logging-with-a-dictionary)\n - [str logging](#logging-with-anything-else-such-as-a-string)\n- [Configuration](#configuration)\n - [Using dictConfig](#using-loggingconfigdictconfig)\n\n## Features\n\n### Adding additional fields and values\n\nYou can add fields to every message that is being logged.\nTo do so, specify the `fields` parameter to the `logging_json.JSONFormatter` instance.\n\nIt must be a dictionary where keys are the keys to be appended to the resulting JSON dictionary (if not already present) and the values can be one of the following:\n* An attribute of the logging record (non-exhaustive list can be found on [the python logging documentation](https://docs.python.org/3/library/logging.html#logrecord-attributes)).\n* If not found on the record, the value will be linked to the key.\n\n#### Logging exceptions, a specific case\n\nIf an exception is logged, the `exception` key will be appended to the resulting JSON dictionary.\n\nThis dictionary will contain 3 keys:\n* `type`: The name of the exception class (useful when the message is blank).\n* `message`: The str representation of the exception (usually the provided error message).\n* `stack`: The stack trace, formatted as a string.\n\nYou can rename the exception field key by setting the `exception_field_name` parameter with a new name for the key.\nIt is also possible to disable this behaviour by setting the `exception_field_name` parameter to `None` or an empty string\n\n### Logging with a dictionary\n\nThis formatter allows you to log dictionary as in the following:\n\n```python\nimport logging\n\nlogging.info({\"key\": \"value\", \"other key\": \"other value\"})\n```\n\nThe resulting JSON dictionary will be the one you provided (with the [additional fields](#adding-additional-fields-and-values)).\n\n### Logging with anything else (such as a string)\n\nAnything not logged using a dictionary will be handled by the standard formatter, and it can result in one of the 2 output:\n* A JSON dictionary, if [additional fields](#adding-additional-fields-and-values) are set or if `extra` parameter is used while logging, with the message available in the `message` key of the resulting JSON dictionary.\n Default `message` key name can be changed by `message_field_name` parameter of the `logging_json.JSONFormatter` instance.\n* The formatted record, if no [additional fields](#adding-additional-fields-and-values) are set.\n\nThis handles the usual string logging as in the following:\n\n```python\nimport logging\n\nlogging.info(\"This is my message\")\n```\n\n### Changing asctime representation\n\nYou can override the default representation of asctime (`2003-07-08 16:49:45,896`) based on two different scenarii:\n\n#### Without milliseconds\n\nSet `datefmt` parameter.\n\nSetting `datefmt` to `%Y-%m-%dT%H:%M:%S` would result in `2003-07-08T16:49:45`.\n\n#### With milliseconds\n\nSet `default_time_format` to something else than `%Y-%m-%d %H:%M:%S` to change the representation part without milliseconds.\nSet `default_msec_format` to something else than `%s,%03d` to change the representation milliseconds.\nNote that `%s` in `default_msec_format` is going to be replaced by the representation without milliseconds.\n\nSetting `default_time_format` to `%Y-%m-%dT%H:%M:%S` and `default_msec_format` to `%s.%03d` would result in `2003-07-08T16:49:45.896`.\n\n## Configuration\n\nYou can create a formatter instance yourself as in the following, or you can use a logging configuration.\n\n```python\nimport logging_json\n\nformatter = logging_json.JSONFormatter(fields={\n \"level_name\": \"levelname\",\n \"thread_name\": \"threadName\",\n \"process_name\": \"processName\"\n})\n```\n\n### Using logging.config.dictConfig\n\nYou can configure your logging as advertise by python, by using the `logging.config.dictConfig` function.\n\n#### dict configuration\n\n```python\nimport logging.config\n\nlogging.config.dictConfig({\n \"version\": 1,\n \"formatters\": {\n \"json\": {\n '()': 'logging_json.JSONFormatter',\n 'fields':{\n \"level_name\": \"levelname\",\n \"thread_name\": \"threadName\",\n \"process_name\": \"processName\"\n }\n }\n },\n \"handlers\": {\n \"standard_output\": {\n 'class': 'logging.StreamHandler',\n 'formatter': 'json',\n 'stream': 'ext://sys.stdout'\n },\n },\n \"loggers\": {\n \"my_app\": {\"level\": \"DEBUG\"}\n },\n \"root\": {\n \"level\": \"INFO\",\n \"handlers\": [\"standard_output\"]\n }\n})\n```\n\n#### YAML logging configuration\n\nYou can use YAML to store your logging configuration, as in the following sample:\n\n```python\nimport logging.config\nimport yaml\n\nwith open(\"path/to/logging_configuration.yaml\", \"r\") as config_file:\n logging.config.dictConfig(yaml.load(config_file))\n```\n\nWhere `logging_configuration.yaml` can be a file containing the following sample:\n\n```yaml\nversion: 1\nformatters:\n json:\n '()': logging_json.JSONFormatter\n fields:\n level_name: levelname\n thread_name: threadName\n process_name: processName\nhandlers:\n standard_output:\n class: logging.StreamHandler\n formatter: json\n stream: ext://sys.stdout\nloggers:\n my_app:\n level: DEBUG\nroot:\n level: INFO\n handlers: [standard_output]\n```\n\n## How to install\n1. [python 3.7+](https://www.python.org/downloads/) must be installed\n2. Use pip to install module:\n```sh\npython -m pip install logging_json\n```\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Colin Bounouar Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "JSON formatter for python logging",
"version": "0.5.0",
"project_urls": {
"changelog": "https://github.com/Colin-b/logging_json/blob/master/CHANGELOG.md",
"documentation": "https://colin-b.github.io/logging_json/",
"issues": "https://github.com/Colin-b/logging_json/issues",
"repository": "https://github.com/Colin-b/logging_json"
},
"split_keywords": [
"logging",
"json"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c55ba460ea20a1613080b5fc0f7a98aa6c2dcc8aace05eea354f39231f3e1237",
"md5": "8f387804c384bd7bb7b03e571f519c81",
"sha256": "ceefd2799a40bbce219b749c681c031868608b721272387d95e3fcc3ee2a8cae"
},
"downloads": -1,
"filename": "logging_json-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8f387804c384bd7bb7b03e571f519c81",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7201,
"upload_time": "2024-01-17T11:08:02",
"upload_time_iso_8601": "2024-01-17T11:08:02.316593Z",
"url": "https://files.pythonhosted.org/packages/c5/5b/a460ea20a1613080b5fc0f7a98aa6c2dcc8aace05eea354f39231f3e1237/logging_json-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c625e57be29b8ceccedd3c271b18b2fd6546bf3a8effa12d74fa116a0993589a",
"md5": "cebc5b8d0ae06d8413f056af9ca5cc1b",
"sha256": "ca4be5c56e7d5ee979dca284ee86ee6bfb6040ae92114c56c8cbefbdf3fa47c4"
},
"downloads": -1,
"filename": "logging_json-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "cebc5b8d0ae06d8413f056af9ca5cc1b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 12062,
"upload_time": "2024-01-17T11:08:03",
"upload_time_iso_8601": "2024-01-17T11:08:03.955940Z",
"url": "https://files.pythonhosted.org/packages/c6/25/e57be29b8ceccedd3c271b18b2fd6546bf3a8effa12d74fa116a0993589a/logging_json-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-17 11:08:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Colin-b",
"github_project": "logging_json",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "logging-json"
}
