# logging URL: /pounce/api/logging/ Section: api Description: 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) --- > For a complete page index, fetch /pounce/llms.txt. Open LLM text (/pounce/api/logging/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Flogging%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Flogging%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Flogging%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2Flogging%2Findex.txt) 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) ``` 3Classes7Functions ## Classes `LogEntry` 5 ▼ Structured log entry for JSON output. Bases: `TypedDict` Structured log entry for JSON output. #### Attributes Name Type Description `ts` `str` — `level` `str` — `logger` `str` — `message` `str` — `exception` `str` — `_JSONFormatter` 1 ▼ Structured JSON log formatter for production observability. Bases: `logging.Formatter` 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. Bases: `logging.Formatter` 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 `is_pretty` 0 `bool` ▼ Return True if pretty (TTY) output mode is active. `def is_pretty() -> bool` ##### Returns `bool` `is_json` 0 `bool` ▼ Return True if JSON output mode is active. `def is_json() -> bool` ##### Returns `bool` `_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 (/pounce/api/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. JSON access-log schema (stability contract — see `site/content/docs/deployment/observability.md`). Each line is a flat object with these keys:: ``` ts str ISO-8601 timestamp, UTC, with offset level str "info" (status < 500) or "warn" (status >= 500) method str HTTP request method path str request target (path + query) status int HTTP response status code bytes int response body bytes sent duration_ms float request duration, rounded to 1 decimal client str "host:port" of the peer req_id str optional — present only when a request id exists; the FULL id, byte-for-byte equal to the ``X-Request-ID`` response header (no truncation) worker int optional — present only in multi-worker mode ``` Consumers may depend on this key set, the value types, and the req_id policy. New keys may be added; existing keys are not renamed or retyped without a deprecation. ##### 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. Logged in full (json and text modes) so it matches the X-Request-ID response header exactly. Default:`None` `worker_id` `int | None` Optional worker ID for multi-worker correlation. Default:`None`