Crate custom_labels

Source
Expand description

§Custom labels for profilers.

§Overview

This library provides Rust bindings to v1 of the Custom Labels ABI.

It allows time ranges within a thread’s execution to be annotated with labels (key/value pairs) in such a way that the labels are visible to a CPU profiler that may interrupt the running process at any time. The profiler can then report the labels that were active at any given time in the profiles it produces.

The main interface is with_label, which sets a label to a provided value, executes a function, and then resets the label to its old value (or removes it if there was no old value).

For example, imagine a program that performs database queries on behalf of a user. It might have a function like the following:

fn query_for_user(username: &str, sql: &str) -> DbResultSet {
    custom_labels::with_label("username", username, || do_query(sql))
}

If two users named “Marta” and “Petros” repeatedly query the database, a profiler might produce a CPU profile like the following:

* all (13.4s)
|
+---- username: Marta (4.9s)
|   |
|   +---- query_for_user (4.9s)
|       |
|       + ---- custom_labels::with_label (4.9s)
|            |
|            + ---- do_query (4.9s)
|
+---- username: Petros (8.5s)
    |
    +---- query_for_user (8.5s)
        |
        + ---- custom_labels::with_label (8.5s)
             |
             + ---- do_query (8.5s)

§Profiler Support

The following profilers can make use of the labels set with this library:

If you work on another profiler that also supports this format, send us a PR to update this list!

Modules§

asynchronous
build
Utilities for build scripts
sys
Low-level interface to the underlying C library.

Structs§

Labelset
A set of key-value labels that can be installed as the current label set.

Functions§

with_label
Set the label for the specified key to the specified value while the given function is running.
with_labels
Set the labels for the specified keys to the specified values while the given function is running.