config.toml¶

Most Kolo configuration happens via the .kolo/config.toml file, but there are also a number of environment variables

KOLO_PATH¶

You can customise the location of the .kolo directory using the KOLO_PATH environment variable. The .kolo directory stores Kolo’s private data and the config.toml configuration file.

KOLO_DISABLE¶

Set the KOLO_DISABLE environment variable to 1 to disable the KoloMiddleware. Kolo automatically disables itself if the Django DEBUG setting is set to False (as should be the case in production) or if it detects that another profiler is already active.

config.toml¶

Filters¶

By default Kolo traces all code in your project and ignores standard library or third party code. Filters let you customize this behavior.

Ignore Frames¶

ignore_frames is a list of file path fragments:

# .kolo/config.toml

[filters]

ignore_frames = ["ignore_me.py", "/ignore_directory/"]

This will ignore any file called ignore_me.py or any file with /ignore_directory/ in its path.

Include Frames¶

# .kolo/config.toml

[filters]

include_frames = ["json", "django/db"]

This will include any frames from the json module of the standard library and from Django’s database code in django.db.

Note

Including standard library and third party code can generate a lot of extra data, which may slow down execution. If you notice slow execution, try to make your includes more narrow.

Ignore Request Paths¶

By default Kolo generates a trace for every Django request. Sometimes you may want to exclude some urls. To do this, add entries to ignore_request_paths:

# .kolo/config.toml

[filters]

ignore_request_paths = ["/static/", "favicon.ico"]

lightweight_repr¶

Some Python objects have __repr__ methods that are expensive to call. By default Kolo serializes unknown objects by calling repr, so this can have a significant impact on Kolo’s overhead. If you think this is a problem in your project, you can set the lightweight_repr config option to true.

hide_startup_message¶

When the django development server starts up, Kolo prints out a message to let users know how to acccess the Kolo web app. This message can be disabled by setting the hide_startup_message config option to true.

Trace points¶

New in v3.1.0.

Trace points let you nominate functions whose returns should produce standalone, top-level traces. When a listed function returns, the frames from its call to its return are saved as their own first-class trace with a fresh trace_id — independent of whatever outer trace is in flight.

# .kolo/config.toml

[trace_points]

on_return = ["dispatch", "process_job"]

Useful for splitting long-running processes into smaller chunks, for example when tracing using KOLO=1. Matches are done by function name.

flush_subtree_mb¶

New in v3.1.0.

Controls subtree flushing for large traces. When the in-progress trace grows past this many megabytes, Kolo spills the largest closed subtree to disk as its own child trace, leaving a subtree_flushed placeholder in the parent. This keeps memory bounded on long-running traces.

# .kolo/config.toml

flush_subtree_mb = 100

Default: 500 (500 MB)
Set to false to disable subtree flushing entirely

Flushing is not exact — the actual trace size can overshoot the threshold somewhat before a coarse-enough closed subtree becomes available to flush.

pyproject.toml¶

Instead of using .kolo/config.toml, you can instead put your config in pyproject.toml in a [tool.kolo] section:

# pyproject.toml

[tool.kolo]

lightweight_repr = true

[tool.kolo.filters]

ignore_request_paths = ["/static/", "favicon.ico"]