.. meta::
   :description: Neuron Explorer documentation for performance profiling, debugging, and optimization of ML workloads on AWS Trainium and Inferentia.
   :date-modified: 10/26/2026

.. _neuron-explorer-home:

Neuron Explorer
=================

Neuron Explorer is a suite of tools designed to support ML engineers throughout their development journey on AWS Trainium. Neuron Explorer helps developers maintain context, iterate efficiently, and focus on building and optimizing high-performance models. Developers can access Neuron Explorer from CLI, UI, or inside their IDE through VSCode integration.

Supported hardware
~~~~~~~~~~~~~~~~~~~

* AWS Trainium: trn1, trn2, trn3
* AWS Inferentia 2: inf2

Neuron Explorer is not supported on Inf1.

When to use Neuron Explorer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :widths: auto
   :header-rows: 1
   :align: left

   * - Scenario
     - Start with
   * - "My training step is slower than expected"
     - System profile — identify which phase (forward, backward, optimizer, communication) dominates
   * - "My model has low hardware utilization"
     - Device profile — see engine utilization, DMA activity, and idle time
   * - "Collective operations are slow"
     - Multi-worker system profile — compare timing across ranks
   * - "My NKI kernel is underperforming"
     - Device profile with source code linking — correlate instructions to kernel code
   * - "I need to compare before/after an optimization"
     - Capture both, view side-by-side in the summary viewer

Profiling Viewers
--------------------

Neuron Explorer enables ML performance engineers to trace execution from source code down to hardware operations, enabling detailed analysis of model behavior at every layer of the stack. The suite of tools supports both single-node and distributed applications, allowing developers to analyze workloads at scale. 

Getting Started
---------------

.. grid:: 1 2 2 2
   :gutter: 3

   .. grid-item-card:: Get Started
      :link: get-started
      :link-type: doc
      :class-card: sd-border-1

      Capture a profile of your Neuron workload, launch Neuron Explorer, and upload your profile for interactive analysis in the browser or VS Code.

   .. grid-item-card:: Capture Profiles
      :link: how-to-profile-workload
      :link-type: doc
      :class-card: sd-border-1

      Learn how to capture profiles using JAX, environment variables, or the CLI.

   .. grid-item-card:: Capture PyTorch Profiles
      :link: how-to-profile-pytorch
      :link-type: doc
      :class-card: sd-border-1

      Capture profiles from PyTorch workloads with ``torch.profiler`` and ``NeuronConfig``.

   .. grid-item-card:: UI Overview
      :link: overview-ui-tour
      :link-type: doc
      :class-card: sd-border-1

      Guided tour of every viewer and tool in Neuron Explorer, grouped by use case.

Visualization and Analysis
---------------------------

.. grid:: 1
   :gutter: 3

   .. grid-item-card:: Device Trace Viewer
      :link: overview-device-profiles
      :link-type: doc
      :class-card: sd-border-1

      Explore hardware-level execution with timeline view, operator table, event details, annotations, dependency highlighting, search, and more analysis features.

   .. grid-item-card:: System Trace Viewer
      :link: overview-system-profiles
      :link-type: doc
      :class-card: sd-border-1

      Explore system-level execution with timeline view and more analysis features.


.. grid:: 1 2 2 2
   :gutter: 3

   .. grid-item-card:: Hierarchy Viewer
      :link: overview-hierarchy-view
      :link-type: doc
      :class-card: sd-border-1

      Visualize the entire execution from model layers down to hardware execution, supporting interactivity with device viewer and source code linking.

   .. grid-item-card:: Source Code Viewer
      :link: how-to-link-view-source-code
      :link-type: doc
      :class-card: sd-border-1

      Navigate between NKI and PyTorch source code and profile data with bidirectional linking and highlighting.

   .. grid-item-card:: Summary Viewer
      :link: overview-summary-page
      :link-type: doc
      :class-card: sd-border-1

      Get streamlined performance insights and optimization recommendations with high-level metrics and visualizations.

   .. grid-item-card:: Tensor Viewer
      :link: overview-tensor-viewer
      :link-type: doc
      :class-card: sd-border-1

      Viewing tensor information including names, sizes, shapes, and memory usage details.

   .. grid-item-card:: Memory Viewer
      :link: overview-memory-viewer
      :link-type: doc
      :class-card: sd-border-1

      Analyze memory allocation, usage patterns, and potential inefficiencies across SBUF partitions.

   .. grid-item-card:: Region Highlighter
      :link: overview-region-highlighter
      :link-type: doc
      :class-card: sd-border-1

      Automatically identify optimization regions in your profiles based on collective operations, hierarchy data, and kernel stack frames.

Tutorials
----------

.. grid:: 1
   :gutter: 3

   .. grid-item-card:: Profile a NKI Kernel
      :link: /nki/guides/use-neuron-profile
      :link-type: doc
      :class-card: sd-border-1

      Learn how to profile a NKI kernel with Neuron Explorer.

