1 /* Copyright 2017 The TensorFlow Authors. All Rights Reserved. 2 3 Licensed under the Apache License, Version 2.0 (the "License"); 4 you may not use this file except in compliance with the License. 5 You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14 ==============================================================================*/ 15 16 #ifndef TENSORFLOW_COMPILER_XLA_METRIC_TABLE_REPORT_H_ 17 #define TENSORFLOW_COMPILER_XLA_METRIC_TABLE_REPORT_H_ 18 19 #include <vector> 20 21 #include "absl/strings/str_cat.h" 22 #include "tensorflow/compiler/xla/util.h" 23 24 namespace xla { 25 26 // Class for creating a text format table showing entries with a metric 27 // (e.g. cycles) and a text (e.g. name of function taking that many 28 // cycles). Entries are grouped by a category and sorted in decreasing order of 29 // the metric. 30 // 31 // Example of a categories table generated using this class: 32 // 33 // ********** microseconds report ********** 34 // There are 3,912,517 microseconds in total. 35 // There are 123 microseconds ( 0.00%) not accounted for by the data. 36 // There are 3002 ops. 37 // 38 // ********** categories table ********** 39 // The left hand side numbers are microseconds. 40 // 1,749,414 (44.71% Σ44.72%) convolution (206 ops) 41 // * 10.51% %convolution.202 42 // * 10.51% %convolution.204 43 // * 10.51% %convolution.203 44 // * ... (203 more ops) 45 // 884,939 (22.62% Σ67.33%) convolution window-dilated (7 ops) 46 // * 7.50% %convolution-window-dilated.7 47 // [...] 48 // 49 // The entry table is similar, it just has the entries directly as the entries 50 // instead of grouping by categories first. 51 class MetricTableReport { 52 public: 53 // Represents an entry in the table. 54 struct Entry { 55 // Text to show in the entry table for this entry. 56 string text; 57 58 // Text to show in the category table for this entry. 59 string short_text; 60 61 // Text that represents the category of this entry - entries with the same 62 // category are grouped together in the category table. 63 string category_text; 64 65 // The value of the metric for this entry. 66 double metric = 0.0; 67 }; 68 69 void AddEntry(Entry entry); 70 71 // The default name for the metric is "units", this function allows setting a 72 // more meaningful name. 73 void SetMetricName(string metric_name); 74 75 // The default name for referring to entries is "entries", this functions 76 // allows setting a more meaningful name. 77 void SetEntryName(string entry_name); 78 79 // By default the size of the table is limited. Calling this function forces 80 // all entries to be shown no matter how many there are. 81 void SetShowAllEntries(); 82 83 // Set option to show a table with data on the categories of entries. 84 void SetShowCategoryTable(); 85 86 // Set option to show a table with data on the entries. 87 void SetShowEntryTable(); 88 89 // Returns the report as a string. expected_metric_sum is the expected sum of 90 // the metric across the entries. It is not an error for the actual sum to be 91 // different from the expectation - the report will include the 92 // discrepancy. All metric percentages are for the ratio with respect to the 93 // expected sum, not the actual sum. 94 string MakeReport(double expected_metric_sum); 95 96 // As MakeReport(), but writes the report to the INFO log in a way that avoids 97 // cutting the report off if it is longer than the maximum line length for a 98 // logged line. Individual lines in the report may still be cut off, but they 99 // would have to be very long for that to happen. 100 void WriteReportToInfoLog(double expected_metric_sum); 101 102 private: 103 static constexpr double kDefaultMaxMetricProportionToShow = 0.99; 104 static constexpr int64 kDefaultMaxEntriesToShow = 100; 105 static constexpr int64 kDefaultMaxEntriesPerCategoryToShow = 5; 106 107 // Append all parameters to the report. 108 template <typename... Args> AppendLine(Args...args)109 void AppendLine(Args... args) { 110 absl::StrAppend(&report_, std::forward<Args>(args)..., "\n"); 111 } 112 113 // Represents a set of entries with the same category_text. 114 struct Category { 115 string category_text; 116 double metric_sum = 0.0; // Sum of metric across entries. 117 std::vector<const Entry*> entries; 118 }; 119 120 // Returns a vector of categories of entries with the same category_text. The 121 // vector is sorted in order of decreasing metric sum. 122 // 123 // The returned categories contain pointers into the entries parameter. The 124 // style guide requires parameters to which references/pointers are retained 125 // to be taken by pointer, even for const parameters, so that is why entries 126 // is taken by pointer. 127 static std::vector<Category> MakeCategories( 128 const std::vector<Entry>* entries); 129 130 // Append a header to the report. 131 void AppendHeader(); 132 133 // Append a table of categories to the report. 134 void AppendCategoryTable(); 135 136 // Append a table of entries to the report. 137 void AppendEntryTable(); 138 139 // Appends a row of a table to the report. 140 void AppendTableRow(const string& text, const double metric, 141 const double running_metric_sum); 142 143 // Returns the discrepancy between the expected sum of the metric of the 144 // entries and the actual sum. 145 double UnaccountedMetric(); 146 147 // Formats the metric value as a string. 148 string MetricString(double metric); 149 150 // Returns a string representing the metric value as a proportion of the 151 // expected metric sum. 152 string MetricPercent(double metric); 153 154 // The entries to make a report about. 155 std::vector<Entry> entries_; 156 157 double expected_metric_sum_ = 0.0; 158 string metric_name_ = "units"; 159 string entry_name_ = "entries"; 160 bool show_category_table_ = false; 161 bool show_entry_table_ = false; 162 163 // These members control how many categories and entries to show in tables. 164 int64 max_entries_to_show_ = kDefaultMaxEntriesToShow; 165 int64 max_entries_per_category_to_show_ = kDefaultMaxEntriesPerCategoryToShow; 166 double max_metric_proportion_to_show_ = kDefaultMaxMetricProportionToShow; 167 168 // The report that is being created. 169 string report_; 170 }; 171 172 } // namespace xla 173 174 #endif // TENSORFLOW_COMPILER_XLA_METRIC_TABLE_REPORT_H_ 175