The Stackdriver Profiler interface provides a graph and a set of controls that let you analyze the data collected by the profiling agent. This page provides an introduction to the Profiler interface. More advanced information is contained in the Filtering profiles and Comparing profiles pages.
Before you start
Before you can use the Profiler to analyze data, you must have some profiling data collected to analyze. For information on using the Profiler agent to collect profiling data, see:
- Profiling Go code
- Profiling Java code
- Profiling Node.js code
- Profiling Python code
- Profiling code outside Google Cloud Platform
Opening the Profiler interface
To use the Profiler interface:
In the Google Cloud Platform Console, select your project:
In the left-hand navigation panel, scroll to Stackdriver and then click Profiler:
The Profiler interface contains a collection of controls and a flame graph. This section explains how to read and interpret the graph. The Profiler controls section describes how to manipulate the graph.
The flame graph is composed of frames. Each frame represents a function in the service:
The width of a frame corresponds to its consumption of the metric being analyzed. The top frame, for example, represents the entire service and consumes 100% of the metric being analyzed. Therefore, this frame is shown as full width.
By default, the frame color corresponds, where possible, to the function's package. If package information is unavailable, as with Node.js, the names of the source files are used to color the function blocks. In a call stack, a change in block color means a transition from one package to another. You can change change the way the frames are colored. For more information, see Color mode.
The flame graph shows one or more call stacks with the values averaged over a set of profiles:
- Each individual profile represents data collected one time per minute from a single instance of the configured service in a single Compute Engine zone. The collection period for a profile varies with the profile type. See Profile collection for more information.
- A maximum of 250 profiles are averaged. If there are more than 250 profiles available, 250 of them are selected randomly as a sample set.
- The top frame, or "root", in a flame graph represents the entire service. Under the "root" frame, is another frame or set of frames making up the second row in the graph. Each of these color-coded frames is a top-level call made by the service. Under each of those colored function frames is another set of function frames, each of which is responsible for some part of the resource of the frame above it. The hierarchy of function frames in the graph represents the call sequence, and the width of a frame represents that function or method's contribution to the resource consumption.
For example, the profiler graph of the consumed heap for the
shows that the service calls three different top-level frames, one
of them is the Go runtime's
main function. The width of these three
top-level frames show the majority of the heap is consumed by the call stack
involving Go runtime's
This section describes the Profiler interface controls. You use these controls to determine the information displayed in the profiler graph.
When you hold the pointer over a frame in the flame graph, a dialog opens that displays additional information about the frame:
- Function name
- Source file location
- Metric consumption information
In the metric consumption information, the prefix total indicates that the metric-value and percentage are for a function and its children. In contrast, the prefix self indicates the metric-value and percentage are for the function with the consumption of its children excluded.
The dialog also includes buttons for three filtering actions:
- Show from frame
- Show stacks
For details on these filtering options, see Filtering profiles.
In this example, the tooltip shows that the
is located in the
/usr/local/go/src/runtime/proc.go file. The
metric consumption information shows that
runtime.main and its children
55.28 MiB of
memory, or about 91% of the total memory consumed by the program.
Range of time
You control the period of time for which profiling data is displayed with the Timespan menu, Now button, and End time menu. By default, Timespan is 7 days, the Now button is enabled, and the End time corresponds to the current time. With the default settings, the Profiler analyzes profiles captured in the previous 7 days.
To set the timespan, click the Timespan down arrow, and then select an option from the list. Your choices range from 10 minutes to 30 days, the limit of the retention period for profile data.
To set a specific end time:
- To enable the End time field, click Now.
In the End time field, enter a date and time, or use the calendar option to select a date:
To reset the end time to the current time, click Now.
Use the Service menu to select the service whose data you want to analyze. The service name is one of the values you (or the runtime environment) specify when you run an application with profiling enabled. For more information on service names, see the profiling guides for Go, Java, Node.js, or Python.
Use the Profile type menu to select the type of profiling data to analyze. Different languages support a different set of profile types:
1 For App Engine standard environment, Go 1.11 or later is required. 2 Only available for App Engine standard environment. 3 Not available for App Engine standard environment. 4 Only available for Python 3.2 and higher. 5 Only available for Python 3.6 and higher.
Each profile type captures a different kind of information:
- CPU time: information about CPU usage
- Heap: information about memory consumption
- Contention: information about mutex usage
- Threads: information about thread usage
- Wall time: information about total time to run
To restrict the analysis to instances of the service running in a specific Compute Engine zone, click the Zone down arrow, and then select the zone from the list.
The default setting for this field is All zones.
To restrict the analysis to a specific version of the named service, click the Version down arrow, and then select the version of interest. The service version is an optional value you (or the runtime environment) specify when an application is run with profiling enabled. For more information on service versions, see the profiling guides for Go, Java, Node.js, or Python.
The default setting for this field is All versions.
To visually compare two profiles of the same type, taken from the same service with a project, use the Compare To feature; for more information, see Comparing profiles.
The default setting for this field is None.
To focus the flame graph on a specific function, click List Focusing the graph., which is located to the left of the filter bar, and then select the function from the Select focus function table. When you focus the frame graph on a function, the graph displays all code paths that flow into, and out of, that function. For examples, see
Focusing the flame graph on a function is optional.
You choose which data in the selected set of profiles to display with filters. The filter syntax is:
[FILTER-OPTION] : [VALUE]
FILTER-OPTION is a predefined filter option and
user-defined. The frame matches the value when the frame function name
VALUE. A case-sensitive comparison is performed.
For example, if
oo, then frames with functions named
The filters you select are displayed in the filter bar.
Metric filter is required and one is automatically added for you.
VALUE is based on your choice for profile type.
Depending on your profile type,
you might be able to modify the
VALUE of your
For example, if you select the profile type as Heap, then a
filter with the
Bytes is added:
You can add a filter in different ways:
- Click Filters , select an option from the list, and then enter the value.
- Click the gray text Add profile data filter in the filter bar, and then enter the filter option and value.
- For the Focus, Show from frame, and Show stacks filter options, you can also place your pointer on the frame, and then select the option from the frame tooltip.
For more information on the filtering options and examples, see the Filtering profiles page.
Stackdriver Profiler keeps your profile data for 30 days, but you can download the data for longer-term storage or for other reasons. When you click download, Profiler writes a compressed file to your local file system. The file name is:
SERVICE_NAMEcontains your Service selection
PROFILE_TYPEcontains your Profile type selection
TO_DATEcontains your time-range specifications
ZONEcontains your Zone selection
VERSIONcontains your Version selection
The data is written in the serialized protocol
.pb) format. The open-source
tool can read this format, so you can analyze this data, not just store it.
pprof documentation for more information.