Logging

Control Chonkie’s log output

By default, Chonkie logs warnings and errors. You can control what gets logged using the CHONKIE_LOG environment variable or configure it programmatically.

Quick Setup

Set the CHONKIE_LOG environment variable before importing chonkie:

export CHONKIE_LOG=debug  # Show everything
export CHONKIE_LOG=info   # Show info, warnings, and errors
export CHONKIE_LOG=warning # Show warnings and errors (default)
export CHONKIE_LOG=error  # Show only errors
export CHONKIE_LOG=off    # Disable all logging

Programmatic Configuration

Configure logging from your Python code:

import chonkie

# Enable debug logging
chonkie.logger.configure("debug")

# Disable logging completely
chonkie.logger.configure("off")

# Back to warnings and errors
chonkie.logger.configure("warning")

Log Levels

• debug - Everything (chunker initialization, text processing, chunk counts)
• info - High-level operations (chunk creation, file operations)
• warning - Potential issues (default)
• error - Only errors
• off - Silent

Custom Format

Change the log format to suit your needs:

Default

import chonkie
chonkie.logger.configure("info")

Output:

2025-11-13 14:18:58,714 | INFO | chonkie.chunker.token:chunk:143 - Created 5 chunks

Simple

import chonkie
chonkie.logger.configure("info", format="%(levelname)s - %(message)s")

Output:

INFO - Created 5 chunks

Minimal

import chonkie
chonkie.logger.configure("info", format="%(message)s")

Output:

Created 5 chunks

Detailed

import chonkie
chonkie.logger.configure("info", format="[%(name)s] %(levelname)s: %(message)s")

Output:

[chonkie.chunker.token] INFO: Created 5 chunks

Structured

import chonkie
import logging

# Custom formatter that includes extra fields
class StructuredFormatter(logging.Formatter):
    def format(self, record):
        msg = super().format(record)
        # Add any extra fields
        extras = []
        for key in ['chunk_count', 'tokens']:
            if hasattr(record, key):
                extras.append(f"{key}={getattr(record, key)}")
        if extras:
            msg += f" [{', '.join(extras)}]"
        return msg

# Apply custom formatter
logger = logging.getLogger("chonkie")
handler = logging.StreamHandler()
handler.setFormatter(StructuredFormatter("%(levelname)s - %(message)s"))
logger.addHandler(handler)
logger.setLevel(logging.INFO)

Output:

INFO - Created chunks [chunk_count=5, tokens=128]

That’s it. Logging is simple and stays out of your way.