Using the new custom reporting features in Performance Advisor

Users of Performance Advisor can create custom reports which allow them to tailor the data they see in their report to their exact requirements. In the latest release of Arm Streamline, part of Arm Performance Studio 2024.0, we have introduced several new features to custom reporting. These changes allow you a finer degree of control over what you can see in your reports.

Note: this content assumes a working knowledge of Performance Advisor, and its existing custom reporting features. The existing features are still present. You can still make custom reports this way if required.

The new format

The most notable addition to custom reporting is the ability to specify series to show on a particular chart. Previously in a custom report, you could choose any chart from Streamline and have this displayed in PA. However, this meant the Performance Advisor chart contained every series from the Streamline chart. Now, you can include specific series from any chart you like by identifying them by their corresponding expression name. The expression name is found in the chart configuration panel in Streamline

To build a custom report, create a JSON file which can be named and located as you wish. You will need to include this file later when generating the performance report. Below is an example of a custom report, featuring a chart titled “GPU cycles per frame” defined in the new format:

{
    "groups": [
        {
            "title": "Group 1",
            "charts": [
                {
                    "id": "gpuUsagePerFrame",
                    "title": "GPU cycles per frame",
                    "series": [
                        {
                            "title": "GPU cycles",
                            "expression": "$MaliGPUCyclesGPUActive"
                        },
                        {
                            "title": "Fragment cycles",
                            "expression": "$MaliGPUCyclesFragmentQueueActive"
                        },
                        {
                            "title": "Non-fragment cycles",
                            "expression": "$MaliGPUCyclesNonFragmentQueueActive"
                        }
                    ],
                    "description": "This chart shows GPU cycles per frame.",
                    "units": "Cycles"
                }
            ]
        }
    ]
} 

If you are familiar with the old layout of custom report files, you can see the layout is largely the same. Parameters such as “description” and “units” are unchanged. However, instead of defining a chart from its name in Streamline, you can pass an array of series defined by their corresponding expression. The series also has a title, which is shown on the axis of the chart in the report. Both the “expression” and “title” properties must be included. Because you are now able to provide individual series directly to charts, you are no longer limited to showing entire existing charts from Streamline. You can now create a custom PA chart featuring series from multiple Streamline charts. Allowing you to group data together as you see fit.

Arithmetic operations on series data

The Streamline expression language used by Performance Advisor can understand some basic arithmetic, including:

• Addition ( + operator)
• Subtraction ( - operator)
• Multiplication ( * operator)
• Division ( / operator)
• Maximum (max(val 1, val2))
• Minimum (min(val 1, val2))

This means you can perform operations on data similarly to how Performance Advisor does in its "standard" charts. This allows an even greater degree of control over the data you show.

Example:

We have a capture of an application made on a device with a Mali-G71 GPU. We want to see a chart showing the number of shader cycles per shader core count per frame. We will easily create a custom chart to show this.

First, we would need to find each of the cycles we are interested in in Streamline, in this example these would be:

• Execution engine cycles, found in the “Mali ALU Instructions” chart under the “Executed Instructions” series.
• Load/Store Cycles, found in the “Mali Load/Store Usage” chart in the “Load/Store unit issue” series.
• Varying Cycles, found in the “Mali Varying Unit Issues” chart as a combination of the “16-bit interpolation issues” series and the “32-bit interpolation issues series”
• Texture Cycles, found in the “Mali Texture Unit Cycles” chart in the series “Filtering active”

Once we have the series we wish to show, we copy its corresponding expression from the expression box in the Streamline chart's configuration panel:

Once we have these expressions, we can make this data per shader core count by using $MaliConstantsShaderCoreCount and dividing our counter expressions by it in our series definition.

Now we would create a chart element in our custom report JSON file and add the counter expressions and the division arithmetic:

                { 
                    "id": "shaderCoreBifrostPerFrame", 
                    "title": "Shader cycles per frame", 
                    "series": [ 
                        { 
                            "title": "Execution engine cycles", 
                            "expression": "($MaliALUInstructionsExecutedInstructions) / $MaliConstantsShaderCoreCount" 
                        }, 
                        { 
                            "title": "Load/store cycles", 
                            "expression": "($MaliLoadStoreUnitCyclesFullRead + $MaliLoadStoreUnitCyclesPartialRead + $MaliLoadStoreUnitCyclesFullWrite + $MaliLoadStoreUnitCyclesPartialWrite + $MaliLoadStoreUnitCyclesAtomicAccess) / $MaliConstantsShaderCoreCount" 
                        }, 
                        { 
                            "title": "Varying Cycles", 
                            "expression": "(($MaliVaryingUnitIssues16BitInterpolationIssues) + ($MaliVaryingUnitIssues32BitInterpolationIssues)) / $MaliConstantsShaderCoreCount" 
                        }, 
                        { 
                            "title": "Texture cycles", 
                            "expression": "($MaliTextureUnitCyclesFilteringActive) / $MaliConstantsShaderCoreCount"
                        } 
                    ], 
                    "description": "This chart shows the absolute number of shader cycles per frame for each pipeline.",
                    "units": "Cycles"
                } 

Then, when we generate the report, we include our custom report with –custom-report=<path to custom report JSON file>
We would get an output chart like this:

Important notes:

• These expression names, like the chart and series names in a Streamline capture, can vary depending on:
  • Which device and CPU/GPU the capture was taken on
  • Which version of Streamline/Gator the capture was created with
• It is important to make sure the expressions you use in your report match those in the Streamline capture.  
• Performance Advisor is version matched with Gator and Streamline, so attempting to generate a report from a capture made with a different version may have issues with finding series as the expressions can change.  

Additional parameters

The series object in the custom report has a few more optional parameters that can be set for specific cases.  

• Performance Advisor scales all its data to be per frame where possible, if the data you are trying to show is already per frame, such as the Draw Calls per Frame chart, you need to specify that it is already per frame with the pair “isPerFrame”: “true” 
• You can set the series data to be displayed as average, maximum or minimum by setting isAverage, isMax or isMin respectively to be “true” 
• If you have data that can often be zero and are not interested in displaying the series on the chart it if it is, you can set the pair “doNotShowIfAllZeroes”: “true” 

Here is an example of a chart with some of the additional parameters:

                {
                    "id": "drawCallsPerFrame",
                    "title": "Draw calls per frame",
                    "series": [
                        {
                            "title": "Draw calls",
                            "expression": "$DrawCallsFrameVkDevice0xe7438000",
                            "isMax": "true",
                            "isPerFrame": "true"
                        }
                    ],
                    "description": "This chart shows the draw calls per frame.",
                    "units": "Draw calls"
                }

In summary

With these additions, you now have much more control over the charts you can create in a Performance Advisor report. If you like what you have seen here, please try it out and let us know what you think. To learn more about Performance Advisor, please refer to the user guide.

Download Arm Performance Studio