Logging¶

Routes CatBoost's training output through Python logging with parsed structured fields.

import logging
from catboost_utils.logging import setup_logging, attach

setup_logging(level=logging.INFO, structured=False)
attach(model)
model.fit(X, y)
# INFO catboost_utils.training - iteration=10 learn_loss=0.423 test_loss=0.451 best_iter=8 total_ms=123 remaining_s=12.3

structured=True emits one JSON object per record. Each parsed line also carries a cbx_iteration extra dict for downstream processors.

attach() monkey-patches model.fit to inject CatBoost's log_cout / log_cerr (which are fit-time params, not constructor params). Skipped with a warning when the model already has verbose / logging_level set, to avoid duplicate output.

catboost_utils.logging.handler.setup_logging ¶

setup_logging(
    level: int = stdlib_logging.INFO,
    *,
    structured: bool = False,
    stream: TextIO | None = None,
) -> stdlib_logging.Logger

Configure the catboost_utils.training logger.

Parameters:

Name	Type	Description	Default
`level`	`int`	standard `logging` level.	`INFO`
`structured`	`bool`	when `True`, every record is rendered as a single JSON object.	`False`
`stream`	`TextIO \| None`	where to send output (defaults to `sys.stderr`).	`None`

Returns:

Type	Description
`Logger`	The configured logger. Idempotent — calling twice replaces the existing handler.

catboost_utils.logging.handler.attach ¶

attach(model: Any) -> None

Attach a logging-backed stream to model for subsequent fit() calls.

log_cout / log_cerr are fit-time parameters in CatBoost (not init params); we monkey-patch the bound fit method to inject them. Idempotent: a second attach() call replaces the previous streams.

Skips (with a warning) when the user already set verbose / logging_level to avoid duplicating output to stdout.

catboost_utils.logging.parser.parse_iteration_line ¶

parse_iteration_line(line: str) -> IterationRecord | None

Try to parse one CatBoost iteration line. Returns None if not a match.