Kolo: a Python debugger that writes traces as plain text files

The debugging gap Kolo is aimed at

A Python traceback tells you where an exception surfaced. It does not tell you which functions ran before it, what they returned, or what the local variables held at each step. Getting that picture normally means either adding print statements and removing them again, or attaching an interactive debugger and stepping through by hand. Both approaches produce nothing you can hand to someone else, and nothing a program can read back.

Kolo's stated purpose is to capture every executed function call, return value, local variable and HTTP request, and to write that record as greppable trace files. The README frames the audience twice: once as ordinary Python developers tracing a Django request, and once, in the v3 note, as "humans and agents alike". That second framing is the interesting one. A trace file that an AI agent can search is a different artifact from a debugger UI a person clicks through.

So the problem is not "I need a breakpoint". It is "I need a durable, text-searchable record of what my code actually did during one request or one run".

What a Kolo trace actually contains

The README lists the captured items explicitly: executed function calls, return values, local variables, HTTP requests, and "more". The screenshot captions fill in the shape of the viewer. There is a trace view, a way to explore a trace, a view of an individual SQL query, and a view of an individual function call.

The v3 changelog note describes the storage change in one line: trace data as plain text files. Earlier versions presented a web UI over captured data; v3 keeps the UI at localhost:8000/_kolo/ but describes the underlying representation as text. That matters because it changes what you can do with a trace. Text files can be piped into grep, committed next to a failing test, or read by a tool that has no browser.

What the README does not describe is the file layout, the on-disk naming scheme, or the serialization format. If you need to parse traces programmatically rather than read them, that is the first thing to check in the docs, because the README alone will not tell you.

Django middleware setup, as documented

The README gives one worked path, and it is short. Install with pip install kolo. Then add "kolo.middleware.KoloMiddleware" to the top of your MIDDLEWARE list in settings.py. Start the server with python manage.py runserver, make a request to any page, and browse to localhost:8000/_kolo/ to view the traced request.

Position in the middleware list is not incidental. "Top of your MIDDLEWARE list" means Kolo wraps the request before the rest of the stack sees it, which is what lets it observe the full call tree rather than a fragment. If you place it lower, expect a narrower trace.

The README also mentions a playground at play.kolo.app for people who cannot run it on their own codebase yet, and links a longer tutorial at docs.kolo.app/en/latest/howto/trace-django-requests.html. Everything outside the Django path (plain Python scripts, other frameworks, the topics list mentions Django and web) is not demonstrated in the material available here.

Where the plain-text approach costs you

Writing traces to files trades interactivity for durability, and the trade is real. An interactive debugger lets you stop mid-execution, inspect state, mutate a variable and continue. A trace is written after the fact. You cannot change what happened, only read it. If your bug depends on state you need to poke at live, Kolo is the wrong instrument.

There is also a volume question the README does not address. Capturing every executed function call and every local variable in a request that fans out across an ORM, a template renderer and a few library calls produces a lot of text. Nothing in the supplied material describes sampling, filtering, size caps or retention. That is a gap worth probing before you enable it on a busy service, because the failure mode of a naive full capture is disk and I/O pressure rather than a wrong answer.

Finally, the repository metadata supplied here lists the primary language as unknown, the licence as unknown, and no recent releases. The README's v3 tip links to a changelog, so a release line exists in the project's own docs, but I cannot confirm version numbers or licence terms from what is available. Treat both as things to verify rather than assume.

How Kolo differs from pdb and from OpenTelemetry

The obvious alternative is pdb, the interactive debugger in the standard library. The difference is not quality, it is the artifact. pdb produces a session you drive in a terminal and nothing that outlives it. Kolo produces a file. If your question is "what did this one request do", and you want the answer to survive the terminal closing, pdb cannot answer it and Kolo is designed to.

The more interesting comparison is OpenTelemetry's Python instrumentation. Both record executed operations, and both are aimed at understanding a running system rather than a stopped one. The divergence is in the unit of capture. OpenTelemetry is built around spans: named, timed, attributed intervals that aggregate into traces designed for a backend. Kolo, as described in the README, captures function calls, return values and local variables, which is application-level detail rather than timing and topology.

That distinction decides the choice. If you want latency percentiles, cross-service correlation and a dashboard, spans are the right primitive and Kolo's local-variable capture is the wrong one. If you want to know what a specific function returned and what the locals were when it ran, spans will not give you that and Kolo will. They are not substitutes, and running both is a legitimate configuration.

Maintenance, releases and licence

The repository was last pushed on 2026-04-17 and is not archived, so it is active. No recent releases were retrieved in the metadata supplied, which means I cannot tell you the current version, the release cadence, or whether v3 is a stable line or a preview. The README's tip block announces v3 as already here and links a changelog, which suggests a released line, but that is inference from a link, not a confirmed fact.

The licence is listed as unknown in the supplied metadata. That is the single most important thing to resolve before adopting it, because it determines whether you can ship it inside a product, whether you must publish modifications, and whether an internal-only deployment is affected. I am not in a position to give legal advice on this, and the material here does not name a licence, so read the LICENSE file in the repository yourself.

Upgrade cost is the other unknown. A major version that changes the trace representation from whatever v2 used to plain text files is a breaking change by definition for anyone who scripted against the old format. If you already have tooling that reads traces, pin the version and read the changelog before moving.

Editorial conclusion

Adopt Kolo if you want an agent or a grep to read your Python execution history as files, and if your stack is Django, where the README's middleware path is a one-line change. Do not adopt it if you need a mature, versioned release line with a documented licence, or if you expect conventional interactive breakpoint debugging. Before wiring it into anything that matters, run pip install kolo, add kolo.middleware.KoloMiddleware to MIDDLEWARE, hit a page, and open localhost:8000/_kolo/ to see the trace shape for yourself. Then confirm the licence terms and the v3 changelog, because the repository metadata supplied here states neither.

Official sources

1. Issues
2. koloai/kolo on GitHub
3. Project website
4. README