src/bloaty.proto

// Copyright 2016 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto2";

package bloaty;

message Options {
  // The files to analyze.  At least one file must be provided.
  repeated string filename = 1;

  // If non-empty, we are in diff mode and these files should provide the
  // baseline.
  repeated string base_filename = 2;

  // Files to use for debug information.  We will match these to files from
  // filename or base_filename by build id.  Files that are only in
  // debug_filename will *not* have their file size counted.
  repeated string debug_filename = 10;

  // Link map files to assist symbol and compile unit parsing.
  // We will match these to files with the same base name / stem.
  // E.g. "foo.map" will be used to analyze the executable "foo".
  repeated string link_map_filename = 30;

  // If set, reads how frequently a range of bytes is accessed in CSV format.
  // The filter is in a sparse pattern format: assuming the frame size (see
  // access_pattern_frame_size) is 8 KiB, given a 24 KiB file and a `0:1,2:3`
  // pattern, it means that the first 8 KiB frame is accessed once, and the
  // third 8 KiB frame is accessed 3 times. The second 8 KiB frame is left
  // out, meaning it was never accessed. The frame indices in the pattern is not
  // guaranteed to be sorted. This option works together with the
  // `accesspattern` data source. When the `accesspattern` data source is the
  // first data source, the protobuf output format will only output items whose
  // region overlaps with a never-accessed frame.
  optional string cold_bytes_filter = 31;

  // If set, customizes how many bytes is in a frame as used by the pattern
  // in cold_bytes_filter.
  optional uint64 access_pattern_frame_size = 32 [default = 8192];

  // The data sources to scan in each file.  At least one data source must be
  // specified.  If more than one source is specified, the output is
  // hierarchical.
  //
  // These can be built-in data sources or custom data sources.
  repeated string data_source = 3;

  // The maximum number of rows to show at each level before collapsing the rest
  // into '[Other]'.
  optional int64 max_rows_per_level = 4 [default = 20];

  enum Demangle {
    DEMANGLE_SHORT = 0;
    DEMANGLE_FULL = 1;
    DEMANGLE_NONE = 2;
  }
  optional Demangle demangle = 5 [default = DEMANGLE_SHORT];

  // What to sort the output by.
  enum SortBy {
    SORTBY_BOTH = 0;
    SORTBY_VMSIZE = 1;
    SORTBY_FILESIZE = 2;
  }
  optional SortBy sort_by = 6 [default = SORTBY_BOTH];

  // When greater than zero, Bloaty will print verbose output to stdout.
  // TODO(haberman): should this be in the output object instead?
  optional int32 verbose_level = 7;

  // If set, these will print verbose information pertaining to the given
  // vm address and/or file offset.
  optional uint64 debug_vmaddr = 11;
  optional uint64 debug_fileoff = 12;

  // Custom data sources for this analysis.
  repeated CustomDataSource custom_data_source = 8;

  // Disassemble this function.
  optional string disassemble_function = 9;

  // Regex with which to filter names in the data sources.
  optional string source_filter = 13;

  // Dump raw memory map instead of printing normal output.
  optional bool dump_raw_map = 14;
}

// A custom data source allows users to create their own label space by
// rewriting a set of existing labels according to a set of regexes.
message CustomDataSource {
  // The name of this data source.
  optional string name = 1;

  // The underlying data source.  We will scan this data source and apply
  // rewrites to define the new data source.  This must be a built-in data
  // source, not another custom data source.
  optional string base_data_source = 2;

  // The rewrites that we will apply to the underlying labels to define the new
  // data source.
  repeated Regex rewrite = 3;
}

// For rewriting labels from a data source.  If the regex matches, then the
// entire string is replaced with the replacement.  Any groups captured from the
// pattern can be substituted into the replacement with \1, \2, etc. and \0
// refers to the entire match.
message Regex {
  optional string pattern = 1;
  optional string replacement = 2;
}