Skip to content

Rename icicle graph to flame graph in docs #477

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
yomete merged 1 commit into from
Jul 9, 2025
Merged

Rename icicle graph to flame graph in docs #477

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/binary-filtering.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,15 +25,15 @@ To see the list of the binaries in the profile, click on the "Show Legend" butto
<br />
<BrowserWindow>

![An icicle graph filtered by a binary](../static/img/tutorial/filtered-by-binary.png)
![A Flame Graph filtered by a binary](../static/img/tutorial/filtered-by-binary.png)

</BrowserWindow>

<br />
The example above specifically works for when you want to only see data in the icicle
graph for a particular binary. So how about when you want to see data in the icicle
graph excluding a particular binary? You can do this by right-clicking on the frame
in the icicle graph and then click on the "Hide Binary" option. This will hide the
The example above specifically works for when you want to only see data in the Flame
Graph for a particular binary. So how about when you want to see data in the Flame
Graph excluding a particular binary? You can do this by right-clicking on the frame
in the Flame Graph and then click on the "Hide Binary" option. This will hide the
data for the binary you right-clicked on.

<BrowserWindow>
Expand All @@ -46,15 +46,15 @@ data for the binary you right-clicked on.

<BrowserWindow>

![The icicle graph showing filtered data](../static/img/tutorial/hidden-binary-filtered.png)
![The Flame Graph showing filtered data](../static/img/tutorial/hidden-binary-filtered.png)

</BrowserWindow>

<br />

This is especially useful for Python workloads that call out to native extensions, so just viewing interpreted frames is not quite right, but just hiding the Python runtime. This means other native extensions like libcuda or pytorch would still be visible.

In addition to that, you can hide multiple binaries at a time! Using the same icicle graph as above, we also want to hide the <em>libc.so.6</em> frames.
In addition to that, you can hide multiple binaries at a time! Using the same Flame Graph as above, we also want to hide the <em>libc.so.6</em> frames.

<BrowserWindow>

Expand All @@ -64,12 +64,12 @@ In addition to that, you can hide multiple binaries at a time! Using the same ic
<br />
<BrowserWindow>

![The icicle graph being filtered by multiple binaries](../static/img/tutorial/multiple-hidden-binaries.png)
![The Flame Graph being filtered by multiple binaries](../static/img/tutorial/multiple-hidden-binaries.png)

</BrowserWindow>
<br />

To get the icicle graph back to its initial state, there's a "Reset Legend" button to reset the icicle graph.
To get the Flame Graph back to its initial state, there's a "Reset Legend" button to reset the Flame Graph.

<BrowserWindow>

Expand Down
32 changes: 19 additions & 13 deletions docs/binary.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,29 @@
# Parca from Binary

import WithVersions from '@site/src/components/WithVersions';
import CodeBlock from '@theme/CodeBlock';
import BrowserWindow from '@site/src/components/BrowserWindow';
import WithVersions from "@site/src/components/WithVersions";
import CodeBlock from "@theme/CodeBlock";
import BrowserWindow from "@site/src/components/BrowserWindow";

