User Guide: Verbose Logging

routing uses a built-in verbosity system to control how much diagnostic output it prints. You can adjust the level at any time during a session.

Quick Start

from routing.core.verbose import VerboseLevel, verbose

verbose.set_level(VerboseLevel.INFO)   # default level

Import once at the top of your script. The verbose object is a module-level singleton shared by the whole package.

Verbosity Levels

Level	Value	What you see
SILENT	0	No output at all. Use in production or batch jobs.
ERROR	1	Only error messages (routing failures, invalid input).
WARNING	2	Errors plus warnings (constraint violations, unusual inputs).
INFO	3	Default. Important progress messages: voxelization complete, pipes routed, optimization done.
DEBUG	4	Detailed per-pipe messages: pathfinding iterations, optimizer passes.
TRACE	5	Everything: per-node pathfinding progress, per-iteration optimizer cost. Very verbose — only for diagnosing hard-to-reproduce issues.

from routing.core.verbose import VerboseLevel, verbose

verbose.set_level(VerboseLevel.SILENT)   # suppress all output
verbose.set_level(VerboseLevel.WARNING)  # warnings and errors only
verbose.set_level(VerboseLevel.INFO)     # default
verbose.set_level(VerboseLevel.DEBUG)    # detailed progress
verbose.set_level(VerboseLevel.TRACE)    # everything

Saving Logs to a File

You can direct all output to a file in addition to the console:

verbose.enable_file_logging("routing_session.log")

This creates a routing_session.log file with timestamps and log levels:

2026-01-15 14:23:01,234 [INFO] CadMap voxelization complete (21 mm, 45×57×26 grid)
2026-01-15 14:23:03,891 [INFO] Route PipeA: found path (length=1.82 m, 47 nodes)
2026-01-15 14:23:05,102 [INFO] Optimization complete (3 iterations, final cost=12345)

Call it before starting any routing operations. File logging is in addition to console output — both are active at the same time.

Typical Workflow

For development and debugging:

verbose.set_level(VerboseLevel.DEBUG)
verbose.enable_file_logging("debug.log")

# ... run routing ...

For production / CI runs:

verbose.set_level(VerboseLevel.WARNING)

# ... run routing — only errors and warnings appear ...

For interactive exploration (default):

verbose.set_level(VerboseLevel.INFO)   # default — no need to set explicitly