Skip to content

Commit

Permalink
feat: Updating flamegraph docs (#13299)
Browse files Browse the repository at this point in the history
* Updating flamegraph
  • Loading branch information
jonathanc-n authored Nov 8, 2024
1 parent 192079e commit f190fc6
Showing 1 changed file with 24 additions and 10 deletions.
34 changes: 24 additions & 10 deletions docs/source/library-user-guide/profiling.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,6 @@

The section contains examples how to perform CPU profiling for Apache DataFusion on different operating systems.

## MacOS

### Building a flamegraph

[Video: how to CPU profile DataFusion with a Flamegraph](https://youtu.be/2z11xtYw_xs)
Expand All @@ -34,31 +32,47 @@ in images such as this:

![Flamegraph](../_static/images/flamegraph.svg)

To create a flamegraph, you need to install the `flamegraph` tool:
## MacOS

#### Step 1: Install the flamegraph Tool

To install flamegraph, run:

```shell
cargo install flamegraph
```

Then you can run the flamegraph tool with the `--` separator to pass arguments
to the binary you want to profile.
#### Step 2: Prepare Your Environment

Ensure that you're in the directory containing the necessary data files for your DataFusion query. The flamegraph tool will profile the execution of your query against this data.

#### Step 3: Running the Flamegraph Tool

To generate a flamegraph, you'll need to use the -- separator to pass arguments to the binary you're profiling. For datafusion-cli, you need to make sure to run the command with sudo permissions (especially on macOS, where DTrace requires elevated privileges).

Here is a general example:

```shell
sudo flamegraph -- datafusion-cli -f <path_to_sql_file/sql_file.sql>
```

#### Example: Generating a Flamegraph for a Specific Query

Example: Flamegraph for `datafusion-cli` executing `q28.sql`. Note this
must be run as root on Mac OSx to access DTrace.
Here is an example using `28.sql`:

```shell
sudo flamegraph -- datafusion-cli -f q28.sql
sudo flamegraph -- datafusion-cli -f 28.sql
```

You can also invoke the flamegraph tool with `cargo` to profile a specific test or benchmark.

Example: Flamegraph for a specific test:
#### Example: Flamegraph for a specific test:

```bash
CARGO_PROFILE_RELEASE_DEBUG=true cargo flamegraph --root --unit-test datafusion -- dataframe::tests::test_array_agg
```

Example: Flamegraph for a benchmark
#### Example: Flamegraph for a benchmark

```bash
CARGO_PROFILE_RELEASE_DEBUG=true cargo flamegraph --root --bench sql_planner -- --bench
Expand Down

0 comments on commit f190fc6

Please sign in to comment.