potik 0.1.0__tar.gz

potik-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+**/.venv
+
+# Environment variables
+**/.env
+**/.env.*
+!**/.env.example
+
+# local
+.local/
+
+# benchmark outputs
+benchmarks/results/
+benchmarks/comparison/results/
+
+# docs build output
+site/

potik-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+potik follows [Semantic Versioning](https://semver.org). Before 1.0, a minor version can break the API.
+
+## 0.1.0 (2026-10-29)
+
+The first release.
+
+- Async handlers whose outputs commit with the input's offset in one Kafka transaction, so `read_committed` consumers see each output exactly once.
+- Concurrent partitions, with records in order within each partition, and handlers that may run for as long as they need.
+- Opt-in key concurrency, which runs a topic's records with different keys concurrently and keeps each key's records in order, with exactly-once outputs.
+- Typed topics with pydantic, msgspec, and text serdes, and async serdes for formats that need I/O to decode.
+- Exception rules that retry handlers, skip records, or write dead letters. A failure without a rule stops only its partition.
+- Concurrency limits, a startup check for missing topics, and OpenTelemetry tracing and metrics as middleware.
+- Shutdown on SIGTERM, and liveness and readiness checks for Kubernetes probes.
+- A `Producer` that sends outside transactions, and a `MockCluster` for tests.
+- A `ReplyListener` that awaits replies to requests in the API replica that sent them.
+- `potik.core`, the runtime without the typed layer.

potik-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danylo Kielsa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

potik-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: potik
+Version: 0.1.0
+Summary: An async Python framework for exactly-once Kafka services.
+Project-URL: Homepage, https://jarv1s10.github.io/potik/
+Project-URL: Documentation, https://jarv1s10.github.io/potik/
+Project-URL: Repository, https://github.com/Jarv1s10/potik
+Project-URL: Issues, https://github.com/Jarv1s10/potik/issues
+Project-URL: Changelog, https://github.com/Jarv1s10/potik/blob/main/CHANGELOG.md
+Author-email: Danylo Kielsa <danylo.kielsa@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anyio,asyncio,confluent-kafka,exactly-once,kafka,stream-processing,transactions
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AnyIO
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.14.0
+Requires-Dist: confluent-kafka>=2.16.0
+Requires-Dist: typing-extensions>=4.14.0
+Provides-Extra: msgspec
+Requires-Dist: msgspec>=0.19.0; extra == 'msgspec'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.30.0; extra == 'otel'
+Requires-Dist: opentelemetry-semantic-conventions>=0.51b0; extra == 'otel'
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.10.0; extra == 'pydantic'
+Description-Content-Type: text/markdown
+
+# potik
+
+[![PyPI](https://img.shields.io/pypi/v/potik)](https://pypi.org/project/potik/) [![Python](https://img.shields.io/pypi/pyversions/potik)](https://pypi.org/project/potik/) [![License](https://img.shields.io/pypi/l/potik)](https://github.com/Jarv1s10/potik/blob/main/LICENSE)
+
+potik is an async Python framework for Kafka services that read records, process them, and write new ones. A handler returns its output records, and potik commits them in one Kafka transaction with the input's offset. Consumers downstream see each output exactly once, even after a crash or a rebalance.
+
+> [!WARNING]
+> potik is alpha. Its API can change between minor versions until 1.0.
+
+## Example
+
+```python
+from typing import Annotated
+
+import anyio
+from pydantic import BaseModel
+
+import potik
+from potik import Config, Key, ProducerRecord, Router, Topic
+from potik.serde import PydanticJson
+
+
+class Order(BaseModel):
+    sku: str
+    amount: float
+
+
+class Accepted(BaseModel):
+    sku: str
+    total: float
+
+
+json = PydanticJson()
+orders = Topic("orders", Order, serde=json)
+accepted = Topic("orders.accepted", Accepted, serde=json)
+router = Router()
+
+
+@router.handler(orders)
+async def accept(order: Order, customer: Annotated[str, Key()]) -> ProducerRecord:
+    return accepted(Accepted(sku=order.sku, total=order.amount * 1.2), key=customer)
+
+
+runtime = potik.build_runtime(Config(bootstrap_servers="localhost:9092", group_id="acceptor"), [router])
+anyio.run(runtime.run)
+```
+
+## Features
+
+- One transactional producer per app commits outputs and offsets for all partitions together (KIP-447).
+- Partitions run concurrently, and records within a partition run in order, or with key concurrency, in order per key. A handler can run for minutes without dropping the app from its consumer group.
+- A `Topic` declares its value and key types, and type checkers check every record a handler returns.
+- A failing handler stops only its own partition. Middleware adds retries and dead letter topics.
+- The app shuts down on SIGTERM after it commits finished work. Its liveness and readiness checks are ready to serve as Kubernetes probes from any HTTP framework.
+- OpenTelemetry tracing follows each record through its handler, and its outputs to the transaction that commits them.
+
+## Install
+
+potik needs Python 3.12+ and Kafka 4.0+.
+
+```sh
+uv add "potik[pydantic]"
+```
+
+## Documentation
+
+- [Quickstart](https://jarv1s10.github.io/potik/quickstart/)
+- [Runtime](https://jarv1s10.github.io/potik/runtime/): delivery, failures, configuration, and production
+- [Middleware](https://jarv1s10.github.io/potik/middleware/): retries, dead letters, concurrency limits, tracing, and metrics
+- [Typed API](https://jarv1s10.github.io/potik/typed/): topics, serdes, handlers, and testing
+- [Producer](https://jarv1s10.github.io/potik/producer/) and [request-reply](https://jarv1s10.github.io/potik/request-reply/)
+
+To contribute, see [CONTRIBUTING.md](https://github.com/Jarv1s10/potik/blob/main/CONTRIBUTING.md).

potik-0.1.0/README.md

@@ -0,0 +1,73 @@
+# potik
+
+[![PyPI](https://img.shields.io/pypi/v/potik)](https://pypi.org/project/potik/) [![Python](https://img.shields.io/pypi/pyversions/potik)](https://pypi.org/project/potik/) [![License](https://img.shields.io/pypi/l/potik)](https://github.com/Jarv1s10/potik/blob/main/LICENSE)
+
+potik is an async Python framework for Kafka services that read records, process them, and write new ones. A handler returns its output records, and potik commits them in one Kafka transaction with the input's offset. Consumers downstream see each output exactly once, even after a crash or a rebalance.
+
+> [!WARNING]
+> potik is alpha. Its API can change between minor versions until 1.0.
+
+## Example
+
+```python
+from typing import Annotated
+
+import anyio
+from pydantic import BaseModel
+
+import potik
+from potik import Config, Key, ProducerRecord, Router, Topic
+from potik.serde import PydanticJson
+
+
+class Order(BaseModel):
+    sku: str
+    amount: float
+
+
+class Accepted(BaseModel):
+    sku: str
+    total: float
+
+
+json = PydanticJson()
+orders = Topic("orders", Order, serde=json)
+accepted = Topic("orders.accepted", Accepted, serde=json)
+router = Router()
+
+
+@router.handler(orders)
+async def accept(order: Order, customer: Annotated[str, Key()]) -> ProducerRecord:
+    return accepted(Accepted(sku=order.sku, total=order.amount * 1.2), key=customer)
+
+
+runtime = potik.build_runtime(Config(bootstrap_servers="localhost:9092", group_id="acceptor"), [router])
+anyio.run(runtime.run)
+```
+
+## Features
+
+- One transactional producer per app commits outputs and offsets for all partitions together (KIP-447).
+- Partitions run concurrently, and records within a partition run in order, or with key concurrency, in order per key. A handler can run for minutes without dropping the app from its consumer group.
+- A `Topic` declares its value and key types, and type checkers check every record a handler returns.
+- A failing handler stops only its own partition. Middleware adds retries and dead letter topics.
+- The app shuts down on SIGTERM after it commits finished work. Its liveness and readiness checks are ready to serve as Kubernetes probes from any HTTP framework.
+- OpenTelemetry tracing follows each record through its handler, and its outputs to the transaction that commits them.
+
+## Install
+
+potik needs Python 3.12+ and Kafka 4.0+.
+
+```sh
+uv add "potik[pydantic]"
+```
+
+## Documentation
+
+- [Quickstart](https://jarv1s10.github.io/potik/quickstart/)
+- [Runtime](https://jarv1s10.github.io/potik/runtime/): delivery, failures, configuration, and production
+- [Middleware](https://jarv1s10.github.io/potik/middleware/): retries, dead letters, concurrency limits, tracing, and metrics
+- [Typed API](https://jarv1s10.github.io/potik/typed/): topics, serdes, handlers, and testing
+- [Producer](https://jarv1s10.github.io/potik/producer/) and [request-reply](https://jarv1s10.github.io/potik/request-reply/)
+
+To contribute, see [CONTRIBUTING.md](https://github.com/Jarv1s10/potik/blob/main/CONTRIBUTING.md).

potik-0.1.0/examples/rpc/README.md

@@ -0,0 +1,44 @@
+# Request-reply across replicas
+
+An API sends each CRM update to Kafka and answers its HTTP request with the updater's reply:
+
+```
+api (Starlette, N replicas)  POST /records/{id} -> crm.updates, then awaits crm.updates.status
+updater (potik)               crm.updates -> crm.updates.status, copying the correlation-id header
+```
+
+Each API replica opens a `ReplyListener` in its lifespan. It reads every partition of `crm.updates.status`, without a consumer group, and hands each reply to the request in this replica that awaits its correlation ID. The API enters `expect()` before it sends a request, so that a fast reply cannot arrive first. A shared consumer group would hand each partition to one replica, so most replies would reach a replica that does not await them.
+
+```sh
+uv sync --extra pydantic
+podman compose -f examples/tracing/compose.yml up -d --wait kafka   # KAFKA_PORT=19092 if port 9092 is taken
+
+# KAFKA_BOOTSTRAP=localhost:19092 for a moved broker
+uv run python examples/rpc/updater.py &
+for port in 8000 8001 8002; do uv run uvicorn api:app --app-dir examples/rpc --port $port & done
+
+for port in 8000 8001 8002 8000 8001 8002; do
+  curl -s -X POST localhost:$port/records/opp-$RANDOM -H 'content-type: application/json' -d '{"Stage": "Won"}'; echo
+done
+kill %1 %2 %3 %4
+podman compose -f examples/tracing/compose.yml down
+```
+
+Each request gets its own status: `200` with `{"ok": true}`, or `422` with `{"ok": false}` for the one update in five that the updater rejects.
+
+## Other ways to correlate
+
+potik leaves the correlation ID's place to the app. Here the API sends it in a `correlation-id` header, and the updater copies it to its reply. It can also travel in the records' values, or in an HTTP call that makes a service reply to Kafka. `correlate` then reads it from wherever the reply carries it:
+
+```python
+def job_id(record: ConsumerRecord) -> str | None:
+    return json.loads(record.value() or b"{}").get("job_id")
+
+
+listener = ReplyListener("jobs.status", bootstrap_servers=BOOTSTRAP, correlate=job_id)
+
+with listener.expect() as pending:
+    await scheduler.schedule(job_id=pending.correlation_id, fields=fields)
+    with anyio.fail_after(30):
+        status = await pending.wait()
+```

potik-0.1.0/examples/rpc/api.py

@@ -0,0 +1,65 @@
+"""The requester: a Starlette app that sends each update to Kafka and answers with the updater's reply.
+
+Run as many replicas as you like. Each one reads every reply, and keeps only the replies to its own requests.
+
+Usage: uv run uvicorn api:app --app-dir examples/rpc --port 8000
+"""
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+import anyio
+from common import BOOTSTRAP, CORRELATION_ID, Update, setup, statuses, updates
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse, PlainTextResponse
+from starlette.routing import Route
+
+from potik import ConsumerRecord, Producer, ReplyListener
+
+TIMEOUT = 10.0
+
+
+def correlation_id(reply: ConsumerRecord) -> str | None:
+    """Return the reply's last `correlation-id` header, which the updater copied from the request."""
+    found = dict(reply.headers() or ()).get(CORRELATION_ID)
+    return found.decode() if isinstance(found, bytes) else found
+
+
+@asynccontextmanager
+async def lifespan(api: Starlette) -> AsyncGenerator[dict[str, Producer | ReplyListener]]:
+    setup("api")
+    # The listener opens before the app takes requests, so it reads the reply to each of them.
+    async with (
+        Producer(BOOTSTRAP) as producer,
+        ReplyListener(statuses.name, bootstrap_servers=BOOTSTRAP, correlate=correlation_id) as listener,
+    ):
+        yield {"producer": producer, "listener": listener}
+
+
+async def update(request: Request) -> JSONResponse:
+    record_id = request.path_params["record_id"]
+    update = Update(record_id=record_id, fields=await request.json())
+    listener: ReplyListener = request.state.listener
+    # Await the reply before sending, so that a fast reply cannot arrive first.
+    with listener.expect() as pending:
+        record = updates(update, key=record_id, headers={CORRELATION_ID: pending.correlation_id})
+        try:
+            with anyio.fail_after(TIMEOUT):
+                await request.state.producer.send(record)
+                reply = await pending.wait()
+        except TimeoutError:
+            return JSONResponse({"error": "no reply yet, and the update may still apply"}, 504)
+    status = await statuses.decode(reply.value() or b"")
+    return JSONResponse(status.model_dump(), 200 if status.ok else 422)
+
+
+async def livez(request: Request) -> PlainTextResponse:
+    """Fail once the producer or the listener stops, so that Kubernetes restarts the replica."""
+    failure = request.state.producer.failure or request.state.listener.failure
+    return PlainTextResponse("ok\n") if failure is None else PlainTextResponse(f"{failure}\n", 503)
+
+
+app = Starlette(
+    routes=[Route("/records/{record_id}", update, methods=["POST"]), Route("/livez", livez)], lifespan=lifespan
+)

potik-0.1.0/examples/rpc/common.py

@@ -0,0 +1,48 @@
+"""The contracts that the API and the updater share: the request and reply topics, and their values."""
+
+import logging
+import os
+
+from confluent_kafka import KafkaError, KafkaException
+from confluent_kafka.admin import AdminClient, NewTopic
+from pydantic import BaseModel
+
+from potik import Topic
+from potik.serde import PydanticJson
+
+BOOTSTRAP = os.environ.get("KAFKA_BOOTSTRAP", "localhost:9092")
+
+
+class Update(BaseModel):
+    record_id: str
+    fields: dict[str, str | int | float | bool | None]
+
+
+class Status(BaseModel):
+    record_id: str
+    ok: bool
+    error: str | None = None
+
+
+# The header that carries a request's ID, which the updater copies to its reply. potik leaves the convention to the app.
+CORRELATION_ID = "correlation-id"
+# Both topics are keyed by the record's ID, so each record's updates run in order.
+JSON = PydanticJson()
+updates = Topic("crm.updates", Update, serde=JSON)
+statuses = Topic("crm.updates.status", Status, serde=JSON)
+# Partitions per topic.
+TOPICS = {updates.name: 3, statuses.name: 3}
+
+
+def setup(service: str) -> None:
+    """Configure logging and create missing topics."""
+    logging.basicConfig(level=logging.INFO, format=f"%(asctime)s {service}[{os.getpid()}] %(levelname)s %(message)s")
+    admin = AdminClient({"bootstrap.servers": BOOTSTRAP})
+    existing = admin.list_topics(timeout=10).topics
+    missing = [NewTopic(name, partitions) for name, partitions in TOPICS.items() if name not in existing]
+    for future in admin.create_topics(missing).values() if missing else ():
+        try:
+            future.result()
+        except KafkaException as exc:
+            if exc.args[0].code() != KafkaError.TOPIC_ALREADY_EXISTS:  # Another service created it meanwhile.
+                raise

potik-0.1.0/examples/rpc/updater.py

@@ -0,0 +1,36 @@
+"""The responder: a plain potik service that applies each update and replies with its status.
+
+Each reply copies its request's `correlation-id` header, and commits in one transaction with the request's offset. One update in five fails, to show an error reply.
+"""
+
+import random
+from typing import Annotated
+
+import anyio
+from common import BOOTSTRAP, CORRELATION_ID, Status, Update, setup, statuses, updates
+
+import potik
+from potik import Config, Header, Key, ProducerRecord, Router, resume_or_earliest
+
+router = Router()
+
+
+@router.handler(updates, output_topics=[statuses])
+async def apply(
+    update: Update, record_id: Annotated[str, Key()], correlation_id: Annotated[str | None, Header(CORRELATION_ID)]
+) -> ProducerRecord[Status]:
+    await anyio.sleep(random.uniform(0.05, 0.5))  # the CRM's API call
+    error = "the CRM rejected the update" if random.random() < 0.2 else None
+    status = Status(record_id=update.record_id, ok=error is None, error=error)
+    # A request without a correlation ID, e.g. a fire-and-forget one, still gets a status that nobody awaits.
+    return statuses(status, key=record_id, headers={CORRELATION_ID: correlation_id})
+
+
+async def main() -> None:
+    # A request sent before the updater first joins its group still gets its reply.
+    config = Config(bootstrap_servers=BOOTSTRAP, group_id="updater", offset_policy=resume_or_earliest)
+    await potik.build_runtime(config, [router]).run()
+
+
+setup("updater")
+anyio.run(main)

potik-0.1.0/examples/tracing/README.md

@@ -0,0 +1,61 @@
+# Tracing across apps
+
+Three services handle each order, and Jaeger shows its trace end to end:
+
+```
+checkout (potik Producer)    -> orders
+fulfillment (potik)           orders -> orders.confirmed | orders.dlq
+notifier (potik)              orders.confirmed -> notifications, orders.dlq -> (helpdesk ticket)
+```
+
+`TracingMiddleware` gives each order a tree like this, across services:
+
+```
+POST /checkout                        checkout
+└─ send orders                        checkout
+   └─ process orders                  fulfillment   one per handler call, retries included
+      ├─ UPDATE stock, POST /charges  fulfillment   the handler's own spans
+      └─ create orders.confirmed      fulfillment   one per output, propagated in its headers
+         └─ process orders.confirmed  notifier
+            └─ create notifications   notifier
+```
+
+Each transaction gets a trace of its own, rooted at its `send` span. The `send` span links to the `create` span of each output in the transaction, and Jaeger lists these links under the span's "References".
+
+- `fulfillment` retries random payment timeouts. The handler's spans from every attempt are children of one `process orders` span. That span has an `exception` event for each failed attempt.
+- `fulfillment` dead-letters every 7th order. Its `process orders` span succeeds and records the `OutOfStockError` as an `exception` event. Its trace continues in `notifier`'s `process orders.dlq`.
+- All three services add `messaging.kafka.message.key` to the tracing middleware's `attributes`, so spans carry each order's customer id.
+- The 10th order crashes `fulfillment`'s run once. The restarted run replays the orders that it handled but had not committed, so their traces show a second `process orders` span next to the first one. Only the second one's outputs commit, so only its `create` span has a link from a transaction and a `process` span in `notifier`.
+
+```sh
+uv sync --extra otel --extra pydantic
+podman compose -f examples/tracing/compose.yml up -d --wait   # KAFKA_PORT=19092 if port 9092 is taken
+
+# KAFKA_BOOTSTRAP=localhost:19092 for a moved broker
+uv run python examples/tracing/fulfillment.py &
+uv run python examples/tracing/notifier.py &
+uv run python examples/tracing/checkout.py 21 0.3   # prints each order's trace id
+
+open http://localhost:16686   # service "checkout", or /trace/<trace id>
+# OTEL_TRACES_EXPORTER=none to run the services without exporting spans
+kill %1 %2
+podman compose -f examples/tracing/compose.yml down
+```
+
+## Health probes
+
+`fulfillment` and `notifier` serve `/livez` and `/readyz` with uvicorn, on ports 8081 and 8082, or `HEALTH_PORT`. Each runs the server as a task next to its runtime, as [Health checks](../../docs/runtime/production.md#health-checks) shows:
+
+```sh
+curl localhost:8081/readyz   # ok
+```
+
+## Logs and baggage
+
+A handler logs within its `process` span's context. The committer logs within its transaction's span, e.g. when it repeats a transaction for a stale group epoch. An OpenTelemetry logging handler, such as the SDK's `LoggingHandler`, adds the trace and span ids to these log records, so the backend shows them with the trace.
+
+Baggage set upstream, such as a tenant id, arrives with the trace context. The handler sees it, and the headers of every output propagate it. To add it to the `process` and `create` spans as attributes, add `BaggageSpanProcessor` from `opentelemetry-processor-baggage` to the tracer provider. A transaction starts its own trace and holds the outputs of many records, so its spans have no baggage.
+
+## Metrics
+
+`potik.middleware.metrics.MetricsMiddleware` records `messaging.client.consumed.messages` and `messaging.process.duration` per topic and partition. It records `messaging.client.operation.duration` and `messaging.client.sent.messages` per transaction. Jaeger stores no metrics, so this example leaves it out. To use it, put it first in the middleware list next to `TracingMiddleware`, and give it a `MeterProvider` that exports to your backend.

potik-0.1.0/examples/tracing/checkout.py

@@ -0,0 +1,49 @@
+"""A checkout API that sends one order per request through a potik Producer, starting each order's trace.
+
+Usage: checkout.py [ORDERS=20] [INTERVAL_S=0.5]
+
+Every 7th order is for an out-of-stock item, and fulfillment dead-letters it. The 10th is for a new item, which crashes fulfillment's run once.
+"""
+
+import random
+import sys
+from uuid import uuid4
+
+import anyio
+from common import BOOTSTRAP, KEYED, Order, orders, setup
+from opentelemetry import trace
+from opentelemetry.trace import SpanKind
+
+from potik import Producer
+from potik.middleware.tracing import TracingMiddleware
+
+setup("checkout")
+tracer = trace.get_tracer("checkout")
+count = int(sys.argv[1]) if len(sys.argv) > 1 else 20
+interval = float(sys.argv[2]) if len(sys.argv) > 2 else 0.5
+
+
+async def main() -> None:
+    # The same middleware as the potik services, so each send gets a span and carries its context.
+    async with Producer(BOOTSTRAP, middleware=[TracingMiddleware(optional_attributes=KEYED)]) as producer:
+        for n in range(1, count + 1):
+            order = Order(
+                id=str(uuid4()),
+                customer=f"customer-{random.randint(1, 5)}",
+                sku="SKU-SOLD-OUT" if n % 7 == 0 else "SKU-NEW" if n == 10 else f"SKU-{random.randint(100, 999)}",
+                amount=round(random.uniform(5, 250), 2),
+            )
+            with tracer.start_as_current_span(
+                "POST /checkout",
+                kind=SpanKind.SERVER,
+                attributes={"http.request.method": "POST", "http.route": "/checkout"},
+            ) as request:
+                request.set_attribute("order.id", order.id)
+                with tracer.start_as_current_span("validate cart"):
+                    await anyio.sleep(random.uniform(0.005, 0.02))
+                await producer.send(orders(order, key=order.customer))
+            print(f"order {n}/{count}: {order.id} {order.sku} trace {request.get_span_context().trace_id:032x}")
+            await anyio.sleep(interval)
+
+
+anyio.run(main)

potik-0.1.0/examples/tracing/common.py

@@ -0,0 +1,99 @@
+"""Shared setup of the tracing example: topics, their values, and the OpenTelemetry SDK."""
+
+import logging
+import os
+import socket
+from collections.abc import Callable
+
+import uvicorn
+from confluent_kafka import KafkaError, KafkaException
+from confluent_kafka.admin import AdminClient, NewTopic
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from pydantic import BaseModel
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+from starlette.routing import Route
+
+from potik import Runtime, Topic
+from potik.middleware.tracing import TracingMiddleware
+from potik.serde import PydanticJson
+
+BOOTSTRAP = os.environ.get("KAFKA_BOOTSTRAP", "localhost:9092")
+# Each service's health probes listen on HEALTH_PORT, or on a port of its own.
+HEALTH_PORT = os.environ.get("HEALTH_PORT")
+# The tracing middleware's attributes, plus each record's key, the order's customer id.
+KEYED = TracingMiddleware.DEFAULT_OPTIONAL_ATTRIBUTES | {"messaging.kafka.message.key"}
+
+
+class Order(BaseModel):
+    id: str
+    customer: str
+    sku: str
+    amount: float
+    status: str = "placed"
+
+
+class Notification(BaseModel):
+    channel: str
+    order: str
+
+
+# The contracts that the services share, which pin the values' format. Every record is keyed by its customer.
+JSON = PydanticJson()
+orders = Topic("orders", Order, serde=JSON)
+confirmed = Topic("orders.confirmed", Order, serde=JSON)
+dead_letters = Topic("orders.dlq", Order, serde=JSON)
+notifications = Topic("notifications", Notification, serde=JSON)
+# Partitions per topic.
+TOPICS = {orders.name: 3, confirmed.name: 3, dead_letters.name: 1, notifications.name: 3}
+
+
+def setup(service: str) -> None:
+    """Configure logging, create missing topics, and export spans.
+
+    Spans go over OTLP (`OTEL_EXPORTER_OTLP_*`), or nowhere if `OTEL_TRACES_EXPORTER=none`.
+    """
+    logging.basicConfig(level=logging.INFO, format=f"%(asctime)s {service}[{os.getpid()}] %(levelname)s %(message)s")
+    admin = AdminClient({"bootstrap.servers": BOOTSTRAP})
+    existing = admin.list_topics(timeout=10).topics
+    missing = [NewTopic(name, partitions) for name, partitions in TOPICS.items() if name not in existing]
+    for future in admin.create_topics(missing).values() if missing else ():
+        try:
+            future.result()
+        except KafkaException as exc:
+            if exc.args[0].code() != KafkaError.TOPIC_ALREADY_EXISTS:  # Another service created it meanwhile.
+                raise
+    resource = Resource.create(
+        {"service.name": service, "service.instance.id": f"{socket.gethostname()}-{os.getpid()}"}
+    )
+    provider = TracerProvider(resource=resource)
+    if os.environ.get("OTEL_TRACES_EXPORTER") != "none":
+        provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+    trace.set_tracer_provider(provider)
+
+
+def probe_server(current: Callable[[], Runtime], port: int) -> uvicorn.Server:
+    """Return a server of the current runtime's `/livez` and `/readyz`, on `HEALTH_PORT` or `port`.
+
+    Run it as a task next to the runtime, so that the runtime handles SIGTERM.
+    """
+
+    async def livez(request: Request) -> PlainTextResponse:
+        return probe(current().liveness())
+
+    async def readyz(request: Request) -> PlainTextResponse:
+        return probe(current().readiness())
+
+    app = Starlette(routes=[Route("/livez", livez), Route("/readyz", readyz)])
+    config = uvicorn.Config(app, host="0.0.0.0", port=int(HEALTH_PORT or port), log_level="warning", lifespan="off")
+    return uvicorn.Server(config)
+
+
+def probe(reason: str | None) -> PlainTextResponse:
+    """Answer a probe with 200, or with 503 and the reason it fails."""
+    return PlainTextResponse("ok\n") if reason is None else PlainTextResponse(f"{reason}\n", 503)