csrd.logging
Context-enriched logging for all application layers.
Dependency tier
Tier 1 csrd.models · csrd.lifespan · csrd.context
Tier 2 csrd.logging · csrd.auth · csrd.delegate · csrd.repository · csrd.service
Tier 3 csrd.versioning
csrd.logging depends only on csrd.context — it sits at the low end of Tier 2.
Components
ContextLogger
A stdlib Logger wrapper that auto-enriches every message with request context (hit_id, user_id, path params) as key=value pairs.
from csrd.logging import ContextLogger
logger = ContextLogger(logging.getLogger(__name__))
logger.info("Order created", meta={"order_id": 42})
# → "Order created hit_id=abc-123 user_id=user1 order_id=42"
All standard logging kwargs (exc_info, extra, stacklevel) pass through. The meta kwarg adds extra key=value pairs per call.
LoggingMixin
A mixin providing self.log (a ContextLogger) for any class. Works at every layer.
from csrd.logging import LoggingMixin
class OrderService(BaseService, LoggingMixin):
async def place_order(self, cart):
self.log.info("Placing order", meta={"items": len(cart)})
Auto-logging (opt-in)
Pass auto_log=True to automatically log entry and exceptions for every public method:
class OrderService(BaseService, LoggingMixin, auto_log=True):
async def place_order(self, cart): # ← entry logged at INFO, exceptions at ERROR
...
Exclude noisy methods:
class MyService(BaseService, LoggingMixin, auto_log=True):
__log_exclude__ = {"health_check"}
Both sync and async methods are handled. Private methods (_name) are always skipped.
RequestContextFilter
A stdlib logging.Filter that injects context fields into log records (not messages). Use this when your logging backend (Splunk, ELK, Datadog) needs structured fields in a configurable format.
Fields added to each record:
| Field | Source | Default |
|---|---|---|
hit_id |
Request trace ID | "-" |
user_id |
Authenticated user's sub claim |
"-" |
app_id |
Application identifier header | "-" |
api_version |
Resolved API version | "-" |
Production logging configuration
ContextLogger enriches log messages — it works out of the box with zero configuration. For production deployments you'll typically also want to configure stdlib logging with structured formatters, handlers, and filters.
Approach 1: ContextLogger only (simplest)
No configuration needed. Messages include context automatically:
2025-07-15 10:23:45 INFO Order created hit_id=abc-123 user_id=user1 order_id=42
Good for development and simple deployments.
Approach 2: YAML logging configuration (production)
Create a config/logging.yml in your application:
version: 1
disable_existing_loggers: false
formatters:
structured:
style: "{"
format: "{asctime} hitId={hit_id} userId={user_id} module={name} func={funcName} level={levelname} {message}"
filters:
context:
"()": csrd.logging.RequestContextFilter
handlers:
console:
class: logging.StreamHandler
level: INFO
formatter: structured
stream: ext://sys.stdout
filters: [context]
loggers:
uvicorn:
handlers: [console]
level: INFO
propagate: false
uvicorn.access:
handlers: [console]
level: INFO
propagate: false
root:
level: INFO
handlers: [console]
Load it at startup:
import logging.config
import yaml
from pathlib import Path
with open(Path("config/logging.yml")) as f:
logging.config.dictConfig(yaml.safe_load(f))
Approach 3: Both together (recommended for production)
Use ContextLogger / LoggingMixin in your code for dev-friendly messages, and attach RequestContextFilter to your production handlers for structured logging backends. The two are complementary — ContextLogger enriches the message text, RequestContextFilter adds record-level fields for formatters.
When to use which
| Approach | Context in logs | Config required | Best for |
|---|---|---|---|
ContextLogger |
In message text (key=value) |
None | Dev, simple apps |
logging.yml + RequestContextFilter |
In log record fields | YAML file | Splunk, ELK, structured logging |
| Both together | Both | YAML file | Full production setup |
Installation
uv add csrd-logging
1 maintainer
Metadata
1 maintainer
Release files for csrd-logging 0.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| csrd_logging-0.8.0.tar.gz | 9.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| csrd_logging-0.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 16.5 kB
Release files / csrd_logging-0.8.0.tar.gz
| Download URL | csrd_logging-0.8.0.tar.gz |
|---|---|
| Size | 9.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
532d29dd4421b46649b2381168faa68d8120c7401f824ae929c8be501af63093
|
|
BLAKE2b-256 checksum How to use checksums |
e435618953ef957acb04e633f2feba7f1fed956972e5bba070d9cab47659962a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency logRelease files / csrd_logging-0.8.0-py3-none-any.whl
| Download URL | csrd_logging-0.8.0-py3-none-any.whl |
|---|---|
| Size | 7.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b19ec4088a9054cfe48f34267f68702aae919b3d2b6bcb98d9b08db8006edb87
|
|
BLAKE2b-256 checksum How to use checksums |
5c050d00ae6fb952ebf84f051cae40ecd4b3e45849e2b21276ddcedf5fdd4287
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.
Transparency log