.. grid:: 1 2 2 2
   :gutter: 3

   .. grid-item-card:: vLLM Performance
      :link: /tools/tutorials/performance-profiling-vllm
      :link-type: doc
      :class-card: sd-border-1

      Capture and analyze system-level and device-level profiles for vLLM inference workloads on Trainium.

   .. grid-item-card:: Profile Memory in torch-neuronx
      :link: /torch/guides/memory-profiling-guide
      :link-type: doc
      :class-card: sd-border-1

      Read memory statistics, inspect fragmentation, and record a memory snapshot in torch-neuronx, then open it in the Memory Viewer.


Additional Resources
--------------------

.. grid:: 1 2 2 2
   :gutter: 3

   .. grid-item-card:: Profile Files
      :link: profile-artifacts
      :link-type: doc
      :class-card: sd-border-1

      What each captured file (NEFF, NTFF, ``.pb``) contains, which files each profile type needs, and how files are named and paired.

   .. grid-item-card:: Environment Variables
      :link: environment-variables
      :link-type: doc
      :class-card: sd-border-1

      Which variables each capture method needs, what each variable does, and recommended combinations.

   .. grid-item-card:: Profile Parquet Schema Reference
      :link: profile-schema-reference
      :link-type: doc
      :class-card: sd-border-1

      Reference for profile output data tables and fields, matching ``neuron-explorer view --show-profile-schema``.

   .. grid-item-card:: Analyze Profile Output
      :link: how-to-analyze-profile-output
      :link-type: doc
      :class-card: sd-border-1

      Query the Parquet tables or export a timeline region to CSV.

.. _download-neuron-explorer-vscode:

Download Neuron Explorer for Visual Studio Code
------------------------------------------------

The Neuron Explorer VSCode extension is available on the Visual Studio Code Extension Marketplace.

To install the extension, open the Extensions view in VSCode by pressing **Ctrl+Shift+X** (Windows/Linux) or **CMD+Shift+X** (MacOS), and search for ``AWS Neuron Explorer``. Select the extension published by **Amazon Web Services** in the sidebar, then click the blue **Install** button.

.. _neuron-explorer-faq:

Neuron Explorer FAQ
-------------------

What can I expect from the Neuron Explorer?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Neuron Explorer provides a comprehensive profiling experience with both device-level and system-level profiling support. Neuron Explorer features an enhanced profiling experience with hierarchical profiling, bidirectional code linking, IDE integration, and more. In future releases, Neuron Explorer will continue to expand with additional profiling viewers and features, debugging capabilities, and enhanced recommendation and analysis tools to support the entire ML development journey on Trainium.

What is the difference between device-level and system-level profiling?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Device-level profiling captures hardware execution data from NeuronCores, including compute engine instructions, DMA operations, and hardware utilization. Use device-level profiling to analyze hardware performance, identify compute or memory bottlenecks, and optimize kernel implementations.

System-level profiling captures software execution data, including framework operations, Neuron Runtime API calls, CPU utilization, and memory usage. Use system-level profiling to analyze framework overhead, identify CPU bottlenecks, and debug runtime issues.

Is Neuron Explorer going to replace Neuron Profiler and Neuron Profiler 2.0?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Yes. Neuron Explorer is the recommended profiling tool and replaces both Neuron Profiler and Profiler 2.0.

Neuron Profiler and Profiler 2.0 reached end of support in the Neuron 2.29 release. They no longer receive updates or technical support, though they remain accessible through the ``neuron-profile`` package in earlier releases. Their user guides are preserved under :ref:`archived-neuron-profiler`. Migrate to Neuron Explorer.

Are my existing profiles compatible with Neuron Explorer?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Yes. Neuron Explorer is backwards compatible with profile data captured using Neuron Profiler or Profiler 2.0. Existing profile files must be reprocessed before viewing in Neuron Explorer, but you do not need to recapture them. See :ref:`new-neuron-profiler-setup`.

For detailed migration guidance, including CLI command mappings and feature comparisons, see the :doc:`migration-faq`.


.. toctree::
   :hidden:
   :maxdepth: 1

   Get Started <get-started>
   Capture Profiles <how-to-profile-workload>
   Capture PyTorch Profiles <how-to-profile-pytorch>
   UI Overview <overview-ui-tour>
   Device Trace Viewer <overview-device-profiles>
   System Trace Viewer <overview-system-profiles>
   Hierarchy Viewer <overview-hierarchy-view>
   Source Code Viewer <how-to-link-view-source-code>
   Summary Viewer <overview-summary-page>
   Tensor Viewer <overview-tensor-viewer>
   Memory Viewer <overview-memory-viewer>
   Region Highlighter <overview-region-highlighter>
   AI Recommendation Viewer <overview-ai-recommendations>
   Profile Parquet Schema Reference <profile-schema-reference>
   Analyze Profile Output <how-to-analyze-profile-output>
   View Profiles with Perfetto <view-perfetto>
   Neuron Profiler to Neuron Explorer Migration Guide <migration-faq>
   Troubleshooting & FAQs <troubleshooting>
   Profile Files <profile-artifacts>
   Environment Variables <environment-variables>
   Glossary <glossary>
   
