Technical Details

Introduction

pyroscope-rs can be described as a general purpose ingestion/forwarding application for profiling data. Though, at the moment, pyroscope-rs is closely tailored to work with a Pyroscope server; and has limited language support (rust, ruby and python).

Components

Timer /timer

The timer thread sends a TimerSignal at regular intervals (each 10th of a second; so 1660034510..1660034520..1660034530...). The timer thread can be interrupted by sending a TimerSignal::Terminate signal to the thread loop. The timer can be compared to the JFR scheduler.

Back-end /backend

Profiling operations should be managed through the Back-end object. The Back-end object provides an abstraction over what the main library expects in terms of data. The internal profiler implementation is irrelevant; however, the Back-end should expose a few functions so that the library can operate it and retrieve data accordingly.

When designing a back-end, it's important to think about these particular functions:

• initialize: The Back-end profiling operation should be uninitialized when first created. This function will enable the main library to initialize the back-end when appropriate. Initialization is synonymous with the start of profiling and data collection.
• shutdown: This function should destroy all the objects the Back-end is using, free all the memory and stop any external profiling operations.
• report: This function should return profiling data up to the last call. When called, any profiling data in the Back-end memory must be cleared. (Otherwise, the Back-end memory will grow indefinitely).

Session Manager /session.rs

The session manager thread receives Session objects and manage their forwarding to the Pyroscope Server endpoint. This is analogous to the JFR Exporter.

Main Library /pyroscope.rs

The main library is a loop that acts as an intermediary between the Back-end and the Session Manager. The main loop is lazy and is activated when it receives a Signal (usually from the Timer, but not strictly)

FFIkit

The FFIkit is a loop that merges signals from two channels: Socket and a standard Rust mpsc. The Socket channel is used when a process is forked and the mpsc channel is no longer available.

Making a release

To make a release, first manually bump the version of the package you want to release, create a tag and then push the tag.

e.g.: To make a new lib release, update Cargo.toml version; create a new tag git tag -a lib-0.x.y -m "lib 0.x.y" and then git push origin --tag`

Possible releases

• lib: git tag -a lib-x.y.z -m "lib x.y.z"
• cli: git tag -a cli-x.y.z -m "cli x.y.z"

Backends:

• Rust: git tag -a pprofrs-x.y.z -m "pprofrs x.y.z"
• Ruby: git tag -a rbspy-x.y.z -m "rbspy x.y.z"
• Python: git tag -a pyspy-x.y.z -m "pyspy x.y.z"

Packages:

• Ruby: git tag -a ruby-x.y.z -m "ruby x.y.z"
• Python: git tag -a python-x.y.z -m "python x.y.z"

Publishing a release

Once a tag is pushed, a draft release is published. Publishing the draft release should trigger the action that will push the packages to the relevant cloud package manager.