You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by lh...@apache.org on 2026/09/28 13:27:18 UTC
(pulsar) 14/16: [docs][test] Guide agents through automated folded stack analysis
This is an automated email from the ASF dual-hosted git repository.
lhotari pushed a commit to branch lh-perf-agents-guide-links
in repository https://gitbox.apache.org/repos/asf/pulsar.git
commit 8da65a6328fd6e817655dc4414de8fada11a5ad5
Author: Lari Hotari <lh...@apache.org>
AuthorDate: Mon Sep 28 15:53:50 2026 +0300
[docs][test] Guide agents through automated folded stack analysis
Link DuckDB and quack_flamegraph from the integration agent guide, clarify collapsed and folded stack terminology, and document JSON and CSV output for automation.
Assisted-by: Codex
---
tests/integration/AGENTS.md | 9 +++++++++
tests/performance/README.md | 5 +++--
tests/performance/docs/analyzing-profiles.md | 19 ++++++++++++++++---
3 files changed, 28 insertions(+), 5 deletions(-)
diff --git a/tests/integration/AGENTS.md b/tests/integration/AGENTS.md
index 2ecec545a8db..04c41530f465 100644
--- a/tests/integration/AGENTS.md
+++ b/tests/integration/AGENTS.md
@@ -8,3 +8,12 @@ running or changing them.
- The tests need Docker. `integrationTest` builds the test image when it is out of date; don't build it separately.
- For performance optimizations, use the performance tests rather than a profiled integration test, as
[`tests/performance/AGENTS.md`](../performance/AGENTS.md) guides.
+
+## Analysis tools
+
+Use [DuckDB](https://duckdb.org/) with the
+[quack_flamegraph](https://github.com/kevintruong/quack-flamegraph) community extension to query collapsed
+stacktrace files, also called folded stacktrace files, as SQL tables. See the
+[setup and usage examples](../performance/docs/analyzing-profiles.md#analyzing-collapsed-stacks-with-duckdb)
+for ranking stacks, methods and call edges. Agents and scripts can export query results as JSON with `duckdb -json`
+or CSV with `duckdb -csv -header` for automated analysis, rather than parsing terminal tables or flame graph HTML.
diff --git a/tests/performance/README.md b/tests/performance/README.md
index f7f291581827..499811390c88 100644
--- a/tests/performance/README.md
+++ b/tests/performance/README.md
@@ -344,8 +344,9 @@ time, CPU and allocation flame graphs, cut to the measurement. The broker's jono
time threads spent blocked by the Pulsar or BookKeeper method that waited. The blocked time flame graphs show the same
time as call trees, to inspect visually which code paths lead to the blocking methods.
-The flame graphs' `.collapsed` files can be handled with multiple tools. jonoffcpu's jfr-converter renders them as
-HTML flame graphs and runs through Gradle with no separate installation. Pass any converter options with `--args`;
+The flame graphs' collapsed stacktrace files (`.collapsed`), also called folded stacktrace files (`.folded`), can be
+handled with multiple tools. jonoffcpu's jfr-converter renders them as HTML flame graphs and runs through Gradle
+with no separate installation. Pass any converter options with `--args`;
use `--args='--help'` to list them:
```bash
diff --git a/tests/performance/docs/analyzing-profiles.md b/tests/performance/docs/analyzing-profiles.md
index 3d23e6af88a5..e94478f416d4 100644
--- a/tests/performance/docs/analyzing-profiles.md
+++ b/tests/performance/docs/analyzing-profiles.md
@@ -104,9 +104,11 @@ Profile both revisions with the same profiler options: profiling has a cost, and
## Analyzing collapsed stacks with DuckDB
For SQL analysis, DuckDB's [quack_flamegraph](https://github.com/kevintruong/quack-flamegraph) community extension
-reads collapsed stacks as tables. Start DuckDB and set the `profile` variable to the path of your collapsed stacks
-file, and `pkg` to a regular expression for the frames you're interested in. The queries below read both from there,
-so they can be copied as-is:
+reads collapsed stacktrace files as tables. These are also called folded stacktrace files: `.collapsed` and
+`.folded` are common extensions for the same format, with semicolon-separated frames and a weight at the end of
+each line. Start DuckDB and set the `profile` variable to the path of your collapsed stacks file, and `pkg` to a
+regular expression for the frames you're interested in. The queries below read both from there, so they can be
+copied as-is:
```sql
INSTALL quack_flamegraph FROM community;
@@ -197,6 +199,17 @@ ORDER BY samples DESC
LIMIT 45;
```
+For automated analysis, agents and scripts can export DuckDB query results as JSON or CSV. Save the setup statements
+and one result query in `analysis.sql` (include the view definition if querying `leaf_by_frame`), then run:
+
+```bash
+duckdb -no-init -bail -json < analysis.sql > analysis.json
+duckdb -no-init -bail -csv -header < analysis.sql > analysis.csv
+```
+
+Use one result query per output file so that JSON contains a single array and CSV contains one table with a header.
+`-bail` stops on SQL errors; check the exit status before consuming the output.
+
## Flame graphs of other recordings
The flame graphs of a standalone run are already in its run directory. Recordings made elsewhere need the root