https://github.com/polarsignals/custom-labels

Experimental C/Rust support for custom profiling labels
https://github.com/polarsignals/custom-labels

Last synced: 3 days ago
JSON representation

Experimental C/Rust support for custom profiling labels

• Host: GitHub
• URL: https://github.com/polarsignals/custom-labels
• Owner: polarsignals
• License: apache-2.0
• Created: 2024-05-02T21:40:59.000Z (6 months ago)
• Default Branch: master
• Last Pushed: 2024-10-15T20:20:41.000Z (28 days ago)
• Last Synced: 2024-10-17T06:53:33.496Z (27 days ago)
• Language: C
• Size: 21.5 KB
• Stars: 2
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
## Warning

This library is experimental; both the API and ABI are subject to change.

## Description

This library maintains a thread-local mapping of keys to values.

Each key and value is an arbitrary byte array.

The core goal of the design is that the map for a thread may be

validly read from that thread whenever user code is stopped; for

example, in a signal handler, a debugger, or an eBPF program. This

should work even if the thread happens to be suspended in the middle

of one of the functions of this library.

The intended purpose is to store custom labels for annotating stack traces

during profiling; for example, client code might set the label `customer_id`

whenever it is processing a request for a particular customer,

and a CPU profiler might then record that value whenever it interrupts the program

to collect a stack trace.

The library exposes a C API (in `customlabels.h`), a Rust API

[documented here](https://docs.rs/custom_labels/0.1.0/custom_labels/), and an ABI for reading

by external code (e.g., profilers or debuggers).

## Supported Configurations

**Language**: any language that can link against C code.

**Platform**: Linux on x86-64 or aarch64 (64-bit ARM).

## Using from Rust

Simply depend on the [`custom-labels`](https://crates.io/crates/custom-labels) crate.

## Using from C or C++ (shared library)

For a release build:

``` bash

CFLAGS="-O2" make

```

For a debug build:

``` bash

CFLAGS="-O0 -g" make

```

Either will produce a library called `libcustomlabels.so` in the repository root,

which should be linked against during your build process.

## Using from C or C++ (main executable)

Ensure that `customlabels.c` is linked into your executable and that `customlabels.h` is available

in the include path for any source file from which you want to use custom labels. The details of

this will depend on your build system.

## ABI

For profiler authors,

the ABI is v0 of the Custom Labels ABI described [here](custom-labels-v0.md).

## Acknowledgements

* The approach was partially influenced by the APM/universal profiling integration described [here](https://github.com/elastic/apm/blob/bd5fa9c1/specs/agents/universal-profiling-integration.md#process-storage-layout).