# Working with visualizations


In Amazon CodeGuru Profiler, you can use visualizations to explore profiling data collected from applications in a profiling group. When a profiling group has enough information to display, you can view an *overview* visualization of the profiling group data. 

A visualization is a collection of stack frames that were profiled in the running application. A stack frame contains the state of one method invocation. The name of the method is displayed in the visualization. You can pause over a frame to see its full name and timing details. You can also see the active CPU cost of the method as it exists in the substack of the frame. Frames with the same frame name are highlighted in the rest of the visualization. You can hide a stack frame from the visualization or inspect a specific frame. You can also zoom and search for a function.

The following topics describe how to navigate, filter, and visualize data collected from your running applications.

**Topics**
+ [

# Accessing visualizations
](working-with-visualizations-accessing.md)
+ [

# Types of visualizations
](working-with-visualizations-visualization-types.md)
+ [

# Exploring visualization data
](working-with-visualizations-exploring.md)
+ [

# Filtering visualization data
](working-with-visualizations-filtering.md)
+ [

# Selecting a custom time range
](working-with-visualizations-time-range.md)
+ [

# Understanding the summary page
](working-with-visualizations-summary-page.md)
+ [

# Understanding the heap summary
](working-with-visualizations-heap-summary.md)
+ [

# Comparing two time ranges
](working-with-visualizations-diff.md)

# Accessing visualizations


 The following instructions show you where to find the visualizations of your profiling group data in the CodeGuru Profiler console.

