Module

logging

Logging configuration and access log formatting.

Configures stdlib logging with pounce-specific formatting. Provides text, JSON, and pretty (TTY) access log output for request/response metrics.

Format modes:

auto   — pretty on TTY, JSON when piped (default)
text   — classic combined-log format via stdlib logging
json   — flat structured JSON written directly to stderr
pretty — colored compact lines on TTY (resolved from auto)
2Classes5Functions

Classes

_JSONFormatter 1 ▼
Structured JSON log formatter for production observability.

Structured JSON log formatter for production observability.

Methods

format 1 str ▼
def format(self, record: logging.LogRecord) -> str
Parameters
Name Type Description
record —
Returns
str
_PrettyFormatter 1 ▼
Compact colored formatter for TTY output — renders through kida templates.

Compact colored formatter for TTY output — renders through kida templates.

Methods

format 1 str ▼
def format(self, record: logging.LogRecord) -> str
Parameters
Name Type Description
record —
Returns
str

Functions

_human_bytes 1 str ▼
Format byte count for human readability.
def _human_bytes(n: int) -> str
Parameters
Name Type Description
n int
Returns
str
_status_color 1 str ▼
Return ANSI color code for an HTTP status code.
def _status_color(status: int) -> str
Parameters
Name Type Description
status int
Returns
str
_duration_str 1 str ▼
Format duration in human-readable form.
def _duration_str(ms: float) -> str
Parameters
Name Type Description
ms float
Returns
str
configure_logging 1 None ▼
Configure stdlib logging for pounce and framework loggers. Resolves the ``"aut…
def configure_logging(config: ServerConfig) -> None

Configure stdlib logging for pounce and framework loggers.

Resolves the"auto"format: pretty on TTY, JSON when piped. Sets up the pounce logger hierarchy and the chirp framework logger with the configured log level and appropriate formatter.

Parameters
Name Type Description
config ServerConfig

Server configuration with log_level and log_format settings.
access_log 9 None ▼
Log an access log entry for a completed request. In JSON mode, writes a flat s…
def access_log(method: str, path: str, status: int, bytes_sent: int, duration_ms: float, client: str, *, http_version: str = '1.1', request_id: str | None = None, worker_id: int | None = None) -> None

Log an access log entry for a completed request.

In JSON mode, writes a flat structured JSON line directly to stderr (bypassing the stdlib logging formatter to avoid double-nesting). In pretty mode, writes a colored compact line to stderr. In text mode, uses the standard combined log format via stdlib logging.

Parameters
Name Type Description
method str

HTTP method (e.g., "GET").
path str

Request path (e.g., "/api/users").
status int

HTTP response status code.
bytes_sent int

Number of response body bytes sent.
duration_ms float

Request duration in milliseconds.
client str

Client address string (e.g., "127.0.0.1:5000").
http_version str

Protocol version string (e.g., "1.1", "2").

Default:'1.1'
request_id str | None

Optional request ID for tracing.

Default:None
worker_id int | None

Optional worker ID for multi-worker correlation.

Default:None