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/"]