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.

.. contents:: On this page
   :local:
   :depth: 1


Quick Start
-----------

.. code-block:: python

   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
----------------

.. list-table::
   :header-rows: 1
   :widths: 15 10 75

   * - 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.

.. code-block:: python

   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:

.. code-block:: python

   verbose.enable_file_logging("routing_session.log")

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

.. code-block:: text

   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**:

.. code-block:: python

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

   # ... run routing ...

For **production / CI runs**:

.. code-block:: python

   verbose.set_level(VerboseLevel.WARNING)

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

For **interactive exploration** (default):

.. code-block:: python

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