Add a new package: measure

.gitignore

@@ -14,3 +14,6 @@ GeneratedPluginRegistrant.m
 
 GeneratedPluginRegistrant.java
 
+packages/measure/result.json
+*instrumentscli*.trace
+

packages/measure/CHANGELOG.md

@@ -0,0 +1,4 @@
+## 0.1.0
+
+* Initial release.
+

packages/measure/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2019 The Chromium Authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google Inc. nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

packages/measure/README.md

@@ -0,0 +1,31 @@
+# Install
+
+Make sure that `pub` is on your path. Then run:
+```shell
+pub global activate measure
+```
+
+# Run
+First, make sure that `dart` and `flutter` is available in your command line.
+
+Then, connect a **single** iPhone, run a Flutter app on it, and
+```shell
+# assuming that you're in this directory
+measure ioscpugpu new -u resources/TraceUtility -t resources/CpuGpuTemplate.tracetemplate
+```
+
+It currently outputs something like
+```
+gpu: 12.4%, cpu: 22.525%
+```
+
+Eventually, we'd like to hook this up to our CI system to continuously monitor
+Flutter's CPU/GPU usages, which can be used to infer the energy usage.
+
+For more information, try
+```shell
+measure help
+measure help ioscpugpu
+measure help ioscpugpu new
+measure help ioscpugpu parse
+```

packages/measure/bin/measure.dart

@@ -0,0 +1,16 @@
+// Copyright 2019 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:args/command_runner.dart';
+
+import 'package:measure/commands/ioscpugpu.dart';
+
+void main(List<String> args) {
+  final CommandRunner<void> runner = CommandRunner<void>(
+    'measure',
+    'Tools for measuring some performance metrics.',
+  );
+  runner.addCommand(IosCpuGpu());
+  runner.run(args);
+}

packages/measure/lib/commands/base.dart

@@ -0,0 +1,63 @@
+// Copyright 2019 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:args/command_runner.dart';
+import 'package:meta/meta.dart';
+
+const String kOptionTimeLimitMs = 'time-limit-ms';
+const String kOptionTemplate = 'template';
+const String kOptionDevice = 'device';
+const String kOptionProessName = 'process-name';
+const String kOptionTraceUtility = 'trace-utility';
+const String kOptionOutJson = 'out-json';
+const String kFlagVerbose = 'verbose';
+
+const String kDefaultProccessName = 'Runner';  // Flutter app's default process
+
+abstract class BaseCommand extends Command<void> {
+  BaseCommand() {
+    argParser.addFlag(kFlagVerbose);
+    argParser.addOption(
+      kOptionOutJson,
+      abbr: 'o',
+      help: 'json file for the measure result.',
+      defaultsTo: 'result.json',
+    );
+  }
+
+  @protected
+  void checkRequiredOption(String option) {
+    if (argResults[option] == null) {
+      throw Exception('Option $option is required.');
+    }
+  }
+
+  @protected
+  bool get isVerbose => argResults[kFlagVerbose];
+  @protected
+  String get outJson => argResults[kOptionOutJson];
+}
+
+abstract class IosCpuGpuSubcommand extends BaseCommand {
+  IosCpuGpuSubcommand() {
+    argParser.addOption(
+      kOptionTraceUtility,
+      abbr: 'u',
+      help:
+        'path to TraceUtility binary (https://github.com/Qusic/TraceUtility)',
+    );
+    argParser.addOption(
+      kOptionProessName,
+      abbr: 'p',
+      help:
+        'the process name used for filtering the instruments CPU measurements',
+      defaultsTo: kDefaultProccessName,
+    );
+  }
+
+  @protected
+  String get traceUtility => argResults[kOptionTraceUtility];
+  @protected
+  String get processName => argResults[kOptionProessName];
+}

packages/measure/lib/commands/ioscpugpu.dart

@@ -0,0 +1,20 @@
+// Copyright 2019 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:args/command_runner.dart';
+import 'package:measure/commands/ioscpugpu/new.dart';
+import 'package:measure/commands/ioscpugpu/parse.dart';
+
+class IosCpuGpu extends Command<void> {
+  IosCpuGpu() {
+    addSubcommand(IosCpuGpuNew());
+    addSubcommand(IosCpuGpuParse());
+  }
+
+  @override
+  String get name => 'ioscpugpu';
+  @override
+  String get description => 'Measure the iOS CPU/GPU percentage.';
+}
+

packages/measure/lib/commands/ioscpugpu/new.dart

