logust 0.3.2__tar.gz → 0.4.0__tar.gz

{logust-0.3.2 → logust-0.4.0}/.github/workflows/CI.yml

@@ -172,7 +172,7 @@ jobs:
           subject-path: 'wheels-*/*'
       - name: Install uv
         if: ${{ startsWith(github.ref, 'refs/tags/') }}
-        uses: astral-sh/setup-uv@v8.1.0
+        uses: astral-sh/setup-uv@v8.2.0
       - name: Publish to PyPI
         if: ${{ startsWith(github.ref, 'refs/tags/') }}
         run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/ 'wheels-*/*'

logust-0.4.0/.github/workflows/docs.yml

@@ -0,0 +1,85 @@
+name: Deploy Docs
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version label (e.g. 0.3.2). Leave empty to deploy "dev".'
+        required: false
+        default: ''
+      set_latest:
+        description: 'Update the "latest" alias to this version.'
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Cache pip
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-mkdocs-material-mike
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: pip install mkdocs-material mkdocstrings[python] mkdocs-minify-plugin mike
+
+      - name: Resolve version
+        id: version
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          INPUT_VERSION: ${{ inputs.version }}
+          INPUT_SET_LATEST: ${{ inputs.set_latest }}
+        run: |
+          if [ "$EVENT_NAME" = "release" ]; then
+            tag="$RELEASE_TAG"
+            version="${tag#v}"
+            printf 'version=%s\n' "$version" >> "$GITHUB_OUTPUT"
+            printf 'alias=latest\n' >> "$GITHUB_OUTPUT"
+          else
+            version="$INPUT_VERSION"
+            if [ -z "$version" ]; then
+              version="dev"
+            fi
+            printf 'version=%s\n' "$version" >> "$GITHUB_OUTPUT"
+            if [ "$INPUT_SET_LATEST" = "true" ]; then
+              printf 'alias=latest\n' >> "$GITHUB_OUTPUT"
+            else
+              printf 'alias=\n' >> "$GITHUB_OUTPUT"
+            fi
+          fi
+
+      - name: Deploy with mike
+        env:
+          MIKE_VERSION: ${{ steps.version.outputs.version }}
+          MIKE_ALIAS: ${{ steps.version.outputs.alias }}
+        run: |
+          if [ -n "$MIKE_ALIAS" ]; then
+            mike deploy --push --update-aliases "$MIKE_VERSION" "$MIKE_ALIAS"
+            mike set-default --push "$MIKE_ALIAS"
+          else
+            mike deploy --push "$MIKE_VERSION"
+          fi

{logust-0.3.2 → logust-0.4.0}/.github/workflows/freethreaded-release.yml

@@ -84,7 +84,7 @@ jobs:
           subject-path: 'wheels-*/*'
       - name: Install uv
         if: ${{ startsWith(github.ref, 'refs/tags/') }}
-        uses: astral-sh/setup-uv@v8.1.0
+        uses: astral-sh/setup-uv@v8.2.0
       - name: Publish to PyPI
         if: ${{ startsWith(github.ref, 'refs/tags/') }}
         run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/ 'wheels-*/*'

{logust-0.3.2 → logust-0.4.0}/.github/workflows/test.yml

@@ -70,7 +70,7 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
+        uses: astral-sh/setup-uv@v8.2.0
 
       - name: Install dependencies and build
         run: |
@@ -83,11 +83,37 @@ jobs:
 
       - name: Upload coverage
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
-        uses: codecov/codecov-action@v6
+        uses: codecov/codecov-action@v7
         with:
           files: ./coverage.xml
           fail_ci_if_error: false
 
+  web-integration-test:
+    name: Web Integration Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
+      - name: Install dependencies and build
+        run: |
+          uv venv
+          uv pip install maturin pytest httpx fastapi starlette uuid-utils
+          uv run maturin develop
+
+      - name: Run web integration tests
+        run: uv run pytest tests/test_web_integration.py -v
+
   lint:
     name: Python Lint
     runs-on: ubuntu-latest
@@ -103,7 +129,7 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
+        uses: astral-sh/setup-uv@v8.2.0
 
       - name: Install dependencies and build
         run: |

