[vm/tool] Add legend to snapshot_analysis compare/summary output.

Issue https://github.com/dart-lang/sdk/issues/41249

Change-Id: I9939ebc6bbebb32284dd55692d65482fc3ae3f2f
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/151387
Commit-Queue: Vyacheslav Egorov <vegorov@google.com>
Reviewed-by: Alexander Markov <alexmarkov@google.com>

pkg/vm/lib/snapshot/commands/compare.dart

@@ -14,6 +14,7 @@ import 'package:vm/snapshot/ascii_table.dart';
 
 import 'package:vm/snapshot/program_info.dart';
 import 'package:vm/snapshot/utils.dart';
+import 'package:vm/snapshot/v8_profile.dart';
 
 class CompareCommand extends Command<void> {
   @override
@@ -143,5 +144,9 @@ precisely based on their source position (which is included in their name).
     print('Old   : ${totalOld} bytes.');
     print('New   : ${totalNew} bytes.');
     print('Change: ${totalDiff > 0 ? '+' : ''}${totalDiff} bytes.');
+
+    if (oldSizes.snapshotInfo != null) {
+      print(bucketLegend);
+    }
   }
 }

pkg/vm/lib/snapshot/commands/summary.dart

@@ -15,6 +15,7 @@ import 'package:args/command_runner.dart';
 import 'package:vm/snapshot/ascii_table.dart';
 import 'package:vm/snapshot/program_info.dart';
 import 'package:vm/snapshot/utils.dart';
+import 'package:vm/snapshot/v8_profile.dart';
 
 class SummaryCommand extends Command<void> {
   @override
@@ -123,5 +124,7 @@ void outputSummary(File input,
         computeHistogram(info, HistogramType.byNodeType, filter: filter);
     printHistogram(info, typeHistogram,
         prefix: typeHistogram.bySize, maxWidth: maxWidth);
+
+    print(bucketLegend);
   }
 }

pkg/vm/lib/snapshot/v8_profile.dart

@@ -537,3 +537,28 @@ class _ProgramInfoBuilder {
     return pathA[i];
   }
 }
+
+final bucketLegend = '''
+
+--------------------------------------------------------------------------------
+IMPORTANT: Dart AOT snapshot is a serialized representation of Dart VM heap.
+Outside of few specific cases (e.g. an object representing a library clearly
+originates from the library it represents) there is no well defined relationship
+between snapshot bytes and a specific method/class/library to which these
+bytes can be attributed with certainty. This snapshot analysis tool tries
+to attribute bytes to specific program structure elements based on their
+reachability from objects with well defined origin - meaning that this analysis
+has some margin of error and imprecision.
+
+- @other bucket denotes bytes attributed to entities outside of the current
+granularity. For example, when breaking down the size by method name there
+might be bytes which exist outside of any specific symbol - in which case
+they will be attributed to @other.
+- @stubs bucket accumulates bytes attributed to stubs (pieces of machine code
+produced by the VM for internal purposes).
+- @shared bucket accumulates bytes shared between otherwise unrelated program
+entities
+- @unknown bucket accumulates bytes which are not reachable from any program
+structure nodes (usually VM internal objects).
+--------------------------------------------------------------------------------
+''';