vm_snapshot_analysis 0.4.0

  • Readme
  • Changelog
  • Installing
  • new72

vm_snapshot_analysis #

This package provides libraries and a utility for analysing the size and contents of Dart VM AOT snapshots based on the output of --print-instructions-sizes-to, --write-v8-snapshot-profile-to and --trace-precompiler-to VM flags.

AOT Snapshot Basics #

Dart VM AOT snapshot is simply a serialized representation of the Dart VM heap graph. It consists of two parts: data (e.g. strings, const instances, objects representing classes, libraries, functions and runtime metadata) and executable code (machine code generated from Dart sources). Some nodes in this graph have clean and direct relationship to the original program (e.g. objects representing libraries, classes, functions), while other nodes don't. Bitwise equivalent objects can be deduplicated and shared (e.g. two functions with the same body will end up using the same machine code object). This makes impossible to attribute of every single byte from the snapshot to a particular place in the program with a 100% accuracy.

  • --print-instructions-sizes-to attributes executable code from the snapshot to a particular Dart function (or internal stub) from which this code originated (ignoring deduplication). Executable code usually constitutes around half of the snapshot, those this varies depending on the application.
  • --write-v8-snapshot-profile-to is a graph representation of the snapshot, it attributes bytes written into a snapshot to a node in the heap graph. This format covers both data and code sections of the snapshot.
  • --trace-precompiler-to gives information about dependencies between compiled functions, allowing to determine why certain function was pulled into the snapshot.

Passing flags to the AOT compiler #

Both in dart2native and Flutter you can use --extra-gen-snapshot-options to pass flags to the AOT compiler:

$ flutter build aot --release --extra-gen-snapshot-options=--write-v8-snapshot-profile-to=profile.json

$ dart2native --extra-gen-snapshot-options=--write-v8-snapshot-profile-to=profile.json -o binary input.dart

Similarly with --print-instructions-sizes-to.

If you are working on the Dart SDK you can use the pkg/vm/tool/precompiler2 script, in which case you can just pass these flags directly:

$ pkg/vm/tool/precompiler2 --write-v8-snapshot-profile-to=profile.json input.dart binary

CLI #

The command line interface to the tools in this package is provided by a single entry point bin/analyse.dart. It consumes output of --print-instructions-sizes-to and --write-v8-snapshot-profile-to flags and presents it in different human readable ways.

This script can be installed globally as snapshot_analysis using

$ pub global activate vm_snapshot_analysis

snapshot_analysis supports the following subcommands:

summary #

$ snapshot_analysis summary [-b granularity] [-w filter] <input.json>

This command shows breakdown of snapshot bytes at the given granularity (e.g. method, class, library or package), filtered by the given substring filter.

For example, here is a output showing how many bytes from a snapshot can be attributed to classes in the dart:core library:

$ pkg/vm/bin/snapshot_analysis.dart summary -b class -w dart:core profile.json
+-----------+------------------------+--------------+---------+----------+
| Library   | Class                  | Size (Bytes) | Percent | Of total |
+-----------+------------------------+--------------+---------+----------+
| dart:core | _Uri                   |        43563 |  15.53% |    5.70% |
| dart:core | _StringBase            |        28831 |  10.28% |    3.77% |
| dart:core | ::                     |        27559 |   9.83% |    3.60% |
| @other    |                        |        25467 |   9.08% |    3.33% |
| dart:core | Uri                    |        14936 |   5.33% |    1.95% |
| dart:core | int                    |        12276 |   4.38% |    1.61% |
| dart:core | NoSuchMethodError      |        12222 |   4.36% |    1.60% |
...

Here objects which can be attributed to _Uri take 5.7% of the snapshot, at the same time objects which can be attributed to dart:core library but not to any specific class within this library take 3.33% of the snapshot.

This command also supports estimating cumulative impact of a library or a package together with its dependencies - which can be computed from a precompiler trace (--trace-precompiler-to options). For example:

$ snapshot_analysis summary -b package /tmp/profile.json
+-----------------------------+--------------+---------+
| Package                     | Size (Bytes) | Percent |
+-----------------------------+--------------+---------+
| package:compiler            |      5369933 |  38.93% |
| package:front_end           |      2644942 |  19.18% |
| package:kernel              |      1443568 |  10.47% |
| package:_fe_analyzer_shared |       944555 |   6.85% |
...
$ snapshot_analysis summary -b package -d 1 --precompiler-trace=/tmp/trace.json /tmp/profile.json
+------------------------------+--------------+---------+
| Package                      | Size (Bytes) | Percent |
+------------------------------+--------------+---------+
| package:compiler (+ 8 deps)  |      5762761 |  41.78% |
| package:front_end (+ 1 deps) |      2708981 |  19.64% |
| package:kernel               |      1443568 |  10.47% |
| package:_fe_analyzer_shared  |       944555 |   6.85% |
...
Dependency trees:

package:compiler (total 5762761 bytes)
├── package:js_ast (total 242490 bytes)
├── package:dart2js_info (total 101280 bytes)
├── package:crypto (total 27434 bytes)
│   ├── package:typed_data (total 11850 bytes)
│   └── package:convert (total 5185 bytes)
├── package:collection (total 15182 bytes)
├── package:_js_interop_checks (total 4627 bytes)
└── package:js_runtime (total 1815 bytes)

package:front_end (total 2708981 bytes)
└── package:package_config (total 64039 bytes)

compare #

$ snapshot_analysis compare [-b granularity] <old.json> <new.json>

This command shows comparison between two size profiles, allowing to understand changes to which part of the program contributed most to the change in the overall snapshot size.

$ pkg/vm/bin/snapshot_analysis.dart compare -b class old.json new.json
+------------------------+--------------------------+--------------+---------+
| Library                | Class                    | Diff (Bytes) | Percent |
+------------------------+--------------------------+--------------+---------+
| dart:core              | _SimpleUri               |        11519 |  22.34% |
| dart:core              | _Uri                     |         6563 |  12.73% |
| dart:io                | _RandomAccessFile        |         5337 |  10.35% |
| @other                 |                          |         4009 |   7.78% |
...

In this example 11519 more bytes can be attributed to _SimpleUri class in new.json compared to old.json.

treemap #

$ snapshot_analysis treemap [--format <format>] <input.json> <output-dir>
$ google-chrome <output-dir>/index.html

This command generates treemap representation of the information from the profile input.json and stores it in output-dir directory. Treemap can later be viewed by opening <output-dir>/index.html in the browser of your choice.

--format flag allows to control granularity of the output when input.json is a V8 snapshot profile, available options are:

  • collapsed essentially renders ProgramInfo as a treemap, individual snapshot nodes are ignored.
  • simplified same as collapsed, but also folds size information from nested functions into outermost function (e.g. top level function or a method) producing easy to consume output.
  • data-and-code collapses snapshot nodes based on whether they represent data or executable code.
  • object-type (default) collapses snapshot nodes based on their type only.

explain #

explain dynamic-calls

$ snapshot_analysis explain dynamic-calls <profile.json> <trace.json>

This command generates a report listing dynamically dispatched selectors and their approximate impact on the code size.

snapshot_analysis explain dynamic-calls /tmp/profile.json /tmp/trace.json
+------------------------------+--------------+---------+----------+
| Selector                     | Size (Bytes) | Percent | Of total |
+------------------------------+--------------+---------+----------+
| set:requestHeader            |        10054 |  28.00% |    0.03% |
| get:scale                    |         3630 |  10.11% |    0.01% |
...
Dynamic call to set:requestHeader (retaining ~10054 bytes) occurs in:
    package:my-super-app/src/injector.dart::Injector.handle{body}

Dynamic call to get:scale (retaining ~3630 bytes) occurs in:
    package:some-dependency/src/image.dart::Image.==

API #

This package can also be used as a building block for other packages which want to analyse VM AOT snapshots.

  • package:vm_snapshot_analysis/instruction_sizes.dart provides helpers to read output of --print-instructions-sizes-to=...
  • package:vm_snapshot_analysis/v8_profile.dart provides helpers to read output of --write-v8-snapshot-profile-to=...

Both formats can be converted into a ProgramInfo structure which attempts to breakdown snapshot size into hierarchical representation of the program structure which can be understood by a Dart developer, attributing bytes to packages, libraries, classes and functions.

  • package:vm_snapshot_analysis/utils.dart contains helper method loadProgramInfo which automatically detects format of the input JSON file and creates ProgramInfo in an appropriate way, allowing to write code which works in the same way with both formats.

Precompiler Trace Format (--write-precompiler-trace-to=...) #

AOT compiler can produce a JSON file containing information about compiled functions and dependencies between them. This file has the following structure:

{
    "trace": traceArray,
    "entities": entitiesArray,
    "strings": stringsArray,
}
  • stringsArray is an array of strings referenced by other parts of the trace by their index in this array.

  • entitiesArray is an flattened array of entities:

    • "C", <library-uri-idx>, <class-name-idx>, 0 - class record;
    • "V", <class-idx>, <name-idx>, 0 - static field record;
    • "F"|"S", <class-idx>, <name-idx>, <selector-id> - function record (F for dynamic functions and S for static functions);

    Note that all records in this array occupy the same amount of elements (4) to make random access by index possible.

  • traceArray is an flattened array of precompilation events:

    • "R" - root event (always the first element)
    • "E" - end event (always the last element)
    • "C", <function-idx> - function compilation event

    Root and function compilation events can additionally be followed by a sequence of references which enumerate outgoing dependencies discovered by the AOT compiler:

    • <entity-idx> - a reference to a function or a static field;
    • "S", <selector-idx> - a dynamic call with the given selector;
    • "T", <selector-id> - dispatch table call with the given selector id;