{logust-0.3.2 → logust-0.4.0}/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-06-14
+
+### Added
+- **Canonical request events for web integrations**: `logust.contrib` now provides `canonical_event()`, `add_event_fields()`, `clear_event_fields()`, `get_event_fields()`, `get_current_event()`, and `TailSampler`, and Starlette/FastAPI middleware can emit one `http.request` event per request with request/response fields, endpoint-enriched extras, and tail sampling for errors and slow requests. (#38)
+
+### Changed
+- **JSON extra values handle more Python types**: `serialize=True` now emits `bytes` / `bytearray` extras as UTF-8 strings with replacement for invalid bytes, `set` / `frozenset` extras as arrays, `datetime` / `date` / `time` extras as `.isoformat()` strings, and `Enum` extras via their `.value` converted with the same rules. Text formatting (`{extra[key]}`) and Python callback records still use the existing `str(value)` view. Other object types such as `Decimal`, `UUID`, `Path`, and `complex` continue to fall back to `str(value)` in JSON.
+
 ## [0.3.2] - 2026-05-07
 
 ### Added
@@ -131,7 +139,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 1.3x faster than Python standard logging
 - Lock-free fast path for filtered messages
 
-[Unreleased]: https://github.com/yamaaaaaa31/logust/compare/v0.3.2...HEAD
+[Unreleased]: https://github.com/yamaaaaaa31/logust/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/yamaaaaaa31/logust/compare/v0.3.2...v0.4.0
 [0.3.2]: https://github.com/yamaaaaaa31/logust/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/yamaaaaaa31/logust/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/yamaaaaaa31/logust/compare/v0.2.1...v0.3.0

{logust-0.3.2 → logust-0.4.0}/Cargo.lock

@@ -19,27 +19,27 @@ dependencies = [
 
 [[package]]
 name = "autocfg"
-version = "1.5.0"
+version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
 
 [[package]]
 name = "bitflags"
-version = "2.11.1"
+version = "2.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
+checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
 
 [[package]]
 name = "bumpalo"
-version = "3.20.2"
+version = "3.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
 [[package]]
 name = "cc"
-version = "1.2.61"
+version = "1.2.64"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d16d90359e986641506914ba71350897565610e87ce0ad9e6f28569db3dd5c6d"
+checksum = "dad887fd958be91b5098c0248def011f4523ab786cd411be668777e55063501f"
 dependencies = [
  "find-msvc-tools",
  "shlex",
@@ -53,9 +53,9 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "chrono"
-version = "0.4.44"
+version = "0.4.45"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c673075a2e0e5f4a1dde27ce9dee1ea4558c7ffe648f576438a20ca1d2acc4b0"
+checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
 dependencies = [
  "iana-time-zone",
  "js-sys",
@@ -182,13 +182,12 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "js-sys"
-version = "0.3.98"
+version = "0.3.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "67df7112613f8bfd9150013a0314e196f4800d3201ae742489d999db2f979f08"
+checksum = "03d04c30968dffe80775bd4d7fb676131cd04a1fb46d2686dbffbaec2d9dfd31"
 dependencies = [
  "cfg-if",
  "futures-util",
- "once_cell",
  "wasm-bindgen",
 ]
 
@@ -209,13 +208,13 @@ dependencies = [
 
 [[package]]
 name = "log"
-version = "0.4.29"
+version = "0.4.32"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
+checksum = "953f07c43838f8e6f9758cab68bf5bed85465e7587ebe0b823f1bcd81978ad3a"
 
 [[package]]
 name = "logust"
-version = "0.3.2"
+version = "0.4.0"
 dependencies = [
  "chrono",
  "colored",
@@ -231,9 +230,9 @@ dependencies = [
 
 [[package]]
 name = "memchr"
-version = "2.8.0"
+version = "2.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
+checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
 
 [[package]]
 name = "miniz_oxide"
@@ -306,9 +305,9 @@ dependencies = [
 
 [[package]]
 name = "pyo3"
-version = "0.28.3"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "91fd8e38a3b50ed1167fb981cd6fd60147e091784c427b8f7183a7ee32c31c12"
+checksum = "cd274650b21d4bfc26a0a47587962c1edb425f69287324355cd040c3ea66071c"
 dependencies = [
  "libc",
  "once_cell",
@@ -320,18 +319,18 @@ dependencies = [
 
 [[package]]
 name = "pyo3-build-config"
-version = "0.28.3"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e368e7ddfdeb98c9bca7f8383be1648fd84ab466bf2bc015e94008db6d35611e"
+checksum = "c5e2a7d2f0d013342f295c048ad19237add5154a55b1c5a254c0ec93d4109078"
 dependencies = [
  "target-lexicon",
 ]
 
 [[package]]
 name = "pyo3-ffi"
-version = "0.28.3"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7f29e10af80b1f7ccaf7f69eace800a03ecd13e883acfacc1e5d0988605f651e"
+checksum = "ca85c467da1bbc8d866eea5deff9cf29ea5f7785054a17da36e65bda9c05845b"
 dependencies = [
  "libc",
  "pyo3-build-config",
@@ -339,9 +338,9 @@ dependencies = [
 
 [[package]]
 name = "pyo3-macros"
-version = "0.28.3"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "df6e520eff47c45997d2fc7dd8214b25dd1310918bbb2642156ef66a67f29813"
+checksum = "9ac53762fd065daa3194dd09337a38bd793a188100fd1a9304c4ab312d901771"
 dependencies = [
  "proc-macro2",
  "pyo3-macros-backend",
@@ -351,13 +350,12 @@ dependencies = [
 
 [[package]]
 name = "pyo3-macros-backend"
-version = "0.28.3"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c4cdc218d835738f81c2338f822078af45b4afdf8b2e33cbb5916f108b813acb"
+checksum = "4ca3a1557399783172dc5bf39cfca835157732532cba56b71d2292161e53b362"
 dependencies = [
  "heck",
  "proc-macro2",
- "pyo3-build-config",
  "quote",
  "syn",
 ]
@@ -424,9 +422,9 @@ dependencies = [
 
 [[package]]
 name = "serde_json"
-version = "1.0.149"
+version = "1.0.150"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
 dependencies = [
  "itoa",
  "memchr",
@@ -437,9 +435,9 @@ dependencies = [
 
 [[package]]
 name = "shlex"
-version = "1.3.0"
+version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
 
 [[package]]
 name = "simd-adler32"
@@ -455,9 +453,9 @@ checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
 
 [[package]]
 name = "smallvec"
-version = "1.15.1"
+version = "1.15.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
 
 [[package]]
 name = "syn"
@@ -484,9 +482,9 @@ checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.121"
+version = "0.2.125"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "49ace1d07c165b0864824eee619580c4689389afa9dc9ed3a4c75040d82e6790"
+checksum = "8ddb3f79143bced6de84270411622a2699cee572fc0875aeaf1e7867cf9fca1a"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -497,9 +495,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.121"
+version = "0.2.125"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8e68e6f4afd367a562002c05637acb8578ff2dea1943df76afb9e83d177c8578"
+checksum = "4e21a184b13fb19e157296e2c46056aec9092264fab83e4ba59e68c61b323c3d"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -507,9 +505,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.121"
+version = "0.2.125"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d95a9ec35c64b2a7cb35d3fead40c4238d0940c86d107136999567a4703259f2"
+checksum = "fecefd9c35bd935a20fc3fc344b5f29138961e4f47fb03297d88f2587afb5ebd"
 dependencies = [
  "bumpalo",
  "proc-macro2",
@@ -520,9 +518,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.121"
+version = "0.2.125"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c4e0100b01e9f0d03189a92b96772a1fb998639d981193d7dbab487302513441"
+checksum = "23939e44bb9a5d7576fa2b563dc2e136628f1224e88a8deed09e04858b77871f"
 dependencies = [
  "unicode-ident",
 ]

{logust-0.3.2 → logust-0.4.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "logust"
-version = "0.3.2"
+version = "0.4.0"
 edition = "2024"
 readme = "README.md"
 
@@ -9,7 +9,7 @@ name = "_logust"
 crate-type = ["cdylib"]
 
 [dependencies]
-pyo3 = { version = "0.28", features = ["extension-module"] }
+pyo3 = { version = "0.29.0", features = ["extension-module"] }
 chrono = { version = "0.4", features = ["serde"] }
 colored = "3.0"
 flate2 = "1.0"

{logust-0.3.2 → logust-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logust
-Version: 0.3.2
+Version: 0.4.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -68,6 +68,7 @@ A fast, Rust-powered Python logging library inspired by [loguru](https://github.
 - **Custom Levels** - Define your own log levels with colors and icons
 - **Color Markup** - Inline `<red>color</red>` tags in log messages
 - **Async Writing** - Optional thread-safe async file writes with `enqueue=True`
+- **Canonical Events** - Request-scoped wide events with built-in tail sampling
 - **Free-Threaded Python** - Release automation builds wheels for CPython 3.13t and 3.14t on Linux and macOS
 - **Zero-Config Integrations** - Built-in support for standard logging, FastAPI, and function timing
 
@@ -503,6 +504,14 @@ async def fetch_user(user_id):
 
 ### FastAPI / Starlette Middleware
 
+Install the matching extra for web middleware:
+
+```bash
+pip install "logust[fastapi]"
+# or
+pip install "logust[starlette]"
+```
+
 ```python
 from fastapi import FastAPI
 from logust.contrib.starlette import setup_fastapi
@@ -516,6 +525,45 @@ setup_fastapi(app, skip_routes=["/health"])
 # - Standard logging redirected to logust
 ```
 
+### Canonical Request Events
+
+Emit one wide event at request completion, then keep high-value events with tail sampling:
+
+```python
+from fastapi import FastAPI
+from logust.contrib import add_event_fields
+from logust.contrib.starlette import setup_fastapi
+
+app = FastAPI()
+
+setup_fastapi(
+    app,
+    canonical=True,
+    sample_rate=0.02,
+    slow_ms=1000,
+    skip_routes=["/health"],
+)
+
+@app.post("/checkout")
+async def checkout(user_id: str):
+    add_event_fields({"user.id": user_id}, feature_checkout_v2=True)
+    return {"ok": True}
+```
+
+The middleware logs a single `http.request` event with request, response, timing,
+trace context, and any fields added during the request. Errors and slow requests
+are kept even when normal successful traffic is sampled. JSON sinks preserve
+numeric, boolean, list, dict, and null extra values as native JSON types. Incoming
+`x-request-id` values are preserved; otherwise Logust generates a short
+`uuid4`-based request ID.
+`sample_rate` must be between `0.0` and `1.0`, and `slow_ms` must be non-negative.
+
+See [docs/guide/canonical-events.md](docs/guide/canonical-events.md) and
+[examples/08_fastapi_integration.py](examples/08_fastapi_integration.py) for the
+full contract and a runnable FastAPI app.
+
+More runnable examples are listed in [examples/README.md](examples/README.md).
+
 ## Complete API Reference
 
 ### Logger Methods

{logust-0.3.2 → logust-0.4.0}/README.md

@@ -22,6 +22,7 @@ A fast, Rust-powered Python logging library inspired by [loguru](https://github.
 - **Custom Levels** - Define your own log levels with colors and icons
 - **Color Markup** - Inline `<red>color</red>` tags in log messages
 - **Async Writing** - Optional thread-safe async file writes with `enqueue=True`
+- **Canonical Events** - Request-scoped wide events with built-in tail sampling
 - **Free-Threaded Python** - Release automation builds wheels for CPython 3.13t and 3.14t on Linux and macOS
 - **Zero-Config Integrations** - Built-in support for standard logging, FastAPI, and function timing
 
@@ -457,6 +458,14 @@ async def fetch_user(user_id):
 
 ### FastAPI / Starlette Middleware
 
+Install the matching extra for web middleware:
+
+```bash
+pip install "logust[fastapi]"
+# or
+pip install "logust[starlette]"
+```
+
 ```python
 from fastapi import FastAPI
 from logust.contrib.starlette import setup_fastapi
@@ -470,6 +479,45 @@ setup_fastapi(app, skip_routes=["/health"])
 # - Standard logging redirected to logust
 ```
 
+### Canonical Request Events
+
+Emit one wide event at request completion, then keep high-value events with tail sampling:
+
+```python
+from fastapi import FastAPI
+from logust.contrib import add_event_fields
+from logust.contrib.starlette import setup_fastapi
+
+app = FastAPI()
+
+setup_fastapi(
+    app,
+    canonical=True,
+    sample_rate=0.02,
+    slow_ms=1000,
+    skip_routes=["/health"],
+)
+
+@app.post("/checkout")
+async def checkout(user_id: str):
+    add_event_fields({"user.id": user_id}, feature_checkout_v2=True)
+    return {"ok": True}
+```
+
+The middleware logs a single `http.request` event with request, response, timing,
+trace context, and any fields added during the request. Errors and slow requests
+are kept even when normal successful traffic is sampled. JSON sinks preserve
+numeric, boolean, list, dict, and null extra values as native JSON types. Incoming
+`x-request-id` values are preserved; otherwise Logust generates a short
+`uuid4`-based request ID.
+`sample_rate` must be between `0.0` and `1.0`, and `slow_ms` must be non-negative.
+
+See [docs/guide/canonical-events.md](docs/guide/canonical-events.md) and
+[examples/08_fastapi_integration.py](examples/08_fastapi_integration.py) for the
+full contract and a runnable FastAPI app.
+
+More runnable examples are listed in [examples/README.md](examples/README.md).
+
 ## Complete API Reference
 
 ### Logger Methods

{logust-0.3.2 → logust-0.4.0}/docs/api.md

@@ -7,6 +7,8 @@ Quick reference for the public API. For examples, see the Guide.
 - **Logger**: Log methods, handlers, levels, context, options, callbacks
 - **LogLevel**: Enum values for severity
 - **Parsing**: `parse()` and `parse_json()` helpers
+- **Contrib**: standard logging interception, decorators, canonical events,
+  FastAPI/Starlette middleware
 
 ## Logger
 
@@ -176,6 +178,93 @@ LogLevel.Critical   # 50
 
 ---
 
+## Contrib
+
+Utilities in `logust.contrib` are optional helpers built on top of the core
+logger.
+
+### Standard logging interception
+
+```python
+from logust.contrib import InterceptHandler, intercept_logging
+
+intercept_logging()
+```
+
+### Function timing
+
+```python
+from logust.contrib import debug_fn, log_fn
+
+@log_fn
+def work():
+    pass
+
+@debug_fn
+async def async_work():
+    pass
+```
+
+### Canonical event helpers
+
+```python
+from logust.contrib import (
+    TailSampler,
+    add_event_fields,
+    canonical_event,
+    clear_event_fields,
+    get_current_event,
+    get_event_fields,
+)
+
+with canonical_event({"event": "job"}) as event:
+    add_event_fields(job_id="job_123")
+```
+
+`add_event_fields(fields=None, **kwargs)` returns `True` when an event is active
+and `False` outside a canonical event context.
+
+`TailSampler` accepts:
+
+```python
+TailSampler(
+    rate=1.0,                  # 0.0 to 1.0
+    always_keep_errors=True,
+    slow_ms=None,              # non-negative milliseconds
+    keep_if=None,              # predicate(event) -> bool
+)
+```
+
+### FastAPI / Starlette
+
+Install web extras before importing the middleware:
+
+```bash
+pip install "logust[fastapi]"
+# or
+pip install "logust[starlette]"
+```
+
+```python
+from logust.contrib.starlette import (
+    RequestLoggerMiddleware,
+    get_request_id,
+    setup_fastapi,
+)
+
+setup_fastapi(
+    app,
+    canonical=True,
+    sample_rate=0.05,
+    slow_ms=1000,
+    skip_routes=["/health"],
+)
+```
+
+For the full event contract, see [Canonical Events](guide/canonical-events.md).
+
+---
+
 ## Type definitions
 
 ### LogRecord