# Telemetry Solution (Topdown Methodology) ## About this Install Guide | Reading time: | 10 min | |---------------|---------| | Last updated: | 22 Jun 2026 | | Author: | Jason Andrews, Arm [GitHub](https://github.com/jasonrandrews) [LinkedIn](https://linkedin.com/in/jason-andrews-7b05a8) | |----------|--------------------------------------------------------------------------------------------------| | Official docs: | [View](https://gitlab.arm.com/telemetry-solution/telemetry-solution) | This guide shows you how to install and use the tool with the most common configuration. For advanced options and complete reference information, see the official documentation. Some install guides also include optional next steps to help you explore related workflows or integrations. The Arm Telemetry Solution provides tools and data for performance analysis. The Arm Topdown Methodology specifies a set of metrics and steps to measure them using the Telemetry Solution. The Telemetry Solution requires Linux Perf to collect metrics. The Telemetry Solution also includes data for defining PMU events, a test suite to stress CPU resources, and a tool to parse Statistical Profiling Extension (SPE) data for analysis. ## What do I need before installing the Telemetry Solution? Follow the instructions below to install the Telemetry Solution on an Arm Linux system. 1. Confirm you are using an Arm machine by running: ```bash uname -m ``` The output should be: ```bash __output__ aarch64 ``` If you see a different result, you are not using an Arm computer running 64-bit Linux. 2. Install Perf Install Perf using the [Perf for Linux on Arm install guide](/install-guides/perf/). 3. Install Python 3 and pip Python 3.7 or later and pip are required. Install these on your Linux distribution. For Debian based distributions (including Ubuntu) run: ```bash sudo apt update sudo apt install python-is-python3 python3-pip python3-venv python3-packaging linux-tools-generic linux-tools-$(uname -r) -y ``` ## How do I install the Telemetry Solution? 1. Clone the repository: ```bash git clone https://git.gitlab.arm.com/telemetry-solution/telemetry-solution.git ``` 2. Install the `topdown-tool` executable: Create a virtual environment for the installation. ```bash python -m venv topdown-venv source topdown-venv/bin/activate ``` Install `topdown-tool` in `/usr/local/bin`: ```bash cd telemetry-solution/tools/topdown_tool pip install -e . ``` 3. Confirm you can run `top-down` using the `version` command: ```bash topdown-tool --help ``` The output will be similar to: ```bash __output__ usage: topdown-tool [-h] [--all-cpus] [--pid PIDS] [--perf-path PERF_PATH] [--perf-args PERF_ARGS] [--cpu CPU] __output__ [--list-cpus] [--list-groups] [--list-metrics] [-c {none,metric,group}] __output__ [--max-events MAX_EVENTS] [-m METRIC_GROUPS] [-n NODE] [-s STAGES] [-i INTERVAL] __output__ [--use-event-names] [-d] [--show-sample-events] [--perf-output PERF_OUTPUT] [--csv CSV] [-v] __output__ [--debug] __output__ ... __output__ positional arguments: __output__ command command to analyse. Subsequent arguments are passed as program arguments. e.g. "sleep 10" __output__ options: __output__ -h, --help show this help message and exit __output__ --all-cpus, -a System-wide collection for all CPUs. __output__ --pid PIDS, -p PIDS comma separated list of process IDs to monitor. __output__ --perf-path PERF_PATH path to perf executable __output__ --perf-args PERF_ARGS additional command line arguments to pass to Perf __output__ --cpu CPU CPU name to use to look up event data (auto-detect by default) __output__ -i INTERVAL, -I INTERVAL, --interval INTERVAL Collect/output data every milliseconds __output__ query options: __output__ --list-cpus list available CPUs and exit __output__ --list-groups list available metric groups and exit __output__ --list-metrics list available metrics and exit __output__ collection options: __output__ -c {none,metric,group}, --collect-by {none,metric,group} when multiplexing, collect events grouped by "none", "metric" (default), or "group". This can avoid comparing data collected during different time periods. __output__ --max-events MAX_EVENTS Maximum simultaneous events. If more events are required, will be run multiple times. __output__ -m METRIC_GROUPS, --metric-group METRIC_GROUPS comma separated list of metric groups to collect. See --list-groups for available groups __output__ -n NODE, --node NODE name of topdown node as well as its descendants (e.g. "frontend_bound"). See --list-metrics for available nodes __output__ -s STAGES, --stages STAGES control which stages to display, separated by a comma. e.g. "topdown,uarch". "all" may also be specified, or "combined" to display all, but without separate the output in to stages. __output__ --use-event-names use event names rather than event codes (e.g. "r01") when collecting data from perf. This can be useful for debugging. __output__ output options: __output__ -d, --descriptions show group/metric descriptions __output__ --show-sample-events show sample events for metrics __output__ --perf-output PERF_OUTPUT output file for perf event data __output__ --csv CSV output file for metric CSV data __output__ -v, --verbose enable verbose output __output__ --debug enable debug output ``` ## How do I test the Telemetry Solution? > Note > You may need to enable access to the counters. More information about the options is in the [Linux Perf install guide](/install-guides/perf/). ```bash sudo sh -c "echo -1 > /proc/sys/kernel/perf_event_paranoid" sudo sh -c "echo 0 > /proc/sys/kernel/kptr_restrict" ``` Confirm `topdown-tool` is able to collect events: ```bash topdown-tool -m Cycle_Accounting -a sleep 5 ``` The output is similar to: ```bash __output__ Stage 1 (Topdown metrics) __output__ ========================= __output__ [Cycle Accounting] __output__ Frontend Stalled Cycles 57.67% cycles __output__ Backend Stalled Cycles. 21.06% cycles ``` > Note > If you encounter the error `Could not detect CPU. Specify via --cpu`, you can check what CPUs are available, and pass it to the command. ```bash topdown-tool --list-cpus topdown-tool --cpu -m Cycle_Accounting -a sleep 5 ``` Your output may be different, but if values are printed you are ready to apply the Arm Top Down methodology.