Configuring Kolo for Python

The main way to configure the Kolo python library is via the .kolo/config.toml file. This works with KoloMiddleware, kolo run, and kolo.enabled and kolo.enable.

You can also configure the VSCode extension.

Customising the .kolo directory

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.

Filters

Filters are Kolo’s way of targetting which code to analyse.

Ignore Frames

By default Kolo traces all code in your project. If you want Kolo to ignore some of your code, define ignore_frames in the filters section of config.toml.

At its simplest, 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

By default Kolo ignores most of the standard library and third party code. To tell Kolo to opt into tracing some of this code, define include_frames in the filters section of config.toml:

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

Warning

Including standard library and third party code can generate a lot of extra data, which may slow down your program and VSCode. Try to target your includes as narrowly as you can.

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 = ["/my/api/"]

Kolo will ignore any trace where Django’s request.path contains any of the entries in ignore_request_paths. For example, a request to /my/api/users/ would be ignored.

Kolo Middleware

Kolo comes with a Django middleware that is used to automatically trace the request/response cycle.

To enable it, add "kolo.middleware.KoloMiddleware" to the top of your MIDDLEWARE setting.

Kolo automatically disables the middleware if DEBUG is set to False so your code isn’t slowed down by our tracing in production.

It also disables itself if another profiler is already active. This is anything set by sys.setprofile. For example, cProfile or Kolo itself.

Finally, the middleware can be temporarily disabled by setting the KOLO_DISABLE environment variable to True.

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]

use_rust = false

[tool.kolo.filters]

ignore_request_paths = ["/my/api/"]