@@ -0,0 +1,117 @@
+// Copyright 2019 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:async';
+import 'dart:io';
+
+import 'package:measure/commands/base.dart';
+import 'package:measure/parser.dart';
+
+class IosCpuGpuNew extends IosCpuGpuSubcommand {
+  IosCpuGpuNew() {
+    argParser.addOption(
+      kOptionTimeLimitMs,
+      abbr: 'l',
+      defaultsTo: '5000',
+      help: 'time limit (in ms) to run instruments for measuring',
+    );
+    argParser.addOption(
+      kOptionTemplate,
+      abbr: 't',
+      help: 'instruments template'
+    );
+    argParser.addOption(
+      kOptionDevice,
+      abbr: 'w',
+      help: 'device identifier recognizable by instruments '
+            '(e.g., 00008020-000364CE0AF8003A)',
+    );
+  }
+
+  @override
+  String get name => 'new';
+  @override
+  String get description => 'Take a new measurement on the iOS CPU/GPU '
+                            'percentage (of Flutter Runner).';
+
+  String get _timeLimit => argResults[kOptionTimeLimitMs];
+
+  @override
+  Future<void> run() async {
+    checkRequiredOption(kOptionTemplate);
+    checkRequiredOption(kOptionTraceUtility);
+    _checkDevice();
+
+    print('Running instruments on iOS device $_device for ${_timeLimit}ms');
+
+    final List<String> args = <String>[
+      '-l', _timeLimit,
+      '-t', argResults[kOptionTemplate],
+      '-w', _device,
+    ];
+    if (isVerbose) {
+      print('instruments args: $args');
+    }
+    final ProcessResult processResult = Process.runSync('instruments', args);
+    _parseTraceFilename(processResult.stdout.toString());
+
+    print('Parsing $_traceFilename');
+
+    final CpuGpuResult result =
+        IosTraceParser(isVerbose, traceUtility).parseCpuGpu(_traceFilename, processName);
+    result.writeToJsonFile(outJson);
+    print('$result\nThe result has been written into $outJson');
+  }
+  String _traceFilename;
+  Future<void> _parseTraceFilename(String out) async {
+    const String kPrefix = 'Instruments Trace Complete: ';
+    final int prefixIndex = out.indexOf(kPrefix);
+    if (prefixIndex == -1) {
+      throw Exception('Failed to parse instruments output:\n$out');
+    }
+    _traceFilename = out.substring(prefixIndex + kPrefix.length).trim();
+  }
+
+  String _device;
+  void _checkDevice() {
+    _device = argResults[kOptionDevice];
+    if (_device == null) {
+      final ProcessResult result = Process.runSync('flutter', <String>['devices']);
+      if (result.stdout.toString().contains('1 connected device')) {
+        final List<String> lines = result.stdout.toString().split('\n');
+        const String kSeparator = '•';
+        for (String line in lines) {
+          if (line.contains(kSeparator)) {
+            final int left = line.indexOf(kSeparator);
+            final int right = line.indexOf(kSeparator, left + 1);
+            _device = line.substring(left + 1, right).trim();
+          }
+        }
+        if (_device == null) {
+          print('Failed to parse `flutter devices` output:\n ${result.stdout}');
+        }
+      } else {
+        print('''
+Option device is not provided, and `flutter devices` returns either 0 or more
+than 1 devices, or errored.
+
+stdout of `flutter devices`:
+===========================
+${result.stdout}
+===========================
+
+stderr of `flutter devices`:
+===========================
+${result.stderr}
+===========================
+'''
+        );
+      }
+    }
+
+    if (_device == null) {
+      throw Exception('Failed to determine the device.');
+    }
+  }
+}

packages/measure/lib/commands/ioscpugpu/parse.dart

@@ -0,0 +1,39 @@
+// Copyright 2019 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:async';
+
+import 'package:measure/commands/base.dart';
+import 'package:measure/parser.dart';
+
+class IosCpuGpuParse extends IosCpuGpuSubcommand {
+  @override
+  String get name => 'parse';
+  @override
+  String get description =>
+      'parse an existing instruments trace with CPU/GPU measurements.';
+
+  @override
+  String get usage {
+    final List<String> lines = super.usage.split('\n');
+    lines[0] = 'Usage: measure ioscpugpu -u <trace-utility-path> '
+               'parse <trace-file-path>';
+    return lines.join('\n');
+  }
+
+  @override
+  Future<void> run() async {
+    checkRequiredOption(kOptionTraceUtility);
+    if (argResults.rest.length != 1) {
+      print(usage);
+      throw Exception('exactly one argument <trace-file-path> expected');
+    }
+    final String path = argResults.rest[0];
+
+    final CpuGpuResult result =
+        IosTraceParser(isVerbose, traceUtility).parseCpuGpu(path, processName);
+    result.writeToJsonFile(outJson);
+    print('$result\nThe result has been written into $outJson');
+  }
+}