{"id":41590297,"url":"https://github.com/fabien-marty/stlog","last_synced_at":"2026-01-24T09:13:15.806Z","repository":{"id":148380959,"uuid":"603175177","full_name":"fabien-marty/stlog","owner":"fabien-marty","description":"STandard STructured LOG (stlog) is Python 3.7+ structured logging library built on standard python logging and contextvars","archived":false,"fork":false,"pushed_at":"2026-01-23T01:30:34.000Z","size":746,"stargazers_count":5,"open_issues_count":9,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-23T18:47:20.964Z","etag":null,"topics":["contextvars","logging","logging-library","python3","structured-logging"],"latest_commit_sha":null,"homepage":"https://fabien-marty.github.io/stlog/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fabien-marty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-02-17T19:21:33.000Z","updated_at":"2025-10-17T01:31:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"2cb05510-5ae7-4690-8f72-c02229a98995","html_url":"https://github.com/fabien-marty/stlog","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/fabien-marty/stlog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabien-marty%2Fstlog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabien-marty%2Fstlog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabien-marty%2Fstlog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabien-marty%2Fstlog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabien-marty","download_url":"https://codeload.github.com/fabien-marty/stlog/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabien-marty%2Fstlog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28722367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T08:27:05.734Z","status":"ssl_error","status_checked_at":"2026-01-24T08:27:01.197Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["contextvars","logging","logging-library","python3","structured-logging"],"created_at":"2026-01-24T09:13:14.045Z","updated_at":"2026-01-24T09:13:15.801Z","avatar_url":"https://github.com/fabien-marty.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n \u003c!-- WARNING: generated from README.md.j2, do not modify this file manually but modify README.md.j2 instead\n      and execute 'poetry run invoke readme' to regenerate this README.md file --\u003e\n\n # stlog\n\n![Python Badge](https://raw.githubusercontent.com/fabien-marty/common/refs/heads/main/badges/python38plus.svg)\n[![UV Badge](https://raw.githubusercontent.com/fabien-marty/common/refs/heads/main/badges/uv.svg)](https://docs.astral.sh/uv/)\n[![Task Badge](https://raw.githubusercontent.com/fabien-marty/common/refs/heads/main/badges/task.svg)](https://taskfile.dev/)\n[![Mergify Badge](https://raw.githubusercontent.com/fabien-marty/common/refs/heads/main/badges/mergify.svg)](https://mergify.com/)\n[![Renovate Badge](https://raw.githubusercontent.com/fabien-marty/common/refs/heads/main/badges/renovate.svg)](https://docs.renovatebot.com/)\n[![MIT Licensed](https://raw.githubusercontent.com/fabien-marty/common/refs/heads/main/badges/mit.svg)](https://en.wikipedia.org/wiki/MIT_License)\n\n[Full documentation](https://fabien-marty.github.io/stlog/)\n\n\u003c!--intro-start--\u003e\n\n## What is it?\n\n**ST**andard **ST**ructured **LOG** (`stlog`) is Python 3.7+ [structured logging](#structured) library:\n\n- built on [standard python logging](https://docs.python.org/3/library/logging.html) and [contextvars](https://docs.python.org/3/library/contextvars.html)\n- very easy to configure with \"good/opinionated\" default values\n- which produces great output **for both humans and machines**\n- which believes in [Twelve-Factor App](https://12factor.net/) principles about config and logs\n- **dependency free** (but can use fancy stuff (colors, augmented traceback...) from [the rich library](https://github.com/Textualize/rich) *(if installed)*)\n\n## Features\n\n- **standard, standard, standard**: all stlog objects are built on [standard python logging](https://docs.python.org/3/library/logging.html) and are compatible with:\n    - other existing handlers, formatters...\n    - libraries which are using a standard logger *(and `stlog` can automatically reinject the global context in log records produced by these libraries)*\n- easy shorcuts to configure your logging\n- provides nice outputs **for humans AND for machines** *(you can produce both at the same time)*\n- structured with 4 levels of context you can choose or combine:\n    - a global one set by environment variables *(read at process start)*\n    - a kind of smart global one (thanks to [contextvars](https://docs.python.org/3/library/contextvars.html))\n    - a context linked to the logger object itself (defined during its building)\n    - a context linked to the log message itself\n- a lot of configuration you can do with environment variables (in the spirit of [Twelve-Factor App](https://12factor.net/) principles)\n\n## Non-Features\n\n- *\"A twelve-factor app never concerns itself with routing or storage of its output stream.\"*\n    - we are going to make an exception on this for log files\n    - but we don't want to introduce complex/network outputs like syslog, elasticsearch, loki...\n- standard, standard, standard: we do not want to move away from [standard python logging](https://docs.python.org/3/library/logging.html) compatibility \n\n## \u003ca name=\"structured\"\u003e\u003c/a\u003e What is *structured logging*?\n\n\u003e Structured logging is a technique used in software development to produce log messages that are more easily parsed and analyzed by machines. \n\u003e Unlike traditional logging, which typically consists of free-form text messages, structured logging uses a well-defined format that includes\n\u003e named fields with specific data types.\n\u003e \n\u003e The benefits of structured logging are many. By using a standard format, it becomes easier to automate the processing and analysis of logs.\n\u003e This can help with tasks like troubleshooting issues, identifying patterns, and monitoring system performance. It can also make it easier\n\u003e to integrate logs with other systems, such as monitoring and alerting tools.\n\u003e \n\u003e Some common formats for structured logging include JSON, XML, and key-value pairs. In each case, the format includes a set of fields that provide information about the log message, such as the severity level, timestamp, source of the message, and any relevant metadata.\n\u003e \n\u003e Structured logging is becoming increasingly popular as more developers recognize its benefits. Many logging frameworks and libraries now include support for structured logging, making it easier for developers to adopt the technique in their own projects.\n\u003e\n\u003e (thanks to ChatGPT)\n\n\u003c!--intro-end--\u003e\n\n## Quickstart\n\n\u003c!--quickstart-start--\u003e\n\n### Installation\n\n```\npip install stlog\n```\n\n### Very minimal usage\n\n```python\nimport stlog\n\nstlog.info(\"It works\", foo=\"bar\", x=123)\nstlog.critical(\"Houston, we have a problem!\")\n \n```\n\nOutput (without `rich` library installed):\n\n```\n2023-03-29T14:48:37Z root [   INFO   ] It works {foo=bar x=123}\n2023-03-29T14:48:37Z root [ CRITICAL ] Houston, we have a problem!\n \n```\n\nOutput (with `rich` library installed):\n\n![rich output](docs/python/qs0.svg)\n \n\n\n### Basic usage\n\n```python\nfrom stlog import getLogger, setup\n\n# Set the logging default configuration (human output on stderr)\nsetup()\n\n# Get a logger\nlogger = getLogger(__name__)\nlogger.info(\"It works\", foo=\"bar\", x=123)\nlogger.critical(\"Houston, we have a problem!\")\n \n```\n\nOutput (without `rich` library installed):\n\n```\n2023-03-29T14:48:37Z __main__ [   INFO   ] It works {foo=bar x=123}\n2023-03-29T14:48:37Z __main__ [ CRITICAL ] Houston, we have a problem!\n \n```\n\nOutput (with `rich` library installed):\n\n![rich output](docs/python/qs1.svg)\n \n\n### Usage with context\n\n```python\nfrom stlog import LogContext, getLogger, setup\n\n# Set the logging default configuration (human output on stderr)\nsetup()\n\n# ...\n\n# Set the (kind of) global execution context\n# (thread, worker, async friendly: one context by execution)\n# (for example in a wsgi/asgi middleware)\n# Note: ExecutionContext is a static class, so a kind of global singleton\nLogContext.reset_context()\nLogContext.add(request_id=\"4c2383f5\")\nLogContext.add(client_id=456, http_method=\"GET\")\n\n# ... in another file/class/...\n\n# Get a logger\nlogger = getLogger(__name__)\nlogger.info(\"It works\", foo=\"bar\", x=123)\nlogger.critical(\"Houston, we have a problem!\")\n \n```\n\nOutput (without `rich` library installed):\n\n```\n2023-03-29T14:48:37Z __main__ [   INFO   ] It works {client_id=456 foo=bar http_method=GET request_id=4c2383f5 x=123}\n2023-03-29T14:48:37Z __main__ [ CRITICAL ] Houston, we have a problem! {client_id=456 http_method=GET request_id=4c2383f5}\n \n```\n\nOutput (with `rich` library installed):\n\n![rich output](docs/python/qs2.svg)\n \n\nWhat about if you want to get a more parsing friendly output (for example in JSON on `stdout`) while keeping the human output on `stderr` (without any context)?\n\n```python\nimport sys\nfrom stlog import LogContext, getLogger, setup\nfrom stlog.output import StreamOutput\nfrom stlog.formatter import HumanFormatter, JsonFormatter\n\nsetup(\n    outputs=[\n        StreamOutput(\n            stream=sys.stderr,\n            formatter=HumanFormatter(exclude_extras_keys_fnmatchs=[\"*\"]),\n        ),\n        StreamOutput(stream=sys.stdout, formatter=JsonFormatter(indent=4)),\n    ]\n)\n\n# See previous example for details\nLogContext.reset_context()\nLogContext.add(request_id=\"4c2383f5\")\nLogContext.add(client_id=456, http_method=\"GET\")\nlogger = getLogger(__name__)\nlogger.info(\"It works\", foo=\"bar\", x=123)\nlogger.critical(\"Houston, we have a problem!\")\n \n```\n\nHuman output (on `stderr`):\n\n```\n2023-03-29T14:48:37Z __main__ [   INFO   ] It works\n2023-03-29T14:48:37Z __main__ [ CRITICAL ] Houston, we have a problem!\n \n```\n\nJSON ouput (on `stdout`) for machines:\n\n```json\n{\n    \"client_id\": 456,\n    \"foo\": \"bar\",\n    \"http_method\": \"GET\",\n    \"level\": \"INFO\",\n    \"logger\": \"__main__\",\n    \"message\": \"It works\",\n    \"request_id\": \"4c2383f5\",\n    \"source\": {\n        \"funcName\": \"\u003cmodule\u003e\",\n        \"lineno\": 21,\n        \"module\": \"qs3\",\n        \"path\": \"/path/filename.py\",\n        \"process\": 6789,\n        \"processName\": \"MainProcess\",\n        \"thread\": 12345,\n        \"threadName\": \"MainThread\"\n    },\n    \"time\": \"2023-03-29T14:48:37.000Z\",\n    \"x\": 123\n}\n{\n    \"client_id\": 456,\n    \"http_method\": \"GET\",\n    \"level\": \"CRITICAL\",\n    \"logger\": \"__main__\",\n    \"message\": \"Houston, we have a problem!\",\n    \"request_id\": \"4c2383f5\",\n    \"source\": {\n        \"funcName\": \"\u003cmodule\u003e\",\n        \"lineno\": 22,\n        \"module\": \"qs3\",\n        \"path\": \"/path/filename.py\",\n        \"process\": 6789,\n        \"processName\": \"MainProcess\",\n        \"thread\": 12345,\n        \"threadName\": \"MainThread\"\n    },\n    \"time\": \"2023-03-29T14:48:37.000Z\"\n}\n \n```\n\n\u003c!--quickstart-end--\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabien-marty%2Fstlog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabien-marty%2Fstlog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabien-marty%2Fstlog/lists"}