Skip to content

Commit 6963894

Browse files
pareenavermapareenaverma
authored
Merge pull request #3481 from juliegaskin/main
New learning path - Use Arm Performix Agentic Dynamic Insights from VS Code with Codex
2 parents 6397209 + 3763347 commit 6963894

8 files changed

Lines changed: 419 additions & 0 deletions

File tree

‎content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/_index.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
title: Use Arm Performix Agentic Dynamic Insights from VS Code with Codex
3+
4+
draft: true
5+
cascade:
6+
draft: true
7+
8+
description: This Learning Path shows how to configure the Arm Performix MCP server with the Codex extension in Visual Studio Code, then generate AI Insights for an existing Arm Performix profiling run.
9+
10+
minutes_to_complete: 20
11+
12+
who_is_this_for: This Learning Path is for software developers and performance engineers who want to optimize applications on Arm-based servers using Arm Performix.
13+
14+
learning_objectives:
15+
- Configure the Arm Performix MCP server in the Codex extension for VS Code.
16+
- Check that the assistant can see Arm Performix recipes and runs.
17+
- Ask the assistant to list available Arm Performix runs.
18+
- Generate AI Insights for a supported code hotspots run.
19+
- Use the result to decide where to inspect or optimize next.
20+
21+
prerequisites:
22+
- Arm Performix version 2026.2.5 or later installed. Refer to the [Install Guide](https://learn.arm.com/install-guides/performix/) for instructions.
23+
- Visual Studio Code installed with the Codex extension.
24+
- Permission to use your organization-approved AI assistant with profile data, symbols, source excerpts, disassembly excerpts, and performance metrics.
25+
- For remote Linux targets, configure key-based SSH access before using the Arm Performix MCP server.
26+
- If you connect to your target as a non-root user, some recipes or target configurations might require passwordless sudo.
27+
- Make sure your SSH known_hosts file contains the target host key.
28+
- If your target configuration uses jump nodes, make sure known_hosts also contains the host key for each jump node.
29+
30+
author:
31+
- Julie Gaskin
32+
33+
### Tags
34+
skilllevels: Introductory
35+
subjects: Performance and Architecture
36+
armips:
37+
- Neoverse
38+
operatingsystems:
39+
- Linux
40+
tools_software_languages:
41+
- Arm Performix
42+
- C++
43+
- GCC
44+
45+
further_reading:
46+
- resource:
47+
title: Install guide
48+
link: https://learn.arm.com/install-guides/performix
49+
type: documentation
50+
- resource:
51+
title: User guide
52+
link: https://developer.arm.com/documentation/110163/latest/
53+
type: documentation
54+
- resource:
55+
title: Code hotspots learning path
56+
link: https://learn.arm.com/learning-paths/servers-and-cloud-computing/cpu_hotspot_performix
57+
type: learning path
58+
- resource:
59+
title: CPU microarchitecture learning path
60+
link: https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-microarchitecture
61+
type: learning path
62+
- resource:
63+
title: Migrating applications to Arm servers
64+
link: https://learn.arm.com/learning-paths/servers-and-cloud-computing/migration/
65+
type: learning path
66+
67+
### FIXED, DO NOT MODIFY
68+
# ================================================================================
69+
weight: 1 # _index.md always has weight of 1 to order correctly
70+
layout: "learningpathall" # All files under learning paths have this same wrapper
71+
learning_path_main_page: "yes" # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
72+
---

‎content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/_next-steps.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
# ================================================================================
3+
# FIXED, DO NOT MODIFY THIS FILE
4+
# ================================================================================
5+
weight: 21 # Set to always be larger than the content in this path to be at the end of the navigation.
6+
title: "Next Steps" # Always the same, html page title.
7+
layout: "learningpathall" # All files under learning paths have this same wrapper for Hugo processing.
8+
---

‎content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/configure_mcp_codex.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: Configure the Arm Performix MCP server in Codex
3+
4+
weight: 3
5+
6+
layout: learningpathall
7+
---
8+
There are 3 ways to configure the MCP server:
9+
10+
- Through VS Code's GUI
11+
- Through the Codex CLI
12+
- By editing the Codex configuration file: `~/.codex/config.toml`.
13+
14+
## Configure the MCP server through VS Code
15+
16+
Use the following procedure in Visual Studio Code:
17+
18+
1. Open Visual Studio Code and open the Codex sidebar.
19+
2. Open Codex settings.
20+
3. In the Codex Settings tab, select MCP servers.
21+
4. Click + Add server.
22+
5. In the Name field, enter a name such as arm-performix.
23+
6. In the Command to launch field, enter the path to the Arm Performix `apx` executable.
24+
Default paths include:
25+
26+
```
27+
/Applications/Arm Performix.app/Contents/assets/apx/apx
28+
29+
/opt/Arm Performix/assets/apx/apx
30+
```
31+
32+
On Windows, the default installation directory depends on whether Arm Performix was installed for one user or all users:
33+
34+
```
35+
C:\Users\<username>\AppData\Local\Programs\Arm Performix
36+
37+
C:\Program Files\Arm Performix
38+
```
39+
40+
7. In the Arguments field, add:
41+
42+
```
43+
mcp
44+
start
45+
```
46+
47+
8. Click **Save** and restart the Codex extension.
48+
49+
## Configure the MCP server using Codex CLI
50+
51+
Alternatively, you can use Codex's CLI to add an MCP server. Replace `<path-to-apx>` with the path to the `apx` executable on your system. If the path contains spaces, put the path in double quotation marks.
52+
53+
```
54+
codex mcp add arm-performix -- "<path-to-apx>" mcp start
55+
```
56+
57+
For example, on macOS:
58+
59+
```
60+
codex mcp add arm-performix -- "/Applications/Arm Performix.app/Contents/assets/apx/apx" mcp start
61+
```
62+
63+
## Configure the MCP server in the Codex configuration file
64+
65+
You can also configure the MCP server by editing the Codex configuration file directly.
66+
67+
1. Open this file in a text editor: `~/.codex/config.toml`
68+
69+
2. Add a server entry:
70+
71+
```
72+
[mcp_servers.arm-performix]
73+
74+
command = "/Applications/Arm Performix.app/Contents/assets/apx/apx"
75+
76+
args = ["mcp", "start"]
77+
```
78+
79+
3. Replace the command value with the path to the apx executable on your system.
80+
4. Save the file and restart the Codex extension.
81+
82+
## Check that the MCP server is connected
83+
84+
Before generating insights, ask Codex to confirm that it can see Arm Performix data:
85+
86+
```
87+
List the available Arm Performix recipes and profiling runs. If no code hotspots runs are available, tell me that the MCP server is connected but there are no supported runs to analyze.
88+
```
89+
90+
If the assistant lists Arm Performix recipes or runs, the MCP server is connected.
91+
92+
To narrow the result, include a workload name, recipe, or time period:
93+
94+
```
95+
Show me a list of Arm Performix runs for which AI insights are available.
96+
```
97+
98+
Review the returned runs and identify the run you want to analyze. Note the run name or run ID.
99+
100+
If no supported Code Hotspots runs are available, you can create one from VS Code by asking the assistant to use the Arm Performix MCP server.

‎content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/create_a_code_hotspots_run.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: Create a Code Hotspots run
3+
4+
weight: 4
5+
6+
layout: learningpathall
7+
---
8+
If no supported Code Hotspots runs are available, you can create one from VS Code by asking the assistant to use the Arm Performix MCP server.
9+
10+
First, ask the assistant to list the configured targets:
11+
12+
```
13+
List the available Arm Performix targets
14+
```
15+
16+
Choose the target that should run your workload, then ask the assistant to run Code Hotspots and generate insights from the result:
17+
18+
```
19+
Run the Code Hotspots recipe on the target named "<target name>" with this workload: "<command>".
20+
When the run completes, generate AI insights for that run. Suggest where I should start investigating next.
21+
```
22+
23+
Replace:
24+
25+
- `<target name>` with the Performix target name returned by the assistant.
26+
27+
- `<command>` with the command that starts your workload on the target.
28+
29+
For example:
30+
31+
```
32+
Run the Code Hotspots recipe on the target named "graviton-dev" with this workload: "/opt/myapp/bin/my_app --input /data/input.dat".
33+
```
34+
35+
The assistant uses the Arm Performix MCP server to prepare the target, run the Code Hotspots recipe.
36+
37+
If you prefer to run the profile manually, use the Performix CLI:
38+
39+
```
40+
apx recipe ready code_hotspots --target my-target --workload "/opt/myapp/bin/my_app --input /data/input.dat"
41+
42+
apx recipe run code_hotspots --target my-target --workload "/opt/myapp/bin/my_app --input /data/input.dat" --timeout 30
43+
```
44+
45+
Use `--timeout` for unattended profiling so the run ends automatically. If you are profiling an already-running process, use `--pid` instead of `--workload`.

‎content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/generate_AI_insights.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: Generate AI insights
3+
4+
weight: 5
5+
6+
layout: learningpathall
7+
---
8+
9+
## Generate AI insights for the latest run
10+
11+
If you want to start with the most recent supported run, use:
12+
13+
```
14+
Generate AI insights for the last profiling run. Suggest where I should start investigating next.
15+
```
16+
17+
The assistant should call the Arm Performix MCP server, gather relevant run data, and return an evidence-based summary.
18+
19+
## Generate AI insights for a specific run
20+
21+
If you want to choose the run first, ask for the list of supported runs, then follow up with:
22+
23+
```
24+
Generate AI insights for the run named "<run ID>".
25+
```
26+
27+
Replace `<run ID>` with the run name or ID returned by the assistant.
28+
29+
If you are investigating a specific function, make the request more focused:
30+
31+
```
32+
Use Arm Performix to explain why function <function-name> is hot in run <run ID>. Use profile evidence from the run.
33+
```
34+
35+
Focused prompts usually produce more useful results than broad application-wide prompts.
36+
37+
## Use the Agentic workflow for iteration
38+
39+
Once you trust the diagnosis, you can ask follow-up questions:
40+
41+
```
42+
Which evidence in the Performix run supports that recommendation?
43+
44+
What is the first optimization I should try, and why?
45+
46+
Suggest a minimal code change to test this hypothesis.
47+
```
48+
49+
If your development environment also exposes build, deployment, remote execution, or source-control tools, the assistant may be able to help with a broader loop:
50+
51+
1. Modify the code.
52+
2. Rebuild the workload.
53+
3. Run it on the target.
54+
4. Profile again with Arm Performix.
55+
5. Compare the new run with the previous run.
56+
57+
The exact level of automation depends on the tools available in your VS Code environment and the Arm Performix MCP tools supported by your release.

‎content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/open-in-performix.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Open the run in Arm Performix for deeper inspection
3+
4+
weight: 6
5+
6+
layout: learningpathall
7+
---
8+
The chat response is useful for triage, but Arm Performix remains the best place to explore rich profile views.
9+
10+
After receiving an insight, open the same run in Arm Performix and inspect:
11+
12+
1. the flame graph,
13+
2. the hottest functions,
14+
3. source-line annotations,
15+
4. disassembly,
16+
5. call paths,
17+
6. comparison data if you have before/after runs.
18+
19+
Use the AI Insight to focus your investigation. For example, if the insight says a loop appears scalar, inspect the disassembly and compiler flags before changing the implementation.
20+
21+
You can watch a [video on how to get started with Arm Performix](https://youtu.be/_eX8ZpNT0kc?si=WrQg5daHxUc0MFbR).

‎content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/overview.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: Overview
3+
4+
weight: 2
5+
6+
layout: learningpathall
7+
---
8+
[Arm Performix](https://developer.arm.com/servers-and-cloud-computing/arm-performix) is a performance toolkit designed to help developers identify bottlenecks and validate improvements on Arm-based systems. It simplifies the process of turning low-level performance data into actionable insights through guided analysis paths called recipes. These recipes help you answer common performance questions and move quickly from observation to root cause.
9+
10+
Arm Performix can expose performance-analysis capabilities to an AI coding assistant through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). This lets you ask focused performance questions from your development environment while using Arm Performix profile data as the evidence behind the answer.
11+
12+
This tutorial shows how to configure the Arm Performix MCP server with the Codex extension in Visual Studio Code, then generate AI Insights for an existing Arm Performix profiling run.
13+
14+
Use AI-generated responses to support performance investigation. Validate important findings by reviewing the relevant data in Arm Performix and by rerunning the workload after making changes.
15+
16+
## How it works
17+
18+
Arm Performix stores profiling runs, target information and rendered analysis data. The Arm Performix MCP server exposes selected Arm Performix capabilities as tools that an MCP-compatible assistant can call.
19+
20+
When you ask for insights, the flow is:
21+
22+
1. You ask an AI assistant in VS Code for Arm Performix insights.
23+
2. The assistant calls the Arm Performix MCP server.
24+
3. Arm Performix gathers relevant run data and profile evidence.
25+
4. The assistant uses that evidence to identify likely bottlenecks, explain why they matter, and suggest next steps.
26+
The assistant does not need to infer everything from source code alone. It can use Arm Performix data as context, including information about runs, functions, call paths, source code, disassembly, or performance metrics, depending on what is available for the selected run.
27+

0 commit comments

Comments
 (0)