logstruct


Namelogstruct JSON
Version 0.1.1 PyPI version JSON
download
home_pageNone
SummaryStructured stdlib logging
upload_time2025-01-25 00:07:27
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9
licenseBSD-3-Clause
keywords logging log structured structure json stdlib
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            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"
}
        
Elapsed time: 2.22679s