logstruct
=========
Everything you need to turn Python stdlib logging into a proper structured logging library. Rather
than fighting ``logging``, let's live with it.
.. code:: python
import logging
import logstruct
logging.basicConfig(level=logging.INFO)
logging.root.handlers[0].formatter = logstruct.StructuredFormatter()
log = logstruct.getLogger(__name__)
log.info("Message with data", key1="val1", data=object())
This prints the following JSON to ``stderr`` that, if pretty-printed, looks as follows:
.. code:: json
{
"time": "2025-01-19 09:49:36,489",
"logger": "__main__",
"level": "INFO",
"func": "<module>",
"line": 8,
"message": "Message with data",
"key1": "val1",
"data": "<object object at 0x765a8a9806f0>"
}
`Full documentation <https://logstruct.readthedocs.org>`_
Features
--------
- `StructuredLogger <logstruct.StructuredLogger>` - a replacement for `logging.Logger`
with a simplified interface for adding structured data to logs. (`Usage <logger_usage>`)
- `StructuredFormatter <logstruct.StructuredFormatter>` - a `logging.Formatter`
implementation that formats log records as JSON. (`Usage <formatter_usage>`)
- `contextual information <context_usage>` to log records with `logstruct.context_scope`.
- Easy to use and simple configure, **no dependencies**.
- Seamlessly integrates with any code using stdlib `logging`, e.g. Sentry SDK.
- Human readable output for development - see `demo_dev_mode.py <dev_mode_logging>`.
Design principles
-----------------
#. Play well with ``logging``.
#. Be small.
Considerations
--------------
If the standard logging library adds a new kwarg to log methods, e.g. ``logging.Logger.info``, this kwarg,
when passed to ``StructuredLogger``, will be merged into the ``extra`` dict until it is added to
``StructuredLogger`` methods. Using ``StructuredLogger`` is optional.
Logging integrations that rely on monkey-patching ``logging.Formatter.format`` won't see it called because
``StructuredFormatter`` doesn't call this method. Such reliance is extremely unlikely.
Development
-----------
While the project source is dependency-free, `PDM <https://pdm-project.org>`_ is used for management of dev
(testing) and doc (Sphinx/ReadTheDocs) dependencies.
.. code:: sh
pdm install
You should be able to get away with not using PDM as long as you don't change dependencies.
.. code:: sh
pip install --editable . -r requirements-dev.txt -r requirements-doc.txt
When dependencies are changed, they need to be locked. This will also write requirements-{dev,doc}.txt.
.. code:: sh
pdm lock -G :all
Tests are run with pytest and Sphinx’s `doctest` target.
.. code:: sh
pdm run pytest
pdm run sphinx-build docs docs/_build -b doctest
``Setuptools-SCM`` and ``build`` are used for building the project. Publishing is done in the CI, using the
old twine method, even though PDM could be used.
British English is used in the project, out of fear of losing my settled status.
Raw data
{
"_id": null,
"home_page": null,
"name": "logstruct",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "logging, log, structured, structure, json, stdlib",
"author": null,
"author_email": "Karoline Pauls <code@karolinepauls.com>",
"download_url": "https://files.pythonhosted.org/packages/78/8e/4303329845a8258c2ece4b66a669ede8c8669ef561b240276f9129201192/logstruct-0.1.1.tar.gz",
"platform": null,
"description": "logstruct\n=========\n\nEverything you need to turn Python stdlib logging into a proper structured logging library. Rather\nthan fighting ``logging``, let's live with it.\n\n.. code:: python\n\n import logging\n import logstruct\n\n logging.basicConfig(level=logging.INFO)\n logging.root.handlers[0].formatter = logstruct.StructuredFormatter()\n\n log = logstruct.getLogger(__name__)\n log.info(\"Message with data\", key1=\"val1\", data=object())\n\nThis prints the following JSON to ``stderr`` that, if pretty-printed, looks as follows:\n\n.. code:: json\n\n {\n \"time\": \"2025-01-19 09:49:36,489\",\n \"logger\": \"__main__\",\n \"level\": \"INFO\",\n \"func\": \"<module>\",\n \"line\": 8,\n \"message\": \"Message with data\",\n \"key1\": \"val1\",\n \"data\": \"<object object at 0x765a8a9806f0>\"\n }\n\n`Full documentation <https://logstruct.readthedocs.org>`_\n\nFeatures\n--------\n\n- `StructuredLogger <logstruct.StructuredLogger>` - a replacement for `logging.Logger`\n with a simplified interface for adding structured data to logs. (`Usage <logger_usage>`)\n- `StructuredFormatter <logstruct.StructuredFormatter>` - a `logging.Formatter`\n implementation that formats log records as JSON. (`Usage <formatter_usage>`)\n- `contextual information <context_usage>` to log records with `logstruct.context_scope`.\n- Easy to use and simple configure, **no dependencies**.\n- Seamlessly integrates with any code using stdlib `logging`, e.g. Sentry SDK.\n- Human readable output for development - see `demo_dev_mode.py <dev_mode_logging>`.\n\nDesign principles\n-----------------\n\n#. Play well with ``logging``.\n#. Be small.\n\nConsiderations\n--------------\n\nIf the standard logging library adds a new kwarg to log methods, e.g. ``logging.Logger.info``, this kwarg,\nwhen passed to ``StructuredLogger``, will be merged into the ``extra`` dict until it is added to\n``StructuredLogger`` methods. Using ``StructuredLogger`` is optional.\n\nLogging integrations that rely on monkey-patching ``logging.Formatter.format`` won't see it called because\n``StructuredFormatter`` doesn't call this method. Such reliance is extremely unlikely.\n\nDevelopment\n-----------\n\nWhile the project source is dependency-free, `PDM <https://pdm-project.org>`_ is used for management of dev\n(testing) and doc (Sphinx/ReadTheDocs) dependencies.\n\n.. code:: sh\n\n pdm install\n\nYou should be able to get away with not using PDM as long as you don't change dependencies.\n\n.. code:: sh\n\n pip install --editable . -r requirements-dev.txt -r requirements-doc.txt\n\nWhen dependencies are changed, they need to be locked. This will also write requirements-{dev,doc}.txt.\n\n.. code:: sh\n\n pdm lock -G :all\n\nTests are run with pytest and Sphinx\u2019s `doctest` target.\n\n.. code:: sh\n\n pdm run pytest\n pdm run sphinx-build docs docs/_build -b doctest\n\n``Setuptools-SCM`` and ``build`` are used for building the project. Publishing is done in the CI, using the\nold twine method, even though PDM could be used.\n\nBritish English is used in the project, out of fear of losing my settled status.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Structured stdlib logging",
"version": "0.1.1",
"project_urls": {
"Changelog": "https://gitlab.com/karolinepauls/logstruct/-/blob/master/CHANGELOG.rst",
"Documentation": "https://logstruct.readthedocs.io/",
"Source": "https://gitlab.com/karolinepauls/logstruct"
},
"split_keywords": [
"logging",
" log",
" structured",
" structure",
" json",
" stdlib"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "88d7b061f1122233f04ee819b41c50d2b1e4a0ae4ba1d29317a2eeb597e28be7",
"md5": "6c4b7879fb89552334b26ee9b2d6fbd9",
"sha256": "d1772261fbb849aed541ba84b28e6f037e46f45c060ec55dcc0cc7a4a76667d8"
},
"downloads": -1,
"filename": "logstruct-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c4b7879fb89552334b26ee9b2d6fbd9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 11613,
"upload_time": "2025-01-25T00:07:25",
"upload_time_iso_8601": "2025-01-25T00:07:25.352870Z",
"url": "https://files.pythonhosted.org/packages/88/d7/b061f1122233f04ee819b41c50d2b1e4a0ae4ba1d29317a2eeb597e28be7/logstruct-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "788e4303329845a8258c2ece4b66a669ede8c8669ef561b240276f9129201192",
"md5": "d6d1657a898f3e8e4475763ce275caba",
"sha256": "58998cbd7eaa4d25ddf461f3f59b8064e3a1cfd870a30da92bf959a0531ca2e1"
},
"downloads": -1,
"filename": "logstruct-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "d6d1657a898f3e8e4475763ce275caba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 42227,
"upload_time": "2025-01-25T00:07:27",
"upload_time_iso_8601": "2025-01-25T00:07:27.654423Z",
"url": "https://files.pythonhosted.org/packages/78/8e/4303329845a8258c2ece4b66a669ede8c8669ef561b240276f9129201192/logstruct-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-25 00:07:27",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "karolinepauls",
"gitlab_project": "logstruct",
"lcname": "logstruct"
}
JSON