Full Program Profiling in One Line

Profiling is usually painful. You instrument your code, add timing calls, fight with configuration files, and pray the overhead doesn’t skew your measurements. What if it didn’t have to be?

The Koru Way

~[profile]import "$std/profiler"

That’s it. One line. Your entire program is now profiled with nanosecond precision.

Every event transition is traced. Every continuation path is measured. Zero boilerplate. Zero configuration. Conditional on the [profile] flag, so production builds stay fast.

And the beautiful part: There is nothing special about this implementation. It is all user space code, you could have made this yourself. Let’s look at how:

Conditional Imports

Koru supports conditional imports. Consider this code:

~[profile]import "$std/profiler"

Unsurprisingly, the [profile] part is mapped to a compiler flag; --profile, and if it isn’t set, the import is removed entirely.

This means that if you don’t want profiling in your production builds, you can simply remove the [profile] flag and the profiler will be completely removed from your codebase.

Koru lifecycle events

Koru defines a limited set of lifecycle events. Consider this code:

~import "$std/io"

~koru:start -> * | Transition |> std.io:println("Application started")
~koru:end -> * | Transition |> std.io:println("Application ended")

~std.io:println("Hello world!")

I am not going to insult your intelligence by explaining what this does.

Event Tap Installation

When you import a module in Koru, its event taps are automatically installed. This means that there is no setup required to use the profiler - the import is the setup. When the imports are added to the AST, they are emitted as part of the tap registry and installed on emission if the patterns match event transitions.

This architectural choice is what makes ~[profile]import "$std/profiler" possible: importing doesn’t just give you functions to call, it can modify the runtime environment itself.

To understand how this works, let’s look at the profiler module:

// Koru profiler module

// Chrome Trace doesn't support JSONL, so we need to write the header and footer manually
~koru:start -> * | Transition |> write_header()
~koru:end -> * | Transition |> write_footer()

~* -> * | Profile p |> write_json(
    p.id,
    p.start,
    p.end,
    p.duration,
    p.name,
    p.category,
    p.children
)

// Implementation of JSON writers
...

As you can see, the profiler module is just a regular Koru module with some lifecycle events. When you import this module, its event taps are automatically installed, which means that the profiler will start and stop when the application starts and ends, and for every transition, it will collect profiling data, and write it to a file.

Chrome Tracker

The profiler (Chrome Trace) is a powerful tool for analyzing the performance of your application. It provides a detailed breakdown of the time spent in each function, allowing you to identify bottlenecks and optimize your code. The implementation in Koru is currently just a proof of concept, but it’s a good starting point for a more robust implementation.

Zero Overhead in Production

Because the import is conditional:

// Development build with profiling
koruc build --profile

// Production build - profiler never imported
koruc build --release

No runtime checks. No disabled instrumentation. The profiler code literally doesn’t exist in production builds.

Why This Is Possible

Most languages make profiling hard because instrumentation is bolted on afterward. Koru makes it trivial because:

Taps are first-class - The event system has built-in instrumentation points

Imports have effects - Importing can modify the runtime environment with taps

Conditional compilation - Features can be present or absent at compile time

String interning - Event names are compile-time constants, perfect for zero-alloc profiling

The architecture enables the feature to be simple.

The Philosophy

Good architecture makes hard things easy. When profiling becomes a single line, you use it more. When you use it more, you understand your program better.

This isn’t about clever tricks. It’s about building systems where the right thing is also the easy thing.

One line. Full program profiling. Because the architecture enables it.