.. meta:: :description: Learn how to use source code linking in Neuron Explorer to understand code performance and optimize your applications :date-modified: 10/02/2026 .. _neuron-explorer-source-code: Source Code Viewer ==================== In this guide, you'll learn how to use Neuron Explorer's source code linking feature to visualize connections between your application code and device performance. Discover how to navigate between source code and device instructions, highlight performance-critical sections, view framework stack traces, and leverage interactive code decorations to optimize your AWS Neuron applications for maximum efficiency. Overview -------- Source code linking helps you understand how your code changes affect device performance and identify ways to optimize it. This feature creates interactive connections between source code files and other Neuron Explorer widgets. You can zoom to device instructions from selected code lines, navigate between instructions and source code, and highlight instructions for specific loop iterations. You can use source code linking in both the VS Code extension and standalone web application. This gives you flexibility for different developer workflows. The Framework Stack Trace feature shows up in the Event Details when an instruction on the device profile is clicked. This feature is used to map the device instructions back to framework level code in JAX or PyTorch to better understand what part of the application code resulted in a particular device instruction. For instructions generated by NKI kernels, the NKI Call Stack entry in Event Details extends this mapping from the framework level into the kernel. .. image:: /tools/images/view-link-1.gif Instructions ------------- Enabling Source Code Linking ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To enable tracking of the stack trace information for framework code, set these environment variables before compiling your NEFF: .. code-block:: bash export XLA_IR_DEBUG=1 export XLA_HLO_DEBUG=1 If you also want to enable source code linking for NKI source code (in addition to framework code), set the following environment variable before compiling: .. code-block:: bash export NKI_DEBUG_INFO=True This adds the "NKI Source Location" field and the NKI Call Stack to the profile, which allows Neuron Explorer to link device instructions back to your NKI kernel source code and show the chain of NKI function calls that produced each instruction. .. _neuron-explorer-nki-call-stack: Viewing the NKI Call Stack ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Selecting a NKI instruction in the Device Timeline shows the complete call chain from the NKI kernel function down to that instruction, under the NKI Call Stack entry in Event Details. This is the kernel-level counterpart to the Framework Stack Trace described in the Overview. The Framework Stack Trace stops at the framework operation that invoked the kernel; the NKI Call Stack continues through the NKI functions inside the kernel. When the same helper function is called from more than one site, the call stack identifies which call site produced the selected instruction. Viewing Source Code ~~~~~~~~~~~~~~~~~~~~ Once you have the NEFF, capture the profile using the environment variables above. When viewing the profile, you can optionally pass source root paths so that Neuron Explorer can display your code alongside the profile: - ``--framework-source-root`` — Path to your framework source files. Use this to link to your JAX or PyTorch application code. - ``--nki-source-root`` — Path to your NKI kernel source files. Use this to link to your NKI source code. Both flags are optional. You can use one, both, or neither depending on which source code you want to view. .. code-block:: bash # Link to framework source code only neuron-explorer view -n file.neff -s profile.ntff --framework-source-root /path/to/framework/source/files # Link to NKI source code only neuron-explorer view -n file.neff -s profile.ntff --nki-source-root /path/to/nki/source/files # Link to both framework and NKI source code neuron-explorer view -n file.neff -s profile.ntff --framework-source-root /path/to/framework/source/files --nki-source-root /path/to/nki/source/files Uploading source code in the web UI """"""""""""""""""""""""""""""""""" If you upload profiles through the **Upload Profile** dialog instead of the CLI, add your source files or folders in the **Source Code** section of the dialog. This section is separate from the profile upload and appears for both **Individual Files** and **Directory Upload**. Source files inside the profile directory are not picked up by **Directory Upload**; the Source Code Viewer stays empty unless the files are added in the **Source Code** section. Source Code Viewer ------------------- Highlighting Instructions ~~~~~~~~~~~~~~~~~~~~~~~~~~ Select source code lines to highlight their corresponding instructions in the profiler view. You can select individual lines or multiple lines through block selection or multiple cursors. .. image:: /tools/images/view-link-2.png Navigating to Source Code ~~~~~~~~~~~~~~~~~~~~~~~~~~ Cmd+click (macOS) or Ctrl+click (Windows/Linux) any instruction to jump to its location in source code. If there are multiple matches, you will be prompted to select which file to navigate to. .. image:: /tools/images/view-link-3.png Source Code Decorations ~~~~~~~~~~~~~~~~~~~~~~~~ Performance metrics appear as decorations directly in your source code, updating automatically with the instruction profiler's time range. Configure which metrics to display and in the settings panel. Currently only instruction count and PE element count are supported. .. image:: /tools/images/view-link-4.png Navigating to Instructions ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Select lines in your source code and navigate to their corresponding instructions using Ctrl+Shift+G, the context menu, or the "Zoom into Instructions" command from the command palette. The Device Trace Viewer will then zoom to show all instructions associated with your selection. .. image:: /tools/images/view-link-5.png Dependency Annotations ~~~~~~~~~~~~~~~~~~~~~~~ When enabled, selecting an instruction will highlight its dependent source code lines. The selected instruction's line will be highlighted in one color, with its dependencies shown in a different color. .. image:: /tools/images/view-link-6.png