diff --git a/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/_index.md b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/_index.md new file mode 100644 index 0000000000..e16d18365c --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/_index.md @@ -0,0 +1,68 @@ +--- +title: Use Arm Performix Agentic Dynamic Insights from VS Code with Codex + +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. + +minutes_to_complete: 20 + +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. + +learning_objectives: + - Configure the Arm Performix MCP server in the Codex extension for VS Code. + - Check that the assistant can see Arm Performix recipes and runs. + - Ask the assistant to list available Arm Performix runs. + - Generate AI Insights for a supported code hotspots run. + - Use the result to decide where to inspect or optimize next. + +prerequisites: + - Arm Performix version 2026.2.5 or later installed. Refer to the [Install Guide](https://learn.arm.com/install-guides/performix/) for instructions. + - Visual Studio Code installed with the Codex extension. + - Permission to use your organization-approved AI assistant with profile data, symbols, source excerpts, disassembly excerpts, and performance metrics. + - For remote Linux targets, configure key-based SSH access before using the Arm Performix MCP server. + - If you connect to your target as a non-root user, some recipes or target configurations might require passwordless sudo. + - Make sure your SSH known_hosts file contains the target host key. + - If your target configuration uses jump nodes, make sure known_hosts also contains the host key for each jump node. + +author: + - Julie Gaskin + +### Tags +skilllevels: Beginner +subjects: Performance and Architecture +armips: + - Neoverse +operatingsystems: + - Linux +tools_software_languages: + - Arm Performix + - C++ + - GCC + +further_reading: + - resource: + title: Install guide + link: https://learn.arm.com/install-guides/performix + type: documentation + - resource: + title: User guide + link: https://developer.arm.com/documentation/110163/latest/ + type: documentation + - resource: + title: Code hotspots learning path + link: https://learn.arm.com/learning-paths/servers-and-cloud-computing/cpu_hotspot_performix + type: learning path + - resource: + title: CPU microarchitecture learning path + link: https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-microarchitecture + type: learning path + - resource: + title: Migrating applications to Arm servers + link: https://learn.arm.com/learning-paths/servers-and-cloud-computing/migration/ + type: learning path + +### FIXED, DO NOT MODIFY +# ================================================================================ +weight: 1 # _index.md always has weight of 1 to order correctly +layout: "learningpathall" # All files under learning paths have this same wrapper +learning_path_main_page: "yes" # This should be surfaced when looking for related content. Only set for _index.md of learning path content. +--- diff --git a/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/_next-steps.md b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/_next-steps.md new file mode 100644 index 0000000000..c3db0de5a2 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/_next-steps.md @@ -0,0 +1,8 @@ +--- +# ================================================================================ +# FIXED, DO NOT MODIFY THIS FILE +# ================================================================================ +weight: 21 # Set to always be larger than the content in this path to be at the end of the navigation. +title: "Next Steps" # Always the same, html page title. +layout: "learningpathall" # All files under learning paths have this same wrapper for Hugo processing. +--- diff --git a/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/configure_mcp_codex.md b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/configure_mcp_codex.md new file mode 100644 index 0000000000..7f511a2870 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/configure_mcp_codex.md @@ -0,0 +1,100 @@ +--- +title: Configure the Arm Performix MCP server in Codex + +weight: 3 + +layout: learningpathall +--- +There are 3 ways to configure the MCP server: + +- Through VS Code's GUI +- Through the Codex CLI +- By editing the Codex configuration file: `~/.codex/config.toml`. + +## Configure the MCP server through VS Code + +Use the following procedure in Visual Studio Code: + +1. Open Visual Studio Code and open the Codex sidebar. +2. Open Codex settings. +3. In the Codex Settings tab, select MCP servers. +4. Click + Add server. +5. In the Name field, enter a name such as arm-performix. +6. In the Command to launch field, enter the path to the Arm Performix `apx` executable. + Default paths include: + + ``` + /Applications/Arm Performix.app/Contents/assets/apx/apx + + /opt/Arm Performix/assets/apx/apx + ``` + + On Windows, the default installation directory depends on whether Arm Performix was installed for one user or all users: + + ``` + C:\Users\\AppData\Local\Programs\Arm Performix + + C:\Program Files\Arm Performix + ``` + +7. In the Arguments field, add: + + ``` + mcp + start + ``` + +8. Click **Save** and restart the Codex extension. + +## Configure the MCP server using Codex CLI + +Alternatively, you can use Codex's CLI to add an MCP server. Replace `` with the path to the `apx` executable on your system. If the path contains spaces, put the path in double quotation marks. + +``` +codex mcp add arm-performix -- "" mcp start +``` + +For example, on macOS: + +``` +codex mcp add arm-performix -- "/Applications/Arm Performix.app/Contents/assets/apx/apx" mcp start +``` + +## Configure the MCP server in the Codex configuration file + +You can also configure the MCP server by editing the Codex configuration file directly. + +1. Open this file in a text editor: `~/.codex/config.toml` + +2. Add a server entry: + + ``` + [mcp_servers.arm-performix] + + command = "/Applications/Arm Performix.app/Contents/assets/apx/apx" + + args = ["mcp", "start"] + ``` + +3. Replace the command value with the path to the apx executable on your system. +4. Save the file and restart the Codex extension. + +## Check that the MCP server is connected + +Before generating insights, ask Codex to confirm that it can see Arm Performix data: + +``` +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. +``` + +If the assistant lists Arm Performix recipes or runs, the MCP server is connected. + +To narrow the result, include a workload name, recipe, or time period: + +``` +Show me a list of Arm Performix runs for which AI insights are available. +``` + +Review the returned runs and identify the run you want to analyze. Note the run name or run ID. + +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. diff --git a/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/create_a_code_hotspots_run.md b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/create_a_code_hotspots_run.md new file mode 100644 index 0000000000..1dfa6488db --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/create_a_code_hotspots_run.md @@ -0,0 +1,45 @@ +--- +title: Create a Code Hotspots run + +weight: 4 + +layout: learningpathall +--- +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. + +First, ask the assistant to list the configured targets: + +``` +List the available Arm Performix targets +``` + +Choose the target that should run your workload, then ask the assistant to run Code Hotspots and generate insights from the result: + +``` +Run the Code Hotspots recipe on the target named "" with this workload: "". +When the run completes, generate AI insights for that run. Suggest where I should start investigating next. +``` + +Replace: + +- `` with the Performix target name returned by the assistant. + +- `` with the command that starts your workload on the target. + +For example: + +``` +Run the Code Hotspots recipe on the target named "graviton-dev" with this workload: "/opt/myapp/bin/my_app --input /data/input.dat". +``` + +The assistant uses the Arm Performix MCP server to prepare the target, run the Code Hotspots recipe. + +If you prefer to run the profile manually, use the Performix CLI: + +``` +apx recipe ready code_hotspots --target my-target --workload "/opt/myapp/bin/my_app --input /data/input.dat" + +apx recipe run code_hotspots --target my-target --workload "/opt/myapp/bin/my_app --input /data/input.dat" --timeout 30 +``` + +Use `--timeout` for unattended profiling so the run ends automatically. If you are profiling an already-running process, use `--pid` instead of `--workload`. diff --git a/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/generate_AI_insights.md b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/generate_AI_insights.md new file mode 100644 index 0000000000..2a8ef96b92 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/generate_AI_insights.md @@ -0,0 +1,57 @@ +--- +title: Generate AI insights + +weight: 5 + +layout: learningpathall +--- + +## Generate AI insights for the latest run + +If you want to start with the most recent supported run, use: + +``` +Generate AI insights for the last profiling run. Suggest where I should start investigating next. +``` + +The assistant should call the Arm Performix MCP server, gather relevant run data, and return an evidence-based summary. + +## Generate AI insights for a specific run + +If you want to choose the run first, ask for the list of supported runs, then follow up with: + +``` +Generate AI insights for the run named "". +``` + +Replace `` with the run name or ID returned by the assistant. + +If you are investigating a specific function, make the request more focused: + +``` +Use Arm Performix to explain why function is hot in run . Use profile evidence from the run. +``` + +Focused prompts usually produce more useful results than broad application-wide prompts. + +## Use the Agentic workflow for iteration + +Once you trust the diagnosis, you can ask follow-up questions: + +``` +Which evidence in the Performix run supports that recommendation? + +What is the first optimization I should try, and why? + +Suggest a minimal code change to test this hypothesis. +``` + +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: + +1. Modify the code. +2. Rebuild the workload. +3. Run it on the target. +4. Profile again with Arm Performix. +5. Compare the new run with the previous run. + +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. diff --git a/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/open-in-performix.md b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/open-in-performix.md new file mode 100644 index 0000000000..55ce3076b8 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/open-in-performix.md @@ -0,0 +1,21 @@ +--- +title: Open the run in Arm Performix for deeper inspection + +weight: 6 + +layout: learningpathall +--- +The chat response is useful for triage, but Arm Performix remains the best place to explore rich profile views. + +After receiving an insight, open the same run in Arm Performix and inspect: + +1. the flame graph, +2. the hottest functions, +3. source-line annotations, +4. disassembly, +5. call paths, +6. comparison data if you have before/after runs. + +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. + +You can watch a [video on how to get started with Arm Performix](https://youtu.be/_eX8ZpNT0kc?si=WrQg5daHxUc0MFbR). diff --git a/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/overview.md b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/overview.md new file mode 100644 index 0000000000..f11b104fb0 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/overview.md @@ -0,0 +1,27 @@ +--- +title: Overview + +weight: 2 + +layout: learningpathall +--- +[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. + +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. + +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. + +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. + +## How it works + +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. + +When you ask for insights, the flow is: + +1. You ask an AI assistant in VS Code for Arm Performix insights. +2. The assistant calls the Arm Performix MCP server. +3. Arm Performix gathers relevant run data and profile evidence. +4. The assistant uses that evidence to identify likely bottlenecks, explain why they matter, and suggest next steps. +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. + diff --git a/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/troubleshooting.md b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/troubleshooting.md new file mode 100644 index 0000000000..928aa5938c --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/troubleshooting.md @@ -0,0 +1,89 @@ +--- +title: Troubleshooting + +weight: 7 + +layout: learningpathall +--- +Here are some solutions to common problems you may face when using this workflow. + +## The Codex extension does not show the Arm Performix MCP server + +Use Codex's `mcp list` subcommand to check if Codex has picked up the MCP server and what settings are present: + +``` +codex mcp list +Name Command Args +arm-performix /Applications/Arm Performix.app/Contents/assets/apx/apx mcp start +``` + +If this is correct, check: + +1. the `apx` command path is correct, +2. the arguments are `mcp` and `start`, +3. the server name is configured in Codex settings or `~/.codex/config.toml`, +4. you restarted the Codex extension after saving the configuration, +5. you are editing the Codex configuration for the same user account that runs VS Code. + +## The MCP server fails to start + +Common causes include: + +1. incorrect Arm Performix executable path, +2. missing execute permission, +3. incompatible Arm Performix version, +4. missing license or environment setup, +5. server started on the wrong machine when using remote development, +6. SSH target configuration that does not satisfy Arm Performix requirements. + +## The Assistant does not use Arm Performix + +Try a more explicit prompt: + +``` +Use the Arm Performix MCP server to list the available Arm Performix runs. +``` + +Or: + +``` +Use Arm Performix to generate AI Insights for the run named "". +``` + +If you have many MCP servers installed, ambiguous prompts such as give me insights might cause the assistant to choose a different tool. + +## No supported runs are found + +Check: + +1. you have created at least one supported Code Hotspots run, +2. the MCP server is running as the same user who created the run, +3. the run exists in the same Arm Performix data location used by the GUI and CLI, +4. the run has enough profile data, symbols, source, or disassembly to support useful analysis, +5. you are not connected to a remote VS Code environment that has a different home directory or Arm Performix configuration. + +## Remote target authentication fails + +Check: + +1. SSH key-based authentication is configured, +2. passwordless sudo is configured if your recipe or target setup requires it, +3. strict host-key checking can succeed, +4. your known_hosts file contains the target SSH host key, +5. your known_hosts file contains each jump-node host key, if jump nodes are used. + +## The insight is too generic + +Try narrowing the request: + +``` +Focus on the highest-impact finding in run "" and explain the evidence. +``` + +Or: + +``` +Explain whether appears to be limited by scalar code, memory traffic, locking, allocation, or call overhead. Use evidence from the Performix run. +``` + +The more specific the question, the easier it is for the assistant to use high-signal profile evidence.