1. Open the [CodeGuru Profiler console](https://console.aws.amazon.com/codeguru/profiler/).

1. In the navigation pane on the left, under **Profiler**, choose **Profiling groups**. 

1. Choose your profiling group to view the summary page for that group.

1. On the summary page, locate the summary panel for the data you want to visualize, and select **Visualize CPU**, **Visualize latency**, or **Visualize heap**, depending on the visualization you wish to see.

   Once you've navigated to the **Visualize** page, you can switch between **Data** and **View** using the drop down menus above the visualization panel.

For more information on visualization types, see [Types of visualizations](working-with-visualizations-visualization-types.md).

# Types of visualizations


Amazon CodeGuru Profiler uses three types of visualizations to display profiling data collected from applications. 
+ An *overview* visualization provides a bottom-up view of your profiling data. 
+ A *hotspots* visualization provides a top-down view of your profiling data. 
+ An *inspect* visualization provides a focus view of a named stack frame. 

Together, these visualizations can help you identify potential performance issues in your applications. All visualizations use a common set of tools to explore and filter data.

The following topics provide more information about each visualization type. 

**Topics**
+ [

## Overview visualizations
](#working-with-visualizations-overview-visualization)
+ [

## Hotspots visualizations
](#working-with-visualizations-hotspots-visualization)
+ [

## Inspect visualizations
](#working-with-visualizations-inspect-visualization)

## Overview visualizations


An overview visualization provides a bottom-up view of your profiling data. It's similar to reading a stack trace in many IDEs. At the bottom of the visualization are the entry point functions. As you move higher, there are functions that are called deeper in the stack trace. Functions at the top of the visualization are the ones doing basic system operations. 

### From stack traces to overview visualization


The following example shows how stack trace samples are represented in an overview visualization. Each stack trace that we sample from the profiled application is added to the visualization.

```
Thread main
    java.lang.Thread.State: RUNNABLE
      com.amazon.profiler.demo.Example.doOne()
      com.amazon.profiler.demo.Example.doPlenty()
      com.amazon.profiler.demo.Example.main(String[])
```

![\[Image: Stack traces in overview 1.\]](http://docs.aws.amazon.com/codeguru/latest/profiler-ug/images/stacks-to-graph1.png)


```
 Thread main
    java.lang.Thread.State: TIMED_WAITING
      java.lang.Thread.sleep(long)
      com.amazon.profiler.demo.Example.doPlenty()
      com.amazon.profiler.demo.Example.main(String[])
```

![\[Image: Stack traces in overview 2.\]](http://docs.aws.amazon.com/codeguru/latest/profiler-ug/images/stacks-to-graph2.png)


```
Thread main
    java.lang.Thread.State: RUNNABLE
      com.amazon.profiler.demo.Example.doPlenty()
      com.amazon.profiler.demo.Example.main(String[])
```

![\[Image: Stack traces in overview 3.\]](http://docs.aws.amazon.com/codeguru/latest/profiler-ug/images/stacks-to-graph3.png)


```
Thread main
    java.lang.Thread.State: RUNNABLE
      com.amazon.profiler.demo.Example.doOne()
      com.amazon.profiler.demo.Example.main(String[])
```

![\[Image: Stack traces in overview 4.\]](http://docs.aws.amazon.com/codeguru/latest/profiler-ug/images/stacks-to-graph4.png)


As we collect more samples, the functions in which threads spend a lot of time appear wider in the visualization.

### What you can learn from overview visualization


An overview visualization can help you find specific call stacks that lead to inefficient code. You can find code that is running on the CPU by looking for flat tops in the visualization. The flat tops are areas where the CPU is doing work directly in that function.

![\[Image: Overview.\]](http://docs.aws.amazon.com/codeguru/latest/profiler-ug/images/overview.png)


**Note**  
This example of an overview is in CPU view (see [Selecting and coloring thread states](working-with-visualizations-thread-states.md)).

This overview example tells the following: 
+ The `doOne` function is called inside both `main` function and `doPlenty` function because it appears above both frames.
+ More than half of the CPU time spent in `doPlenty` is actually spent in the `doOne` function because the width of `doOne` is more than half the width of `doPlenty`. 
+ The `doPlenty` function is also doing some basic CPU operations because it has some self time (some width with no callee frames). 

The overview example *DOES NOT* tell the following: 
+ Inside `main` code, the `doOne` function is called before the `doPlenty` function. Frames are ordered alphabetically, and from the visualization, we can't tell in which order the functions are called. 
+ The `doOne` function is called more often than the `random` function. The overview visualization only tells that more CPU time is spent in `doOne` but CodeGuru Profiler doesn't give any information about the number of times it was called. It might be that it is called less often but is more CPU heavy. 
+ The `doPlenty` function takes n seconds to execute. CodeGuru Profiler doesn't measure execution time; it only provides estimates of the average CPU time spent in that function over the profile's time range. It's not a duration. A CPU-heavy function that is rarely called and a cheap function that is called many times can look similar in an overview visualization. 

An overview visualization can make it difficult to spot problems with functions that are spread around in multiple stacks. For example, logging calls are often distributed across threads and functions. In these cases, a hotspots visualization might be a better choice. 

## Hotspots visualizations


A hotspots visualization shows a top-down view of your profile. The functions consuming the most application time are at the top of the visualization. The entry point functions are at the bottom of the visualization.

You can use a hotspots visualization to investigate functions that are by themselves computationally expensive. 

### Example


![\[Image: Overview.\]](http://docs.aws.amazon.com/codeguru/latest/profiler-ug/images/hotspots.png)


This overview example tells the following: 
+ The `doOne` function has two different callers because there are two frames below it.
+ Most of the overall CPU time is spent in the `doOne` function because it is the majority of the width in the top row.

## Inspect visualizations


An inspect visualization is useful to analyze a frame that appears in many places in a visualization. It groups all of the frames with the same name together in the middle of the visualization. Children (callees) are merged into the visualization above the frame. Parents (callers) are merged into the visualization below the frame. 

# Exploring visualization data


CodeGuru Profiler makes it easy to explore visualization data. You can pause over frames to see information about methods, zoom in on a frame to see more context, and inspect a frame to see the data in an inspect visualization.

**Topics**
+ [

# Choosing my code in visualizations
](working-with-visualizations-choosing-my-code.md)
+ [

# Pausing over a frame
](working-with-visualizations-pause.md)
+ [

# Zooming in on a frame
](working-with-visualizations-zoom.md)
+ [

# Resetting zoom in a visualization
](working-with-visualizations-reset.md)
+ [

# Inspecting a frame
](working-with-visualizations-inspect.md)
+ [

# Understanding the dollar estimate of the CPU cost for frames
](working-with-visualizations-additional-info.md)

# Choosing my code in visualizations


CodeGuru Profiler differentiates your code in the overview visualization, so you can quickly identify the methods you are working on. 

The blue portion of the flame graph highlights your code. The green portion of the graph highlights other code that your application uses, such as libraries and frameworks.

![\[Image: Stack traces in overview 1.\]](http://docs.aws.amazon.com/codeguru/latest/profiler-ug/images/mycode.png)


You can change the coloring by manually selecting which package name you want CodeGuru Profiler to identify as your code.

**To view your code**

1. Choose **Actions**.

1. Choose **Select my code**.

1. Search for the profile namespace that you want to view. The namespaces are sorted based on how much of the overall profiling data they represent.

# Pausing over a frame


One of the easiest ways to begin exploring visualization data is by pausing over the visualization. When you pause over a frame, all frames with the same function name are highlighted. This makes it easy to see where and how often the function is called. 

You can also see details about the function. CodeGuru Profiler displays the name of the function, how much time it has run on the CPU in that stack frame, and the sample time spent in the selected thread states. 

# Zooming in on a frame


Clicking a frame zooms in on the function. The frame becomes the new "base" of the visualization. The visualization shows callees of the selected function. Only the functions in the call chain leading to the call of the selected function are displayed. 

You can zoom in on any visible frame.

To zoom back out, choose **ALL**. In a hotspots visualization, **ALL** is located at the top of the visualization. In an overview visualization, it's at the bottom. 

# Resetting zoom in a visualization


You can zoom in to stack frames to view details. To return to the top-most view, you can reset the zoom. 

**To reset the visualization**
+ On the **Profiling group detail** page, choose **Actions**, and then choose **Reset zoom**. 

# Inspecting a frame


You can inspect frames that appear in many places in a visualization. This can happen when your application code has a common set of shared functions. 

For example, if you have code that compresses data, you might call it from dozens of functions. If you inspect the compress function, you can see the parent (callers) and children (callee) functions at a glance. 

**To inspect a frame**

1. On the **Profiling group detail** page, pause over the frame you want to inspect on the visualization. 

1. Open the context (right-click) menu, and then choose **Inspect frame**. 

# Understanding the dollar estimate of the CPU cost for frames


Amazon CodeGuru Profiler provides an estimated dollar value for the active CPU cost of a frame. The value is an estimation that can help you understand where your optimization efforts will be most valuable. 

To view a frame's dollar estimate, pause over the frame. When you pause over other frames, you see a dollar value estimation that's based on that frame's portion of the total CPU time.

**Note**  
This estimated value does not represent your monthly bill. 

The estimated dollar value shown on the **ALL** frame represents the yearly cost of the compute fleet seen during profiling. This is based on the on-demand AWS compute pricing in the AWS Region of your profiling group. 

To view information about your compute fleet, choose **Actions**, then choose **Additional profiling data information**.

# Filtering visualization data


This section contains information about how to filter profiling data.

**Topics**
+ [

# Selecting and coloring thread states
](working-with-visualizations-thread-states.md)
+ [

# Hiding a frame
](working-with-visualizations-hiding-frame.md)

# Selecting and coloring thread states


In a visualization view, you can filter profiling data by thread state. You can color thread states inside of stack frames to make it easy to spot how the application is behaving. You can also select which thread states are displayed.

**Note**  
The CPU view and latency view were not supported for first release of Python applications; if you open old Python profiles from before February 2021, the profiling data represents wall clock time percentages for each frame. This is similar to the latency view, without the different thread states and colors. On recent Python profiles the different views work normally.

CPU view – The default thread state view for visualizations, it's useful to try to reduce CPU utilization. It displays frames for thread states that correspond to CPU usage: `RUNNABLE`, `BLOCKED`, and `NATIVE`. In this view, the different shades of coloring simply help with visualization, and are based on the frame names. 

Latency view – Useful to try to improve the latency of all or part of your application. When you select it, the visualization displays frames for all of the thread states except `IDLE`. All of these threads might contribute to latency. Frames in the visualization are colored based on the thread state. 

Custom view – You can choose to select the thread states for frames to include in the visualization. The threads you can select are the ones found in your profile data. You can also choose whether to color the frames based on thread states. 

## Example of differences between CPU view and latency view



****  

| CPU view | Latency view | 
| --- | --- | 
|  ![\[Image: CPU view.\]](http://docs.aws.amazon.com/codeguru/latest/profiler-ug/images/cpu-visualization.png)  |  ![\[Image: Latency view.\]](http://docs.aws.amazon.com/codeguru/latest/profiler-ug/images/latency-visualization.png)  | 

The `callOtherService` function appears smaller in the **CPU** view because it's not showing the time when the thread was in a waiting state. In the **Latency view**, we still see the part where the CPU was active (in red), but we also see when the threads were waiting (in green). 

If you're trying to reduce your CPU usage, the **CPU view** shows you that `localActions` is the most CPU heavy inside `handleServiceCall`, and you might want to optimize this part. 

If you're trying to improve the latency of `handleServiceCall`, the **Latency view** shows you that most of the time is spent in `callOtherService`. You can check if this is expected and try to reduce the number of calls or speed up the execution of calls (for example, caching or batching the requests, or calling a closer AWS Region). 

# Hiding a frame


When you hide a frame, the visualization no longer shows that frame or its callee frames. This is useful when you want to remove certain execution paths from the visualization. For example, you can exclude the `myFunction` function if it's not causing performance issues. All occurrences of that frame in the visualization will be hidden.

**To hide a stack frame while pausing over it**

1. On the **Profiling group detail** page, pause over the frame you want to inspect on the visualization. 

1. Open the context (right-click) menu, and then choose **Hide frame**. 

**To search for stack frames to hide**

1. On the **Profiling group detail** page, choose **Actions**, and then choose **Hide frames**. 

1. In the **Hidden frames** page, specify a search string. As the string is provided, results will automatically update. 

1. Select a stack frame to hide. When you're done, close the **Hidden frames** page.

**To unhide stack frames**

1. Choose **X Hidden frames** in the upper-left corner. It opens the **Hidden frames** menu with the list of already hidden frames. **X** is how many frames are currently hidden. 

1. Choose **Show** on any of the hidden frames to stop hiding it. 

# Selecting a custom time range


By default, visualizations display the latest hour of data from the profiling group. You can select a different start time and end time to explore other data for other time ranges. This can be helpful to see how performance has changed over time. 

**To select a custom time range**

1. In the **Profiling group detail** page, at the top of the visualization, select the date/time displayed. For example, **2019-12-04 @ 7:30 - 7:40 PST**. 

1. In the **Select a custom time range** page, choose a **Start time**. You can optionally keep the existing start time. 

1. Choose an **End time**. You can optionally keep the existing end time. 

1. Choose **Confirm** to update the visualization. 

If there is not enough data for the selected range, select a different time range. For the CodeGuru Profiler preview, you can reset the time range back to the default by choosing **Profiler**, **Profiling groups** in the navigation pane, and then selecting the profiling group. 

# Understanding the summary page


The Amazon CodeGuru Profiler summary page displays the status of your profiling group and relevant metrics gathered during profiling. The metrics shown are for any data gathered in the last 12 hours, up to the beginning of the current UTC hour.

Most information is only displayed while the profiling group is enabled. If a profiling group is disabled, or becomes inactive, then metrics and reports are not shown. You can view the following elements in the summary page.

To view the summary page, go to the [CodeGuru Profiler console](https://console.aws.amazon.com/codeguru/profiler/) and choose **Profiling groups** in the navigation bar. Then select the profiling group that you want to view.

## Profiling group status


This is the latest general information regarding the status of the profiling group.

## CPU summary


The **CPU utilization** gives an indication of how much of the instance’s CPU resources are consumed by the profiled application. For JVM applications, this gives a percentage of system CPU resources consumed by the JVM. The metric value is an average across all instances reporting data to this profiling group.

A low value (for example < 10%) indicates your application does not consume a large amount of the system CPU capacity. This means there could be an opportunity to use smaller instances or autoscaling to reduce cost, as long as there is nothing else running on the system. A high value (>90%) indicates your application is consuming a large amount of system CPU capacity. This means there is likely value in looking at your CPU profiles and recommendations for areas of optimization. The values are averages over the last full 12 hours.

The **Agent CPU usage** provides an estimate of how much of the system CPU resources are consumed by the CodeGuru Profiler agent on average across profiled instances. It’s expected that this value is low (<1%); however, it can be normal for this to be higher depending on the application being profiled. If the number concerns you, please get in touch with AWS Support, or provide feedback at the bottom of the page.

The **Time spent executing code** is a measure of how frequently your application’s JVM threads were in the `RUNNABLE` thread state, as a percentage of all thread states except `IDLE`.

A high percentage (>90%) indicates most of your application’s time is spent executing operations on the CPU. A very low percentage (<1%) indicates that most of your application was spent in other thread states (e.g. `BLOCKED` or `WAITING`) and there may be more value in looking at the **Latency** visualization, which displays all non-`IDLE` thread states, instead of the **CPU** visualization.

## Latency summary


The **Time spent blocked** is a measure of how often your threads are in the `BLOCKED` state, once we exclude all `IDLE` threads. This can happen if your application makes frequent use of synchronized blocks or monitor locks. The **Latency** visualization can help you understand what sections of code are causing threads to block.

**Time spent waiting** is a measure of how much time your application’s thread spent in the `WAITING` and `TIMED WAITING` thread states, as a percentage of all thread states except `IDLE`. This is frequently caused by I/O operations such as network calls or disk operations. The **Latency** visualization can help you understand which sections of code are causing threads to wait.

## Heap usage


The **Average heap usage** shows how much of your application’s maximum heap capacity is consumed by your application on average across all profiled instances. The percentage shown is the average heap space used compared to the JVM’s maximum heap capacity, with the absolute value for the average heap space used shown next to it.

A high percentage (>90%) could indicate that your application is close to running out of memory most of the time. If you wish to optimize this, then the **Heap summary** visualization shows you the object types consuming the most space on the heap. A low percentage (<10%) may indicate that your JVM is being provided much more memory than it actually requires and cost savings may be available by reducing your system memory size, although you should check the peak usage too.

The **Peak heap usage** metric shows the highest percentage of memory consumed by your application seen by the CodeGuru Profiler agent. This is based on the same dataset as seen in the **Heap summary** visualization. A high percentage (>90%) could indicate that your application has high spikes of memory usage, especially if your average heap usage is low. 

Choose **Visualize heap** to see your application's heap usage over time. For information on understanding the heap summary, see [Understanding the heap summary](working-with-visualizations-heap-summary.md). 

## Anomalies


CodeGuru Profiler discovers anomalies by analyzing trends in your profiling data and detecting deviations in that data. Any anomalies found are shown here along with details of which time period is anomalous. Further details can be found in the linked report.

## Recommendations


CodeGuru Profiler makes recommendations that you can use to optimize your applications. Any recommendations available are shown here along with details of the estimated impact on your overall application profile. Further details can be found on the linked report.

# Understanding the heap summary


The **Heap summary** visualization shows your application’s heap usage over time. You can change the time period shown using the time range selector in the top-right. For information on enabling the heap summary data collection feature, see [Step 4: Start CodeGuru Profiler in your application](setting-up-long.md#setting-up-step-4).

To view your application's heap summary visualization, select your profiling group in the [CodeGuru Profiler console](https://console.aws.amazon.com/codeguru/profiler/), navigate to the **Heap usage** panel, and select **Visualize heap**.

## Total capacity


This shows the maximum heap size configured for the JVM. If your application’s used space reaches this value then you may run out of memory. This value is equal to your JVM’s Xmx value (if configured). 

## Used space


This shows how much heap space your application requires to store all objects required in memory after a garbage collection cycle. If this value continuously grows over time until it reaches total capacity, then that could be an indication of a memory leak. If this value is very low compared to total capacity, then you may be able to save money by reducing your system’s memory.

![\[Image: Heap summary visualization.\]](http://docs.aws.amazon.com/codeguru/latest/profiler-ug/images/heap-summary.png)


## Heap summary table


The **Heap summary** table shows information about the object types consuming the most heap space in your application. The size of each type only accounts for the shallow memory requirement of that type, and does not include the size of objects referenced by objects of that type. Values are averaged across all hosts reporting data at the same time.

Only object types that consume more than 0.5% (by default) of your heap’s total capacity across all objects are detected. Object types with consumption below that threshold are counted as part of the used capacity value, and are not shown individually in the table.

Object types that are below that threshold for at least one data point are shown with an **Incomplete data** badge. The values shown are only averages of the data available, and do not include time periods during which the object type size was lower than the 0.5% capacity threshold.

**Object types**
+ The **Average usage by type** shows how much heap space your application requires to store all objects required in memory after a garbage collection cycle. If this value continuously grows over time until it reaches total capacity, it could indicate a memory leak. If this value is very low compared to total capacity, then you may be able to save money by reducing your system’s memory.
+ The **Average number of objects** indicates the average number of objects of this type on the heap during the time period.
+ Use the **my code** namespace (if configured) to categorize the type into one of several categories. The **my code** namespace can be configured in the **Actions** dropdown list at the top of the page. The table of object types can be filtered based on this code type.

# Comparing two time ranges


The CodeGuru Profiler **Compare** option allows you to view differences between two different time ranges of the same profiling group. It can be used for overview, hotspots, and inspect visualizations. This feature is not available for the heap summary visualization.

**To enable the compare visualization**

1. Choose **Compare**.

1. Set **B** to be the time to which you want to compare to your current visualization.

1. Choose **Apply**.

If you'd like to change the time range comparison, choose **Change B**.

These comparisons are visualized by color. Functions that take more time in one time range appear more prominently as the color of the corresponding time range. Less saturated colors indicate a smaller difference between the two time ranges. A very light or white color indicates little to no difference between the time ranges.

![\[Image: Diff visualization.\]](http://docs.aws.amazon.com/codeguru/latest/profiler-ug/images/diff-visualization.png)


In this example, the two time ranges are A (green) and B (purple). The visualization allows you to pinpoint the areas in darker violet that indicate the function took more time in time range B. Similarly, the darker green indicates functions spending more time in time range A. The more faded sections of the visualization indicate a similar amount of time was taken by the function in both time ranges.

## Understanding the comparison


You can see more information about a function if you pause over it. In the following example, you can see the CPU cost reduced betwen the first time range and the second.

**Note**  
It's normal to see changes in your profiling data without any code changes. The profiling data may vary depending on when and how your application runs. Keep in mind your application characteristics when selecting a comparison time range. For example, you might find interesting profiling data if you compare data from your current time range with the data from a week earlier.

![\[Image: Diff visualization.\]](http://docs.aws.amazon.com/codeguru/latest/profiler-ug/images/diff-visualization-2.png)