Logging

Text logs on the CLI. JSON when you ask.

The CLI writes human text unless you pass --log-file. Structured JSON is a Python switch: format_json=True. A debug archive is a zip of JSON files you can attach to an issue. The CLI has no --json-logs flag.

CLI: levels and a log file

python -m chunking_strategy --log-level silent|minimal|normal|verbose|debug|trace chunk doc.txt
python -m chunking_strategy --quiet chunk doc.txt
python -m chunking_strategy --verbose chunk doc.txt
python -m chunking_strategy --debug chunk doc.txt
python -m chunking_strategy --log-level debug --log-file chunking.log chunk doc.txt

--debug is DEBUG plus a default file chunking_debug.log, and it turns on performance and metrics collection. --quiet is MINIMAL and no console. Rotating file handler: 10 MB, 3 backups, unless you change that in Python.

JSON lines for a log stack

import chunking_strategy as cs

cs.configure_logging(
    level=cs.LogLevel.VERBOSE,
    file_output=True,
    log_file="chunking_metrics.jsonl",
    format_json=True,
    collect_performance=True,
    collect_metrics=True,
)

cs.user_info("Processing started")
result = cs.create_chunker("sentence_based").chunk(open("doc.txt").read())
cs.user_success(f"{len(result.chunks)} chunks")
cs.performance_log("sentence_chunking", 0.12, n_chunks=len(result.chunks))
cs.metrics_log({"quality_score": result.quality_score})

Each line is one JSON object:

{"timestamp": "2026-09-18T08:00:00", "level": "INFO", "module": "chunking_strategy.user", "message": "Processing started", "filename": "...", "line_number": 12, "function": "..."}

That is what you ship to Elasticsearch, Splunk, or a file you grep. Full LogConfig also has max_file_size (default 10MB) and backup_count (3).

Collect logs for a bug report

python -m chunking_strategy debug enable --log-file my-debug.log
python -m chunking_strategy --debug chunk the-bad-file.pdf
python -m chunking_strategy debug collect -d "PDF extract throws on page 12" -o ./debug-archives/
python -m chunking_strategy debug archive "PDF extract throws on page 12"
python -m chunking_strategy debug test-logging

The zip contains:

import chunking_strategy as cs

cs.enable_debug_mode()
cs.create_chunker("sentence_based").chunk(open("doc.txt").read())
info = cs.create_debug_archive("sentence_based returned empty")
print(info["debug_archive"], info["session_id"])

Return key is debug_archive (path to the zip), not archive_path.

Hardware (not JSON on the CLI)

python -m chunking_strategy hardware
python -m chunking_strategy hardware --detailed --recommendations

There is no hardware --json in the shipped CLI. If you need a machine record in JSON, use the debug zip’s system_info.json or call get_hardware_info() from Python yourself.