You can download the latest binary release for your architecture from our [releases page](https://github.com/parca-dev/parca/releases).

<WithVersions language="bash">
{ versions =>
{(versions) => (
<CodeBlock className="language-bash">
curl -sL https://github.com/parca-dev/parca/releases/download/{versions.server}/parca_{versions.server.substring(1)}_`uname -s`_`uname -m`.tar.gz | tar xvfz - parca
curl -sL https://github.com/parca-dev/parca/releases/download/
{versions.server}/parca_{versions.server.substring(1)}_`uname -s`_`uname
-m`.tar.gz | tar xvfz - parca
</CodeBlock>
}
)}
</WithVersions>

We also produce Docker images that can be pulled:

<WithVersions language="bash">
{ versions =>
{(versions) => (
<CodeBlock className="language-bash">
docker pull ghcr.io/parca-dev/parca:{versions.server}
</CodeBlock>
}
)}
</WithVersions>

We provide an example configuration file that you can use to get Parca running, and the scrape configuration section should look familiar to anyone familiar with Prometheus.
Expand All @@ -39,12 +43,14 @@ scrape_configs:
```

You can download from our repository:

<WithVersions language="bash">
{ versions =>
{(versions) => (
<CodeBlock className="language-bash">
curl -sL https://raw.githubusercontent.com/parca-dev/parca/{versions.server}/parca.yaml > parca.yaml
curl -sL https://raw.githubusercontent.com/parca-dev/parca/
{versions.server}/parca.yaml > parca.yaml
</CodeBlock>
}
)}
</WithVersions>

To start Parca, pass this config file with the `config-path` flag:
Expand Down Expand Up @@ -147,12 +153,12 @@ Selecting one of these profile types and clicking the `Search` button will retri

</BrowserWindow>

This should result in a time series based on the profile that is interactable. Clicking anywhere on the line graph should then bring up an icicle graph for the profile that you've selected.
This should result in a time series based on the profile that is interactable. Clicking anywhere on the line graph should then bring up an Flame Graph for the profile that you've selected.

<BrowserWindow>

![image](https://user-images.githubusercontent.com/8681572/133893258-96fdbc0a-8036-4d89-bb4c-578fb131c8e0.png)

</BrowserWindow>

You can then interact with the icicle graph to better understand how Parca is behaving.
You can then interact with the Flame Graph to better understand how Parca is behaving.
12 changes: 6 additions & 6 deletions docs/concepts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Concepts

import BrowserWindow from '@site/src/components/BrowserWindow';
import BrowserWindow from "@site/src/components/BrowserWindow";

## Data model

Expand All @@ -18,9 +18,9 @@ Parca ingests profiles using the open-source pprof profile.proto format. More ca

The pprof utility offers a robust set of tools for exploring profiles. Parca specifically tries to solve the storage and retrieval of these profiles, and allows you to explore these profiles across time.

## Icicle Graphs
## Flame Graphs

Often to better understand how your application is behaving you need to compare two profiles. Parca allows you to make selections of two points in time that you want to compare and will generate an icicle graph of the difference between the two selected profiles.
Often to better understand how your application is behaving you need to compare two profiles. Parca allows you to make selections of two points in time that you want to compare and will generate an Flame Graph of the difference between the two selected profiles.

If a span is larger in the second profile, you'll see that span colored in red, and will be darker shade the larger the difference is. This allows one to quickly visually identify where a program is growing in usage scope.

Expand All @@ -42,14 +42,14 @@ If a span remains blue, it means there was no significant change between the two

## Cumulative and Diff values

When comparing two profiles, it's not unusual to see a `Cumulative` value and `Diff` value in the tooltip that displays when you hover over the icicle graph.
When comparing two profiles, it's not unusual to see a `Cumulative` value and `Diff` value in the tooltip that displays when you hover over the Flame Graph.

<BrowserWindow>

![image](https://user-images.githubusercontent.com/9016992/146777868-90f145fd-aaab-451d-8848-247877a7dde3.png)

</BrowserWindow>
</BrowserWindow>

As an example, a stack trace like `main() > foo() > bar()` where `main` calls `foo` that calls `bar`. In one profile, we observe this stack trace running at 500ns, so its cumulative value will be 500 and then later in another profile, we see this stack trace but it was running for only 300ns, thus it's cumulative value will be 300.

However, if we compare the latest stack trace that was running at 300ns to the former one running 500ns, we see that the diff is 300-500 = -200. It means that compared to the first profile we've seen this same stack trace 200ns less.
However, if we compare the latest stack trace that was running at 300ns to the former one running 500ns, we see that the diff is 300-500 = -200. It means that compared to the first profile we've seen this same stack trace 200ns less.
52 changes: 31 additions & 21 deletions docs/kubernetes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Kubernetes

import WithVersions from '@site/src/components/WithVersions';
import CodeBlock from '@theme/CodeBlock';
import BrowserWindow from '@site/src/components/BrowserWindow';
import WithVersions from "@site/src/components/WithVersions";
import CodeBlock from "@theme/CodeBlock";
import BrowserWindow from "@site/src/components/BrowserWindow";

:::tip

Expand Down Expand Up @@ -46,11 +46,12 @@ Creating this namespace is not strictly necessary, but it prevents a race with t
To provision the Parca against any Kubernetes cluster, and use the API and UI:

<WithVersions language="bash">
{ versions =>
{(versions) => (
<CodeBlock className="language-bash">
kubectl apply -f https://github.com/parca-dev/parca/releases/download/{versions.server}/kubernetes-manifest.yaml
kubectl apply -f https://github.com/parca-dev/parca/releases/download/
{versions.server}/kubernetes-manifest.yaml
</CodeBlock>
}
)}
</WithVersions>

You can verify by selecting pods if everything runs as expected:
Expand All @@ -63,6 +64,7 @@ parca parca-5f879c46ff-pv649 1/1 Running 0 53m
```

To view the Parca UI and access the API, we can port-forward using the default port `7070`:

```
kubectl -n parca port-forward service/parca 7070
```
Expand All @@ -88,12 +90,15 @@ Creating this namespace is not strictly necessary, but it prevents a race with t
:::

To provision the Parca Agent as a `DaemonSet`:

<WithVersions language="bash">
{ versions =>
{(versions) => (
<CodeBlock className="language-bash">
kubectl apply -f https://github.com/parca-dev/parca-agent/releases/download/{versions.agent}/kubernetes-manifest.yaml
kubectl apply -f
https://github.com/parca-dev/parca-agent/releases/download/
{versions.agent}/kubernetes-manifest.yaml
</CodeBlock>
}
)}
</WithVersions>

You can verify by selecting pods if everything runs as expected:
Expand All @@ -107,27 +112,30 @@ parca-agent-b66vt 1/1 Running 0 54m
```

Let's set up a port-forward using the default port `7071`.

```
kubectl -n parca port-forward `kubectl -n parca get pod -lapp.kubernetes.io/name=parca-agent -ojsonpath="{.items[0].metadata.name}"` 7071
```

Now we can view the active profilers by visiting `http://localhost:7071`:

<BrowserWindow>

![image](../static/img/tutorial/active_profilers.png)

</BrowserWindow>

<br/>
<br />

And all the discovered processes:

<BrowserWindow>

![image](../static/img/tutorial/processes.png)

</BrowserWindow>

<br/>
<br />

To continuously send every profile collected to a Parca server configure the `--remote-store-address` and the potential credentials needed.
For example, to send to a Parca server in the `parca` namespace set: `--remote-store-address=parca.parca.svc:7070`.
Expand All @@ -137,7 +145,7 @@ This has already been set up for our current setup in the previously applied man

You can use `--remote-store-insecure` and `--remote-store-insecure-skip-verify` for simpler setups.

``` shell
```shell
--remote-store-insecure Send gRPC requests via plaintext instead of
TLS.
--remote-store-insecure-skip-verify
Expand All @@ -156,28 +164,29 @@ You should shortly see the `Select profile...` dropdown menu populate with the p
Parca supports any pprof formatted profile, but here we are demonstrating Parca Agent's automatic profiling with zero-instrumentation, which currently only supports CPU profiling.

:::

<BrowserWindow>

![image](../static/img/tutorial/profile_type_dropdown_selected.png)

</BrowserWindow>

<br/>
<br />

Selecting `CPU Samples` as profile type and clicking the `Search` button will retrieve the profiles from Parca Agent for the time selection (default Last Hour).

This should result in a time series based on the profile that is interactable.
Clicking anywhere on the line graph should then bring up an icicle graph for the profile that you've selected.
Clicking anywhere on the line graph should then bring up a Flame Graph for the profile that you've selected.

<BrowserWindow>

![image](../static/img/tutorial/cpu_sample_count_select.png)

</BrowserWindow>

<br/>
<br />

You can then interact with the icicle graph to better understand how Parca is behaving.
You can then interact with the Flame Graph to better understand how Parca is behaving.

:::info

Expand All @@ -193,7 +202,7 @@ If you go to query bar and enter `namespace="kube-system"` you can focus on them

</BrowserWindow>

<br/>
<br />

And you can click the samples on the graph to focus on the individual profiles.

Expand All @@ -203,7 +212,6 @@ And you can click the samples on the graph to focus on the individual profiles.

</BrowserWindow>


### Selecting a subset of applications to profile

Metadata discovery mechanism enriches the collected profiles with Kubernetes labels. You can use relabelling feature of the Parca Agent to drop a subset of labels.
Expand All @@ -216,6 +224,7 @@ To learn more about relabelling please see the [Prometheus `relabel_config` docu
:::

First you need to specify a configuration file if you haven't already. The relevant manifest changes on `parca-agent-daemonSet.yaml` would like the following:

```diff
...
template:
Expand Down Expand Up @@ -245,11 +254,12 @@ For brevity, we skip the details of mounting a `ConfigMap` with relevant content
:::

For example, to only profile Pods with the `app.kubernetes.io/name=my-web-app` label, the relevant configuration file `/etc/parca-agent.yaml` would like the following:

```yaml
relabel_configs:
- source_labels: [app_kubernetes_io_name]
regex: my-web-app
action: keep
- source_labels: [app_kubernetes_io_name]
regex: my-web-app
action: keep
```

:::tip
Expand Down
Loading