1 // Copyright 2015 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BASE_TRACE_EVENT_TRACE_CONFIG_H_ 6 #define BASE_TRACE_EVENT_TRACE_CONFIG_H_ 7 8 #include <stdint.h> 9 10 #include <string> 11 #include <vector> 12 13 #include "base/base_export.h" 14 #include "base/gtest_prod_util.h" 15 #include "base/trace_event/memory_dump_request_args.h" 16 #include "base/values.h" 17 18 namespace base { 19 namespace trace_event { 20 21 class ConvertableToTraceFormat; 22 23 // Options determines how the trace buffer stores data. 24 enum TraceRecordMode { 25 // Record until the trace buffer is full. 26 RECORD_UNTIL_FULL, 27 28 // Record until the user ends the trace. The trace buffer is a fixed size 29 // and we use it as a ring buffer during recording. 30 RECORD_CONTINUOUSLY, 31 32 // Record until the trace buffer is full, but with a huge buffer size. 33 RECORD_AS_MUCH_AS_POSSIBLE, 34 35 // Echo to console. Events are discarded. 36 ECHO_TO_CONSOLE, 37 }; 38 39 class BASE_EXPORT TraceConfig { 40 public: 41 typedef std::vector<std::string> StringList; 42 43 // Specifies the memory dump config for tracing. Used only when 44 // "memory-infra" category is enabled. 45 struct MemoryDumpTriggerConfig { 46 uint32_t periodic_interval_ms; 47 MemoryDumpLevelOfDetail level_of_detail; 48 }; 49 50 typedef std::vector<MemoryDumpTriggerConfig> MemoryDumpConfig; 51 52 TraceConfig(); 53 54 // Create TraceConfig object from category filter and trace options strings. 55 // 56 // |category_filter_string| is a comma-delimited list of category wildcards. 57 // A category can have an optional '-' prefix to make it an excluded category. 58 // All the same rules apply above, so for example, having both included and 59 // excluded categories in the same list would not be supported. 60 // 61 // Category filters can also be used to configure synthetic delays. 62 // 63 // |trace_options_string| is a comma-delimited list of trace options. 64 // Possible options are: "record-until-full", "record-continuously", 65 // "record-as-much-as-possible", "trace-to-console", "enable-sampling", 66 // "enable-systrace" and "enable-argument-filter". 67 // The first 4 options are trace recoding modes and hence 68 // mutually exclusive. If more than one trace recording modes appear in the 69 // options_string, the last one takes precedence. If none of the trace 70 // recording mode is specified, recording mode is RECORD_UNTIL_FULL. 71 // 72 // The trace option will first be reset to the default option 73 // (record_mode set to RECORD_UNTIL_FULL, enable_sampling, enable_systrace, 74 // and enable_argument_filter set to false) before options parsed from 75 // |trace_options_string| are applied on it. If |trace_options_string| is 76 // invalid, the final state of trace options is undefined. 77 // 78 // Example: TraceConfig("test_MyTest*", "record-until-full"); 79 // Example: TraceConfig("test_MyTest*,test_OtherStuff", 80 // "record-continuously, enable-sampling"); 81 // Example: TraceConfig("-excluded_category1,-excluded_category2", 82 // "record-until-full, trace-to-console"); 83 // would set ECHO_TO_CONSOLE as the recording mode. 84 // Example: TraceConfig("-*,webkit", ""); 85 // would disable everything but webkit; and use default options. 86 // Example: TraceConfig("-webkit", ""); 87 // would enable everything but webkit; and use default options. 88 // Example: TraceConfig("DELAY(gpu.PresentingFrame;16)", ""); 89 // would make swap buffers always take at least 16 ms; and use 90 // default options. 91 // Example: TraceConfig("DELAY(gpu.PresentingFrame;16;oneshot)", ""); 92 // would make swap buffers take at least 16 ms the first time it is 93 // called; and use default options. 94 // Example: TraceConfig("DELAY(gpu.PresentingFrame;16;alternating)", ""); 95 // would make swap buffers take at least 16 ms every other time it 96 // is called; and use default options. 97 TraceConfig(const std::string& category_filter_string, 98 const std::string& trace_options_string); 99 100 TraceConfig(const std::string& category_filter_string, 101 TraceRecordMode record_mode); 102 103 // Create TraceConfig object from the trace config string. 104 // 105 // |config_string| is a dictionary formatted as a JSON string, containing both 106 // category filters and trace options. 107 // 108 // Example: 109 // { 110 // "record_mode": "record-continuously", 111 // "enable_sampling": true, 112 // "enable_systrace": true, 113 // "enable_argument_filter": true, 114 // "included_categories": ["included", 115 // "inc_pattern*", 116 // "disabled-by-default-memory-infra"], 117 // "excluded_categories": ["excluded", "exc_pattern*"], 118 // "synthetic_delays": ["test.Delay1;16", "test.Delay2;32"] 119 // "memory_dump_config": { 120 // "triggers": [ 121 // { 122 // "mode": "detailed", 123 // "periodic_interval_ms": 2000 124 // } 125 // ] 126 // } 127 // } 128 // 129 // Note: memory_dump_config can be specified only if 130 // disabled-by-default-memory-infra category is enabled. 131 explicit TraceConfig(const std::string& config_string); 132 133 TraceConfig(const TraceConfig& tc); 134 135 ~TraceConfig(); 136 137 TraceConfig& operator=(const TraceConfig& rhs); 138 139 // Return a list of the synthetic delays specified in this category filter. 140 const StringList& GetSyntheticDelayValues() const; 141 GetTraceRecordMode()142 TraceRecordMode GetTraceRecordMode() const { return record_mode_; } IsSamplingEnabled()143 bool IsSamplingEnabled() const { return enable_sampling_; } IsSystraceEnabled()144 bool IsSystraceEnabled() const { return enable_systrace_; } IsArgumentFilterEnabled()145 bool IsArgumentFilterEnabled() const { return enable_argument_filter_; } 146 SetTraceRecordMode(TraceRecordMode mode)147 void SetTraceRecordMode(TraceRecordMode mode) { record_mode_ = mode; } EnableSampling()148 void EnableSampling() { enable_sampling_ = true; } EnableSystrace()149 void EnableSystrace() { enable_systrace_ = true; } EnableArgumentFilter()150 void EnableArgumentFilter() { enable_argument_filter_ = true; } 151 152 // Writes the string representation of the TraceConfig. The string is JSON 153 // formatted. 154 std::string ToString() const; 155 156 // Returns a scoped_refptr and wrap TraceConfig in ConvertableToTraceFormat 157 scoped_refptr<ConvertableToTraceFormat> AsConvertableToTraceFormat() const; 158 159 // Write the string representation of the CategoryFilter part. 160 std::string ToCategoryFilterString() const; 161 162 // Returns true if at least one category in the list is enabled by this 163 // trace config. 164 bool IsCategoryGroupEnabled(const char* category_group) const; 165 166 // Merges config with the current TraceConfig 167 void Merge(const TraceConfig& config); 168 169 void Clear(); 170 memory_dump_config()171 const MemoryDumpConfig& memory_dump_config() const { 172 return memory_dump_config_; 173 } 174 175 private: 176 FRIEND_TEST_ALL_PREFIXES(TraceConfigTest, TraceConfigFromValidLegacyFormat); 177 FRIEND_TEST_ALL_PREFIXES(TraceConfigTest, 178 TraceConfigFromInvalidLegacyStrings); 179 FRIEND_TEST_ALL_PREFIXES(TraceConfigTest, ConstructDefaultTraceConfig); 180 FRIEND_TEST_ALL_PREFIXES(TraceConfigTest, TraceConfigFromValidString); 181 FRIEND_TEST_ALL_PREFIXES(TraceConfigTest, TraceConfigFromInvalidString); 182 FRIEND_TEST_ALL_PREFIXES(TraceConfigTest, 183 IsEmptyOrContainsLeadingOrTrailingWhitespace); 184 FRIEND_TEST_ALL_PREFIXES(TraceConfigTest, TraceConfigFromMemoryConfigString); 185 FRIEND_TEST_ALL_PREFIXES(TraceConfigTest, LegacyStringToMemoryDumpConfig); 186 FRIEND_TEST_ALL_PREFIXES(TraceConfigTest, EmptyMemoryDumpConfigTest); 187 188 // The default trace config, used when none is provided. 189 // Allows all non-disabled-by-default categories through, except if they end 190 // in the suffix 'Debug' or 'Test'. 191 void InitializeDefault(); 192 193 // Initialize from the config string 194 void InitializeFromConfigString(const std::string& config_string); 195 196 // Initialize from category filter and trace options strings 197 void InitializeFromStrings(const std::string& category_filter_string, 198 const std::string& trace_options_string); 199 200 void SetCategoriesFromIncludedList(const base::ListValue& included_list); 201 void SetCategoriesFromExcludedList(const base::ListValue& excluded_list); 202 void SetSyntheticDelaysFromList(const base::ListValue& list); 203 void AddCategoryToDict(base::DictionaryValue& dict, 204 const char* param, 205 const StringList& categories) const; 206 207 void SetMemoryDumpConfig(const base::DictionaryValue& memory_dump_config); 208 void SetDefaultMemoryDumpConfig(); 209 210 // Convert TraceConfig to the dict representation of the TraceConfig. 211 void ToDict(base::DictionaryValue& dict) const; 212 213 std::string ToTraceOptionsString() const; 214 215 void WriteCategoryFilterString(const StringList& values, 216 std::string* out, 217 bool included) const; 218 void WriteCategoryFilterString(const StringList& delays, 219 std::string* out) const; 220 221 // Returns true if category is enable according to this trace config. 222 bool IsCategoryEnabled(const char* category_name) const; 223 224 static bool IsEmptyOrContainsLeadingOrTrailingWhitespace( 225 const std::string& str); 226 227 bool HasIncludedPatterns() const; 228 229 TraceRecordMode record_mode_; 230 bool enable_sampling_ : 1; 231 bool enable_systrace_ : 1; 232 bool enable_argument_filter_ : 1; 233 234 MemoryDumpConfig memory_dump_config_; 235 236 StringList included_categories_; 237 StringList disabled_categories_; 238 StringList excluded_categories_; 239 StringList synthetic_delays_; 240 }; 241 242 } // namespace trace_event 243 } // namespace base 244 245 #endif // BASE_TRACE_EVENT_TRACE_CONFIG_H_ 246