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:

  1. Download the Android source.

  2. Navigate to the Winscope folder:

    cd development/tools/winscope

  3. Install dependencies using:

    npm install

    To see a list of available commands, run: npm run

  4. Build all prod and test targets using:

    npm run build:prod

  5. 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:

  1. Build :framework-minus-apex-intdefs for the annotation preprocessor to run:

    mp :framework-minus-apex-intdefs

  2. 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

  3. 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.

  • 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.