Kronicler

<img width="1136" height="278" alt="2026-01-13_00-24" src="https://github.com/user-attachments/assets/9f406d08-6e79-4554-a2bd-eb0b112cc56d" />

Automatic performance capture and analytics for production applications in Python using a custom columnar database written in Rust.

View Kronicler on UseKronicler.com, PyPi.org, Crates.io and GitHub.

[!IMPORTANT] Kronicler is still early in development. I'd appreciate any feedback to help make kronicler more useful for you!

Benefits of using Kronicler

• Automatic performance capturing
• Lightweight and concurrent*
• One Python dependency
• Works out-of-the-box without configuration

* concurrency is in development but not fully implemented as of version 0.1.3. Track concurrency in issue #123.

Why use Kronicler?

If you want to monitor the performance of a production application, kronicler offers efficient and lightweight logging with a single library. Kronicler lets you view runtime statistics for functions like mean and median as well as statistics for different percentiles.

A use-case for these statistics is to find functions that occasionally operate much slower than they do on average. By looking at the "slowest" speed, the standard error, and the mean, you can find functions that occasionally run much slower than expected. Sometimes it's hard to find and replicate these issues in a test environment, so keeping logs in your production application can improve your ability to find these issues.

What really is Kronicler?

| Name | Description | Link | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Kronicler (Python) | A Python library that provides the @kronicler.capture decorator to save performance logs to a database. | More about Python | | Kronicler (Database) | Custom columnar database designed for log capturing and performance analytics. | More about Database | | Kronicler (Rust) | A Rust library for accessing the columnar database and capture functions for Rust-based log capturing tasks. | More about Rust | | Kronicler (CLI) | Rust-based CLI tool for analyzing performance logs captured with the capture methods. | More about CLI | | Kronicler (Web) | Prototype web portal for remotely viewing performance logs. | More about Web |

Install (Python)

Install with Pip for Python

pip install kronicler

You may need to use a virtual environment.

Usage (Python)

Kronicler provides a Python decorator called capture that will calculate the time it takes to run the function.

import kronicler

@kronicler.capture
def my_function():
	pass

Python docs

Public API exposed from the Python package:

• Database: Rust-backed database handle. Create it with Database(sync_consume=False) (or True for sync capture), then use capture(name, args, start, end), fetch(index), fetch_all(), logs(), average(function_name), get_function_names(), and contains_name(name). Static helpers: exists() and new_reader(sync_consume=False). The init() method starts the consumer loop (blocking).
• database_init(): Convenience helper that spawns a background thread and calls Database.init() for async capture consumption.
• capture: Decorator that times the wrapped function and records it via the global DB instance. Disabled when KRONICLER_ENABLED is set to false or 0.
• decorator_example: Simple example decorator that prints start/end messages.
• KroniclerEndpointMiddleware: Starlette/ASGI middleware that captures timings per request path.
• KroniclerFunctionMiddleware: Starlette/ASGI middleware that captures timings per endpoint function name.
• KroniclerMiddleware: Deprecated alias of KroniclerFunctionMiddleware that emits a deprecation warning.

Architecture

Simplified version of the package and database architecture. The data is passed from the Python decorator called capture to the database's queue. It then consumes that queue to insert each field into its respective column. The column uses the bufferpool to operate on pages.

This does not include details on:

• How the bufferpool manages pages.
• How pages operate.
• capture, index, row, or saving and loading with metadata.

The Database

The columnar database is somewhat inspired by my previous database called RedoxQL. A lot of the structure and architecture is different as well as how data is stored.

The Bufferpool

The bufferpool is based on my bufferpool project. I had to modify it to work with the rest of this database.

Future Languages

Install and Usage for Rust is coming soon...

I plan to implement the Rust version as an attribute to be used like the following:

#[capture]
fn foo() { todo!() }

Examples

Using Kronicler (Basic Example)

Here is the most basic usage of Kronicler. Use it to capture the runtime of functions by adding the @kronicler.capture decorator.

import kronicler

@kronicler.capture
def foo():
    print("Foo")

Using Kronicler with FastAPI

With just two lines of code, you can add Kronicler to your FastAPI server. The KroniclerMiddleware automatically captures performance data for all your routes.

from fastapi import FastAPI
import kronicler

app = FastAPI()
app.add_middleware(kronicler.KroniclerMiddleware)

# Used only for the /logs route
DB = kronicler.Database(sync_consume=True)


@app.get("/")
def read_root():
    return {"status": "success"}


@app.get("/logs")
def read_logs():
    return DB.logs()

That's it! The middleware automatically captures the performance of every route without needing to manually decorate functions.

Optional: Manual Function Capture

If you want to capture functions manually (e.g., helper functions that aren't routes), you can still use @kronicler.capture as normal:

from fa