Flattened array is an array of records formed by consecutive elements: [R0_0, R0_1, R0_2, R1_0, R1_1, R1_2, ...] here R0_* is the first record and R1_* is the second record and so on.

Features and bugs #

Please file feature requests and bugs at the issue tracker.

Changelog #

0.4.0 #

  • Add buildComparisonTreemap for constructing treemap representing the diff between two size profiles.
  • Implemented support for extracting call graph information from the AOT compiler trace (--trace-precompiler-to flag), see precompiler_trace.dart.
  • New command explain dynamic-calls which estimates the impact of different dynamic calls on the resulting AOT snapshot size using information from the size dump (e.g. V8 snapshot profile) and AOT compiler trace.
  • summary command can now use information from the AOT compiler trace to group packages/libraries together with their dependencies to given more precise estimate of how much a specific package/library brings into the snapshot.

0.3.0 #

  • Extract treemap construction code into a separate library, to make it reusable.
  • Add ability to collapse leaf nodes in a treemap created from V8 snapshot profile. This behavior is programmatically controlled by TreemapFormat format parameter and from CLI via --format flag. The following options are available
    • collapsed essentially renders ProgramInfo as a treemap, individual snapshot nodes are ignored.
    • simplified same as collapsed, but also folds size information from nested functions into outermost function (e.g. top level function or a method) producing easy to consume output.
    • data-and-code collapses snapshot nodes based on whether they represent data or executable code.
    • object-type (default) collapses snapshot nodes based on their type only.
  • When computing ProgramInfo from a V8 snapshot profile no longer create ProgramInfoNode for Code nodes which are owned by a function - instead directly attribute the Code node itself and all retained nodes into ProgramInfoNode for the function itself. For stubs (including allocation stubs) create an artificial functionNode instead of using NodeType.other. The only remaining use of NodeType.other is for fields.

0.2.0 #

  • Update CLI help message to avoid referring to a snapshot created by pub as the name of the script.
  • Fix owner computation code for V8 profiles: the size of a snapshot node which corresponds to a ProgramInfoNode should be attributed to that ProgramInfoNode and not to its parent. For example Function node corresponds to ProgramInfoNode of type functionNode, previously the size of Function node would be attributed to the parent of this ProgramInfoNode, but it should be attributed to the node itself.
  • Update README.md to include more information on how to pass flags to Dart AOT compiler.
  • Add ProgramInfoNode.size documentation to clarify the meaning of the member.

0.1.0 #

  • Initial release

Use this package as an executable

1. Install it

You can install the package from the command line:


$ pub global activate vm_snapshot_analysis

2. Use it

The package has the following executables:


$ snapshot_analysis

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  vm_snapshot_analysis: ^0.4.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:vm_snapshot_analysis/ascii_table.dart';
import 'package:vm_snapshot_analysis/instruction_sizes.dart';
import 'package:vm_snapshot_analysis/name.dart';
import 'package:vm_snapshot_analysis/precompiler_trace.dart';
import 'package:vm_snapshot_analysis/program_info.dart';
import 'package:vm_snapshot_analysis/treemap.dart';
import 'package:vm_snapshot_analysis/utils.dart';
import 'package:vm_snapshot_analysis/v8_profile.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
55
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
72
Overall:
Weighted score of the above. [more]
72
Learn more about scoring.

We analyzed this package on Jul 6, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.13

Analysis suggestions

Package not compatible with runtime flutter-web on web

Because of the import of dart:io via the import chain package:vm_snapshot_analysis/precompiler_trace.dartpackage:vm_snapshot_analysis/utils.dartdart:io

Package not compatible with runtime web

Because of the import of dart:io via the import chain package:vm_snapshot_analysis/precompiler_trace.dartpackage:vm_snapshot_analysis/utils.dartdart:io

Health suggestions

Fix lib/precompiler_trace.dart. (-0.50 points)

Analysis of lib/precompiler_trace.dart reported 1 hint:

line 148 col 32: This function has a return type of 'CallGraphNode', but doesn't end with a return statement.

Format bin/analyse.dart.

Run dartfmt to format bin/analyse.dart.

Maintenance suggestions

The package description is too short. (-18 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and vm_snapshot_analysis.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.8.0 <3.0.0
args ^1.6.0 1.6.0
meta ^1.1.8 1.2.1
path ^1.7.0 1.7.0
Dev dependencies
pedantic ^1.9.0
test ^1.15.1