Starting March 27, 2025, we recommend using android-latest-release instead of aosp-main to build and contribute to AOSP. For more information, see Changes to AOSP.

Run Winscope

Winscope tracing is part of the Android framework. This page outlines the steps required to download, build, and run the Winscope trace viewer locally.

Build Winscope locally

Follow these steps to set up your PC to run the Winscope tracer:

Download the Android source.
Navigate to the Winscope folder:
```
cd development/tools/winscope
```
Install dependencies using:
```
npm install
```
To see a list of available commands, run: npm run
Build all prod and test targets using:
```
npm run build:prod
```
Run Winscope using:
```
npm run start
```

Build separate parts

You can build individual parts of Winscope separately using the following commands:

Command	Description
`build:trace_processor`	Checks out and rebuilds the latest version of Perfetto's `trace_processor`.
`build:protos`	Recompiles the proto definitions.

Run tests

Winscope contains unit and end-to-end tests. To run them use npm run <command>:

Command	Description
`test:unit:ci`	Runs the unit tests in a less verbose format for CI or presubmit hook.
`test:unit:dev`	Runs the unit tests in a more verbose format for local development. This mode watches for changes and automatically reruns the correct tests.
`test:e2e`	Runs the end-to-end tests, such as those for the cross-tool protocol.
`test:presubmit:quiet`	Builds all presubmit unit tests, linters, and graph analysis in a less verbose format for CI or presubmit hook.
`test:presubmit`	Builds all presubmit unit tests, linters, and graph analysis in a more verbose format for local development.
`test:all`	Runs all tests (unit and end-to-end), linters, and graph analysis in a more verbose format for local development.

Update @IntDef mapping

@IntDef is an annotation used in Android to restrict the possible values of an integer. Winscope uses a mapping of these annotations to display the name of the value instead of the integer.

To update the @IntDef mapping, do the following:

Build :framework-minus-apex-intdefs for the annotation preprocessor to run:
```
mp :framework-minus-apex-intdefs
```

Copy the generated intDefMapping.json file to the prebuilts repository:

$ python3 -c 'import sys,json,collections; print(json.dumps(collections.OrderedDict(sorted(collections.ChainMap(*map(lambda x:json.load(open(x)), sys.argv[1:])).items())), indent=2))' $(find out/soong/.intermediates/frameworks/base -iname intDefMapping.json) > ./development/tools/winscope/src/common/intDefMapping.json

Upload the changes in Winscope using repo upload.

Other commands

In addition to build and tests, Winscope scripts contain other capabilities, as shown in the table. To run them use npm run command:

Command	Description
`format:check`	Checks for code formatting issues using `prettier`.
`format:fix`	Checks and auto fixes code formatting issues using `prettier`.
`eslint:check`	Checks for code formatting issues using `eslint`.
`eslint:fix`	Checks and auto fixes code formatting issues using `eslint`.
`tslint:check`	Checks for code formatting issues using `tslint`.
`tslint:fix`	Checks and auto fixes code formatting issues using `tslint`.
`deps_graph:check_cycles`	Analyzes the code for cyclical dependencies.

Troubleshoot

Use the following tips for troubleshooting:

Error ProtocolError: missing required '<FIELD>' or TypeError: Cannot read property '<PROP>' of null
- This occurs when the trace file was created with a new proto definition, containing new required fields.
  1. Make sure you're opening the trace on the correct Winscope version (master, S, or R).
  2. If you create the new field on the proto, recompile the protos in Winscope using npm run build:protos.
    
    Note: You shouldn't need a new required field, because the protos should be backward compatible.
Some installed dependency versions are wrong (build fails)
- Revert changes to package.json and package-lock.json. Remove node_modules. Run npm install again.
I added a new field to one of the proto files. How do I display it?
- Winscope uses the proto definitions from when it was compiled, so new fields won't appear by default. To show new fields, rebuild the protos using npm run build:protos.