Merge pull request #21 from arielb1/add-decoder

add decoder implementation

Author: arielb1

.github/workflows/build-decoder.yml

@@ -0,0 +1,24 @@
+name: Build (decoder)
+on: [pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      RUST_BACKTRACE: 1
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-directories: decoder
+      - name: Build
+        working-directory: decoder
+        shell: bash
+        run: cargo build --all-features --verbose
+      - name: Run tests
+        working-directory: decoder
+        shell: bash
+        run: cargo test --all-features --verbose

.github/workflows/format.yml

@@ -15,6 +15,11 @@ jobs:
         id: cargoFmt
         shell: bash
         run: cargo fmt --all -- --check
+      - name: Run fmt check - decoder
+        id: cargoFmtDecoder
+        shell: bash
+        working-directory: decoder
+        run: cargo fmt --all -- --check
   clippy:
     name: Cargo clippy
     runs-on: ubuntu-latest
@@ -26,3 +31,17 @@ jobs:
         id: cargoClippy
         shell: bash
         run: cargo clippy --workspace --all-features -- -D warnings
+  clippyDecoder:
+    name: Cargo clippy (decoder)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-directories: decoder
+      - name: Run clippy check - decoder
+        id: cargoClippyDecoder
+        shell: bash
+        working-directory: decoder
+        run: cargo clippy --workspace --all-features -- -D warnings

.gitignore

@@ -1 +1,2 @@
 /target
+/decoder/target

CONTRIBUTING.md

@@ -57,8 +57,6 @@ Then make a new PR for the release and get it approved.
 
 The automated release PR generation functionality is not used here.
 
-This requires a crates.io token in GitHub secrets for the repo. Currently the "token" is literally the string `secret` but I will put a more realistic token once the repo is public. 
-
 [conventional commits]: https://www.conventionalcommits.org/en/v1.0.0/
 
 ## Code of Conduct

Cargo.lock

@@ -84,6 +84,52 @@ emit `tokio.PollCatchV1` events this way:
     }
 ```
 
+## Decoder
+
+The `decoder` directory in the Git repository contains a decoder that can be used to view JFR files, especially with PollCatch information.
+
+The decoder is NOT intended right now to be used in production. In particular, it uses the [`jfrs`] crate for parsing `.jfr` files, and while that crate seems to be purely safe Rust, to my knowledge it has not been audited for security and probably contains at least denial-of-service issues if not worse.
+
+If you want to use the decoder for anything but debugging on trusted `.jfr` files, you bear full responsibility for the consequences.
+
+To use the decoder, you can download the `.zip` file from s3, and then run it:
+```
+aws s3 cp s3://your-bucket/YOUR_PROFILE.zip .
+# the last parameter is the long poll threshold
+./decoder/target/release/pollcatch-decoder longpolls --zip profile_WHATEVER_*.zip 500us
+```
+
+The output should look like this
+```
+[930689.953296] thread 60898 - poll of 8885us
+ -   1: libpthread-2.26.so.__nanosleep
+ -   2: simple.std::thread::sleep_ms
+ -   3: simple.simple::slow::accidentally_slow
+ -   4: simple.simple::slow::accidentally_slow_2
+ -   5: simple.simple::slow::run::{{closure}}::{{closure}}
+ -  16 more frame(s) (pass --stack-depth=21 to show)
+
+[930691.953294] thread 60898 - poll of 736us
+ -   1: libpthread-2.26.so.__nanosleep
+ -   2: simple.std::thread::sleep_ms
+ -   3: simple.simple::slow::accidentally_slow
+ -   4: simple.simple::slow::accidentally_slow_2
+ -   5: simple.simple::slow::run::{{closure}}::{{closure}}
+ -  16 more frame(s) (pass --stack-depth=21 to show)
+
+[930709.953293] thread 60898 - poll of 2736us
+ -   1: libpthread-2.26.so.__nanosleep
+ -   2: simple.std::thread::sleep_ms
+ -   3: simple.simple::slow::accidentally_slow
+ -   4: simple.simple::slow::accidentally_slow_2
+ -   5: simple.simple::slow::run::{{closure}}::{{closure}}
+ -  16 more frame(s) (pass --stack-depth=21 to show)
+```
+
+If it does not work, make sure you are using the most recent version of `async-profiler` and that you enabled the pollcatch hooks.
+
+[`jfrs`]: https://docs.rs/jfrs
+
 ## Security
 
 See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.