apitech
/
grafana
mirror of https://github.com/grafana/grafana
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: update flame graph visualization (#86615)

Browse Source 
* docs: update flame graph visualization

* fix: linting issues

* docs: add example data

* Apply suggestions from code review

Co-authored-by: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com>

* Removed Wikipedia link

* Fixed punctuation

* Updated max image width

* Update docs/sources/panels-visualizations/visualizations/flame-graph/index.md

Co-authored-by: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com>

* fix: linting issues

* docs: add links to pyroscope docs about flame graph and profile types

* Ran prettier

* docs: add flame graph video

* Updated wording

---------

Co-authored-by: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com>
Co-authored-by: Isabel Matwawana <isabel.matwawana@grafana.com>
pull/87271/head
Marie Cruz 1 year ago committed by GitHub
parent cdb9eeb7fc
commit 7db41222c6
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 70 additions and 39 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 109
      docs/sources/panels-visualizations/visualizations/flame-graph/index.md

109
docs/sources/panels-visualizations/visualizations/flame-graph/index.md
Unescape View File

@ -19,23 +19,69 @@ weight: 100
# Flame graph
Flame graphs let you visualize profiling data. Using this visualization, the profile can be represented as a flame graph, table, or both
Flame graphs let you visualize [profiling](https://grafana.com/docs/pyroscope/latest/introduction/profiling/) data. Using this visualization, a [profile](https://grafana.com/docs/pyroscope/latest/view-and-analyze-profile-data/profiling-types/) can be represented as a [flame graph](#flame-graph-mode), [top table](#top-table-mode), or both.
![<Flame graph>](/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1.png)
For example, if you want to understand which parts of a program consume the most resources, such as CPU time, memory, or I/O operations, you can use a flame graph to visualize and analyze where potential performance issues are:
## Flame graph mode
{{< figure src="/static/img/docs/flame-graph-panel/flame-graph-dark-mode.png" max-width="1025px" alt="A flame graph visualization for a system profile with both flame graph and top table mode." >}}
A flame graph takes advantage of the hierarchical nature of profiling data. It condenses data into a format that allows you to easily see which code paths are consuming the most system resources, such as CPU time, allocated objects, or space when measuring memory. Each block in the flame graph represents a function call in a stack and its width represents its value.
You can use a flame graph visualization if you need to:
- Identify any performance hotspots to find where code optimizations may be needed.
- Diagnose the root cause of any performance degradation.
- Analyze the behavior of complex systems, including distributed systems or microservices architectures.
To learn more about how Grafana Pyroscope visualizes flame graphs, refer to [Flame graphs: Visualizing performance data](https://grafana.com/docs/pyroscope/latest/view-and-analyze-profile-data/flamegraphs/).
## Configure a flame graph visualization
Once you’ve created a [dashboard](https://grafana.com/docs/grafana/<GRAFANA_VERSION>/dashboards/build-dashboards/create-dashboard/), the following video shows you how to configure a flame graph visualization:
{{< youtube id="VEvK0JkPlOY" >}}
## Supported data formats
To render a flame graph, you must format the data frame data using a _nested set model_.
A nested set model ensures each item of a flame graph is encoded by its nesting level as an integer value, its metadata, and by its order in the data frame. This means that the order of items is significant and needs to be correct. The ordering is a depth-first traversal of the items in the flame graph which recreates the graph without needing variable-length values in the data frame like in a children's array.
![<Flame graph>](/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-flamegraph.png)
Required fields:
| Field name | Type | Description |
| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
| level | number | The nesting level of the item. In other words how many items are between this item and the top item of the flame graph. |
| value | number | The absolute or cumulative value of the item. This translates to the width of the item in the graph. |
| label | string | Label to be shown for the particular item. |
| self | number | Self value, which is usually the cumulative value of the item minus the sum of cumulative values of its immediate children. |
### Example
The following table is an example of the type of data you need for a flame graph visualization and how it should be formatted:
| level | value | self | label |
| ----- | -------- | ------ | ----------------------------------------- |
| 0 | 16.5 Bil | 16.5 K | total |
| 1 | 4.10 Bil | 4.10 k | test/pkg/agent.(\*Target).start.func1 |
| 2 | 4.10 Bil | 4.10 K | test/pkg/agent.(\*Target).start.func1 |
| 3 | 3.67 Bil | 3.67 K | test/pkg/distributor.(\*Distributor).Push |
| 4 | 1.13 Bil | 1.13 K | compress/gzip.(\*Writer).Write |
| 5 | 1.06 Bil | 1.06 K | compress/flat.(\*compressor).write |
## Modes
### Flame graph mode
A flame graph takes advantage of the hierarchical nature of profiling data. It condenses data into a format that allows you to easily see which code paths are consuming the most system resources, such as CPU time, allocated objects, or space when measuring memory. Each block in the flame graph represents a function call in a stack and its width represents its value.
Grayed-out sections are a set of functions that represent a relatively small value and they are collapsed together into one section for performance reasons.
{{< figure src="/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-tooltip.png" max-width="500px" caption="Hover tooltip" >}}
{{< figure src="/static/img/docs/flame-graph-panel/flame-graph-mode-dark.png" max-width="650px" alt="A flame graph visualization for a system profile with flame graph mode." >}}
You can hover over a specific function to view a tooltip that shows you additional data about that function, like the function's value, percentage of total value, and the number of samples with that function.
### Drop-down actions
{{< figure src="/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-tooltip.png" max-width="650px" alt="A flame graph visualization with a hover tooltip." >}}
#### Drop-down actions
You can click a function to show a drop-down menu with additional actions:
@ -43,29 +89,37 @@ You can click a function to show a drop-down menu with additional actions:
- Copy function name
- Sandwich view
{{< figure src="/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-dropdown.png" max-width="500px" caption="Dropdown actions" >}}
{{< figure src="/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-dropdown.png" max-width="650px" alt="A flame graph visualization with drop-down actions." >}}
#### Focus block
##### Focus block
When you click **Focus block**, the block, or function, is set to 100% of the flame graph's width and all its child functions are shown with their widths updated relative to the width of the parent function. This makes it easier to drill down into smaller parts of the flame graph.
{{< figure src="/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-focus.png" max-width="500px" caption="Focus block" >}}
{{< figure src="/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-focus.png" max-width="650px" alt="A flame graph visualization with focus block action selected." >}}
#### Copy function name
##### Copy function name
When you click **Copy function name**, the full name of the function that the block represents is copied.
#### Sandwich view
##### Sandwich view
The sandwich view allows you to show the context of the clicked function. It shows all the function's callers on the top and all the callees at the bottom. This shows the aggregated context of the function so if the function exists in multiple places in the flame graph, all the contexts are shown and aggregated in the sandwich view.
{{< figure src="/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-sandwich.png" max-width="500px" caption="Sandwich view">}}
{{< figure src="/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-sandwich.png" max-width="650px" alt="A flame graph visualization with sandwich view selected.">}}
### Status bar
#### Status bar
The status bar shows metadata about the flame graph and currently applied modifications, like what part of the graph is in focus or what function is shown in sandwich view. Click the **X** in the status bar pill to remove that modification.
![<Status bar>](/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-status.png)
{{< figure src="/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-status.png" max-width="1025px" alt="A flame graph visualization's status bar.">}}
### Top table mode
The top table shows the functions from the profile in table format. The table has three columns: symbols, self, and total. The table is sorted by self time by default, but can be reordered by total time or symbol name by clicking the column headers. Each row represents aggregated values for the given function if the function appears in multiple places in the profile.
{{< figure src="/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-table.png" max-width="650px" alt="Table view">}}
There are also action buttons on the left-most side of each row. The first button searches for the function name while second button shows the sandwich view of the function.
## Toolbar
@ -73,7 +127,7 @@ The status bar shows metadata about the flame graph and currently applied modifi
You can use the search field to find functions with a particular name. All the functions in the flame graph that match the search will remain colored while the rest of the functions are grayed-out.
![<Searching for function name>](/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-search.png)
{{< figure src="/static/img/docs/flame-graph-panel/flame-graph-search-dark.png" max-width="1025px" alt="Searching for a function name in a flame graph visualization.">}}
### Color schema picker
@ -88,26 +142,3 @@ Align text either to the left or to the right to show more important parts of th
### Visualization picker
You can choose to show only the flame graph, only table, or both at the same time
## Top table mode
The top table shows the functions from the profile in table format. The table has three columns: symbols, self, and total. The table is sorted by self time by default, but can be reordered by total time or symbol name by clicking the column headers. Each row represents aggregated values for the given function if the function appears in multiple places in the profile.
![Table view](/media/docs/grafana/panels-visualizations/flamegraph/screenshot-flamegraph-10.1-table.png)
There are also action buttons on the left for each row. The first button searches for the function name while second button shows the sandwich view of the function.
## Data API
In order to render the flame graph, you must format the data frame data using a [nested set model](https://en.wikipedia.org/wiki/Nested_set_model).
A nested set model ensures each item of the flame graph is encoded just by its nesting level as an integer value, its metadata, and by its order in the data frame. This means that the order of items is significant and needs to be correct. The ordering is a depth-first traversal of the items in the flame graph which recreates the graph without needing variable-length values in the data frame like in a children's array.
Required fields:
| Field name | Type | Description |
| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| level | number | The nesting level of the item. In other words how many items are between this item and the top item of the flame graph. |
| value | number | The absolute or cumulative value of the item. This translates to the width of the item in the graph. |
| label | string | Label to be shown for the particular item. |
| self | number | Self value which is usually the cumulative value of the item minus the sum of cumulative values of its immediate children. |

Write Preview
Loading…
Cancel
Save