Merge pull request #25 from pyroscope-io/0.5.0

Version 0.5.0

Author: omarabid

.github/workflows/build.yml

@@ -1,6 +1,20 @@
 name: Build
 
-on: [push, pull_request]
+on: 
+  push:
+    paths:
+    - 'pyroscope_backends/**'
+    - 'pyroscope_cli/**'
+    - 'src/**'
+    - 'tests/**'
+    - '.github/workflows/build.yml'
+  pull_request:
+    paths: 
+    - 'pyroscope_backends/**'
+    - 'pyroscope_cli/**'
+    - 'src/**'
+    - 'tests/**'
+    - '.github/workflows/build.yml'
 
 jobs:
   build:

.github/workflows/python.yml

@@ -0,0 +1,56 @@
+name: Python Package
+
+on: 
+  push:
+    paths:
+    - 'pyroscope_ffi/python/**'
+    - '.github/workflows/python.yml'
+  pull_request:
+    paths: 
+    - 'pyroscope_ffi/python/**'
+    - '.github/workflows/python.yml'
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        target: [x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-apple-darwin, aarch64-apple-darwin]
+        exclude:
+        - os: ubuntu-latest
+          target: x86_64-apple-darwin
+        - os: ubuntu-latest
+          target: aarch64-apple-darwin
+        - os: macos-latest
+          target: x86_64-unknown-linux-gnu
+        - os: macos-latest
+          target: aarch64-unknown-linux-gnu
+
+    env:
+      CIBW_BEFORE_ALL_LINUX: "curl https://sh.rustup.rs -sSf | sh -s -- --default-toolchain stable -y && apt update && apt install -y libssl-dev libunwind8-dev"
+      CIBW_BUILD_VERBOSITY: "1"
+      CIBW_ENVIRONMENT: 'PATH="$PATH:$HOME/.cargo/bin"'
+      CIBW_MANYLINUX_X86_64_IMAGE: "quay.io/pypa/manylinux_2_24_x86_64:latest"
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-python@v2
+
+      - name: Install cibuildwheel
+        run: python -m pip install cibuildwheel==2.4.0
+
+      - name: Build wheels
+        run: python pyroscope_ffi/python -m cibuildwheel --output-dir wheelhouse
+
+      - uses: actions/upload-artifact@v2
+        with:
+          path: ./wheelhouse/*.whl
+
+      - name: Display repo
+        shell: bash
+        run: |
+          cd wheelhouse
+          ls -la

.github/workflows/tests.yml

@@ -1,6 +1,20 @@
 name: Tests
 
-on: [push, pull_request]
+on: 
+  push:
+    paths:
+    - 'pyroscope_backends/**'
+    - 'pyroscope_cli/**'
+    - 'src/**'
+    - 'tests/**'
+    - '.github/workflows/tests.yml'
+  pull_request:
+    paths: 
+    - 'pyroscope_backends/**'
+    - 'pyroscope_cli/**'
+    - 'src/**'
+    - 'tests/**'
+    - '.github/workflows/tests.yml'
 
 jobs:
   test:

Cargo.toml

@@ -1,14 +1,14 @@
 [package]
 name = "pyroscope"
 description = """
-Pyroscope Profiler
+Pyroscope Profiler Agent for continuous profiling of Rust, Python and Ruby applications.
 """
-keywords = ["pyroscope", "profiler"]
+keywords = ["pyroscope", "profiler", "profiling", "pprof"]
 authors = ["Abid Omar <[email protected]>"]
-version = "0.4.0"
+version = "0.5.0"
 edition = "2021"
 license = "Apache-2.0"
-homepage = "https://pyroscope.io"
+homepage = "https://pyroscope.io/docs/rust"
 documentation  = "https://docs.rs/pyroscope"
 repository = "https://github.com/pyroscope-io/pyroscope-rs"
 readme = "README.md"
@@ -23,6 +23,7 @@ members = [
 exclude = [
     "pyroscope_backends",
     "pyroscope_cli",
+    "pyroscope_ffi",
 ]
 
 [[example]]
@@ -53,15 +54,15 @@ path = "examples/internal/rbspy-connect.rs"
 thiserror ="1.0"
 log = "0.4"
 reqwest = { version = "0.11", features = ["blocking"]}
-libc = "^0.2.66"
+libc = "^0.2.124"
 
 [dev-dependencies]
-tokio = { version = "1.13", features = ["full"] }
+tokio = { version = "1.18", features = ["full"] }
 pretty_env_logger = "0.4.0"
 assert_matches = "1"
 pyroscope_pprofrs = { path = "pyroscope_backends/pyroscope_pprofrs" }
-pyroscope_rbspy = { path = "pyroscope_backends/pyroscope_rbspy" }
 pyroscope_pyspy = { path = "pyroscope_backends/pyroscope_pyspy" }
+pyroscope_rbspy = { path = "pyroscope_backends/pyroscope_rbspy" }
 
 [profile.dev]
 opt-level=0

README.md

@@ -15,9 +15,13 @@ You may be looking for:
 - [Crate Documentation](https://docs.rs/pyroscope/)
 - [Examples](examples)
 - [Release notes](https://github.com/omarabid/pyroscope/releases)
+- [Pyroscope CLI](pyroscope_cli)
 
 ## Table of Contents
 - [Quick Start](#quick-start)
+- [Pyroscope Server](#pyroscope-server)
+- [Multi-Threading](#multi-threading)
+- [Profiling Backends](#profiling-backends)
 - [Limitations](#limitations)
 - [Getting Help](#getting-help)
 - [License](#license)
@@ -28,8 +32,8 @@ Add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-pyroscope = "0.4.0"
-pyroscope-pprofrs = "0.1"
+pyroscope = "0.5.0"
+pyroscope-pprofrs = "0.2"
 ```
 
 Configure and create the backend (pprof-rs)
@@ -42,7 +46,7 @@ let pprof_backend = Pprof::new(pprof_config);
 Configure the Pyroscope agent:
 
 ```rust
- let mut agent =
+ let agent =
      PyroscopeAgent::builder("http://localhost:4040", "myapp-profile")
      .backend(pprof_backend)
      .build()?;
@@ -51,19 +55,38 @@ Configure the Pyroscope agent:
 Profile your code:
 
 ```rust
- agent.start();
- // Profiled computation
- agent.stop();
- 
- // Non-profiled computation
+ let agent_running = agent.start()?;
+
+ // Computation to profile 
+
+ let agent_ready = agent_running.stop()?;
+ agent_ready.shutdown();
 ```
 
+### Pyroscope Server
+
+The Pyroscope Agent send the profiling data to a [Pyroscope Server](https://pyroscope.io/docs/installing-pyroscope-overview/). You need to have a Pyroscope Server running in order to consume and visualize this data. It's not possible, currently, to forward the data to another endpoint.
+
+### Multi-Threading
+
+The Pyroscope Agent and the [pprof-rs backend](pyroscope_backends/pyroscope_pprofrs) can profile and report data from a multi-threaded program. [pprof-rs](https://github.com/tikv/pprof-rs), however, does not track child-processes and thus profiling is limited to a single process.
+
+### Profiling Backends
+
+The Pyroscope Agent doesn't do any profiling. The agent role is to orchasrate a profiling backend, and report the profiling data to the Pyroscope Server. The Agent can support external backends (in fact, all current backends are independent crates) and you can make your own. Backends can also be used seperately. The currently available backends are:
+
+- [pprof-rs](pyroscope_backends/pyroscope_pprofrs): Rust profiler. A wrapper around [pprof-rs](https://github.com/tikv/pprof-rs).
+- [rbspy](pyroscope_backends/pyroscope_rbspy): Ruby Profiler. A wrapper around [rbspy](https://rbspy.github.io/).
+- [py-spy](pyroscope_backends/pyroscope_pyspy): Python Profiler. A wrapper around [py-spy](https://github.com/benfred/py-spy).
+
+
 ### Limitations
 
 - **Backend**: The Pyroscope Agent uses [pprof-rs](https://github.com/tikv/pprof-rs) as a backend. As a result, the [limitations](https://github.com/tikv/pprof-rs#why-not-) for pprof-rs also applies.
-- **Tagging**: Adding or removing tags is not possible within threads. In general, the [Pyroscope Agent](https://docs.rs/pyroscope/latest/pyroscope/pyroscope/struct.PyroscopeAgent.html) is not Sync; and as a result a reference cannot be shared between threads. A multi-threaded program could be profiled but the agent is not thread-aware and a particular thread cannot be tagged.
+- **Tagging**: ~~Adding or removing tags is not possible within threads. In general, the [Pyroscope Agent](https://docs.rs/pyroscope/latest/pyroscope/pyroscope/struct.PyroscopeAgent.html) is not Sync; and as a result a reference cannot be shared between threads. A multi-threaded program could be profiled but the agent is not thread-aware and a particular thread cannot be tagged.~~
+As of 0.5.0, the Pyroscope Agent support tagging within threads. Check the [Tags](examples/tags.rs) and [Multi-Thread](examples/multi-thread.rs) examples for usage.
 - **Timer**: epoll (for Linux) and kqueue (for macOS) are required for a more precise timer.
-- **Shutdown**: The Pyroscope Agent might take some time (usually less than 10 seconds) to shutdown properly and drop its threads.
+- **Shutdown**: The Pyroscope Agent might take some time (usually less than 10 seconds) to shutdown properly and drop its threads. For a proper shutdown, it's recommended that you run the `shutdown` function before dropping the Agent.
 
 ### Getting help
 

SECURITY.md

@@ -4,6 +4,7 @@
 
 | Version | Supported          |
 | ------- | ------------------ |
+| 0.5.x   | :white_check_mark: |
 | 0.4.x   | :white_check_mark: |
 | 0.3.x   | :white_check_mark: |
 | < 3.0   | :x:                |

examples/async.rs

@@ -1,7 +1,7 @@
 extern crate pyroscope;
 
 use pyroscope::{PyroscopeAgent, Result};
-use pyroscope_pprofrs::{Pprof, PprofConfig};
+use pyroscope_pprofrs::{pprof_backend, PprofConfig};
 use std::hash::{Hash, Hasher};
 
 fn hash_rounds1(n: u64) -> u64 {
@@ -34,13 +34,20 @@ fn hash_rounds2(n: u64) -> u64 {
 
 #[tokio::main]
 async fn main() -> Result<()> {
-    let mut agent = PyroscopeAgent::builder("http://localhost:4040", "example.async")
-        .backend(Pprof::new(PprofConfig::new().sample_rate(100)))
+    let agent = PyroscopeAgent::builder("http://localhost:4040", "example.async")
+        .backend(pprof_backend(PprofConfig::new().sample_rate(100)))
         .tags([("TagA", "ValueA"), ("TagB", "ValueB")].to_vec())
         .build()?;
 
+    // Show start time
+    let start = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap()
+        .as_secs();
+    println!("Start Time: {}", start);
+
     // Start Agent
-    agent.start()?;
+    let agent_running = agent.start()?;
 
     tokio::task::spawn(async {
         let n = hash_rounds1(300_000);
@@ -57,7 +64,17 @@ async fn main() -> Result<()> {
     .unwrap();
 
     // Stop Agent
-    agent.stop()?;
+    let agent_ready = agent_running.stop()?;
+
+    // Shutdown the Agent
+    agent_ready.shutdown();
+
+    // Show program exit time
+    let exit = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap()
+        .as_secs();
+    println!("Exit Time: {}", exit);
 
     Ok(())
 }

examples/backend.rs

@@ -1,7 +1,7 @@
 extern crate pyroscope;
 
 use pyroscope::{PyroscopeAgent, Result};
-use pyroscope_pprofrs::{Pprof, PprofConfig};
+use pyroscope_pprofrs::{pprof_backend, PprofConfig};
 use std::hash::{Hash, Hasher};
 
 fn hash_rounds(n: u64) -> u64 {
@@ -19,8 +19,8 @@ fn hash_rounds(n: u64) -> u64 {
 }
 
 fn main() -> Result<()> {
-    let mut agent = PyroscopeAgent::builder("http://localhost:4040", "example.basic")
-        .backend(Pprof::new(PprofConfig::new().sample_rate(100)))
+    let agent = PyroscopeAgent::builder("http://localhost:4040", "example.basic")
+        .backend(pprof_backend(PprofConfig::new().sample_rate(100)))
         .tags([("TagA", "ValueA"), ("TagB", "ValueB")].to_vec())
         .build()?;
 
@@ -32,7 +32,7 @@ fn main() -> Result<()> {
     println!("Start Time: {}", start);
 
     // Start Agent
-    agent.start()?;
+    let agent_running = agent.start()?;
 
     let _result = hash_rounds(300_000);
 
@@ -44,9 +44,10 @@ fn main() -> Result<()> {
     println!("Stop Time: {}", stop);
 
     // Stop Agent
-    agent.stop()?;
+    let agent_ready = agent_running.stop()?;
 
-    drop(agent);
+    // Shutdown the Agent
+    agent_ready.shutdown();
 
     // Show program exit time
     let exit = std::time::SystemTime::now()

examples/basic.rs

@@ -1,7 +1,7 @@
 extern crate pyroscope;
 
 use pyroscope::{PyroscopeAgent, Result};
-use pyroscope_pprofrs::{Pprof, PprofConfig};
+use pyroscope_pprofrs::{pprof_backend, PprofConfig};
 
 fn fibonacci(n: u64) -> u64 {
     match n {
@@ -17,19 +17,19 @@ fn main() -> Result<()> {
     // Initialize the logger.
     pretty_env_logger::init_timed();
 
-    let mut agent = PyroscopeAgent::builder("http://invalid_url", "example.error")
-        .backend(Pprof::new(PprofConfig::new().sample_rate(100)))
+    let agent = PyroscopeAgent::builder("http://invalid_url", "example.error")
+        .backend(pprof_backend(PprofConfig::new().sample_rate(100)))
         .build()
         .unwrap();
     // Start Agent
-    agent.start()?;
+    let agent_running = agent.start()?;
 
     let _result = fibonacci(47);
 
     // Stop Agent
-    agent.stop()?;
+    let agent_ready = agent_running.stop()?;
 
-    drop(agent);
+    agent_ready.shutdown();
 
     Ok(())
 }