1 files changed, 57 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..78bbda9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,57 @@
+# logformat - logfmt logging for Python
+
+* implements the same value escaping as the [logfmt library] used by Grafana Loki
+* implements a `logging.Formatter` so it works with any library using the standard library logging
+* implements a convenience wrapper around `logging.Logging` for specifying structured fields via `kwargs`
+
+```python
+import logging
+
+import logformat
+
+logfmt_handler = logging.StreamHandler()
+logfmt_handler.setFormatter(logformat.LogfmtFormatter())
+logging.basicConfig(handlers=[logfmt_handler], level=logging.INFO)
+
+logger = logformat.get_logger()
+
+logger.warning("this seems off", some_id=33)
+```
+
+Will output a line like:
+
+```
+time=2025-03-23T06:21:36Z level=warning msg="this seems off" some_id=33
+```
+
+`exc_info` and `stack_info` are supported via `backtrace=True` and `stack=True`
+(which will add same-named fields).
+
+In the main method of a script you should always catch any exception and log
+them as errors, so that unexpected errors show up properly in your log file.
+This library makes this easy by providing a `log_uncaught` decorator:
+
+```python
+logger = logformat.get_logger()
+
+@logger.log_uncaught
+def run():
+    # your script
+    ...
+```
+
+This library intentionally doesn't provide any pretty terminal output but the
+produced logs can be viewed with the [logfmt CLI] (since that tool again uses
+the [logfmt library] that this library is compatible with).
+
+## Alternatives
+
+* structlog's `get_logger` returns `Any`.
+  While there's a typed alternative that's a bit of a footgun.
+
+* logfmter doesn't include the time by default, names the time field `when` by default
+  and the level field `at` by default, doesn't use ISO dates by default
+  and isn't compatible with the Go [logfmt library] as of March 2025
+
+[logfmt library]: https://github.com/go-logfmt/logfmt
+[logfmt CLI]: https://github.com/TheEdgeOfRage/logfmt