trace_config.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361
  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. #ifndef BASE_TRACE_EVENT_TRACE_CONFIG_H_
  5. #define BASE_TRACE_EVENT_TRACE_CONFIG_H_
  6. #include <stdint.h>
  7. #include <memory>
  8. #include <set>
  9. #include <string>
  10. #include <unordered_set>
  11. #include <vector>
  12. #include "base/base_export.h"
  13. #include "base/gtest_prod_util.h"
  14. #include "base/strings/string_piece.h"
  15. #include "base/trace_event/memory_dump_request_args.h"
  16. #include "base/trace_event/trace_config_category_filter.h"
  17. #include "base/values.h"
  18. namespace base {
  19. namespace trace_event {
  20. class ConvertableToTraceFormat;
  21. // Options determines how the trace buffer stores data.
  22. // A Java counterpart will be generated for this enum.
  23. // GENERATED_JAVA_ENUM_PACKAGE: org.chromium.base
  24. enum TraceRecordMode {
  25. // Record until the trace buffer is full.
  26. RECORD_UNTIL_FULL,
  27. // Record until the user ends the trace. The trace buffer is a fixed size
  28. // and we use it as a ring buffer during recording.
  29. RECORD_CONTINUOUSLY,
  30. // Record until the trace buffer is full, but with a huge buffer size.
  31. RECORD_AS_MUCH_AS_POSSIBLE,
  32. // Echo to console. Events are discarded.
  33. ECHO_TO_CONSOLE,
  34. };
  35. class BASE_EXPORT TraceConfig {
  36. public:
  37. using StringList = std::vector<std::string>;
  38. // Specifies the memory dump config for tracing.
  39. // Used only when "memory-infra" category is enabled.
  40. struct BASE_EXPORT MemoryDumpConfig {
  41. MemoryDumpConfig();
  42. MemoryDumpConfig(const MemoryDumpConfig& other);
  43. ~MemoryDumpConfig();
  44. // Specifies the triggers in the memory dump config.
  45. struct Trigger {
  46. uint32_t min_time_between_dumps_ms;
  47. MemoryDumpLevelOfDetail level_of_detail;
  48. MemoryDumpType trigger_type;
  49. };
  50. // Specifies the configuration options for the heap profiler.
  51. struct HeapProfiler {
  52. // Default value for |breakdown_threshold_bytes|.
  53. enum { kDefaultBreakdownThresholdBytes = 1024 };
  54. HeapProfiler();
  55. // Reset the options to default.
  56. void Clear();
  57. uint32_t breakdown_threshold_bytes;
  58. };
  59. // Reset the values in the config.
  60. void Clear();
  61. void Merge(const MemoryDumpConfig& config);
  62. // Set of memory dump modes allowed for the tracing session. The explicitly
  63. // triggered dumps will be successful only if the dump mode is allowed in
  64. // the config.
  65. std::set<MemoryDumpLevelOfDetail> allowed_dump_modes;
  66. std::vector<Trigger> triggers;
  67. HeapProfiler heap_profiler_options;
  68. };
  69. class BASE_EXPORT ProcessFilterConfig {
  70. public:
  71. ProcessFilterConfig();
  72. explicit ProcessFilterConfig(
  73. const std::unordered_set<base::ProcessId>& included_process_ids);
  74. ProcessFilterConfig(const ProcessFilterConfig&);
  75. ~ProcessFilterConfig();
  76. bool empty() const { return included_process_ids_.empty(); }
  77. void Clear();
  78. void Merge(const ProcessFilterConfig&);
  79. void InitializeFromConfigDict(const Value&);
  80. void ToDict(Value::Dict& dict) const;
  81. bool IsEnabled(base::ProcessId) const;
  82. const std::unordered_set<base::ProcessId>& included_process_ids() const {
  83. return included_process_ids_;
  84. }
  85. bool operator==(const ProcessFilterConfig& other) const {
  86. return included_process_ids_ == other.included_process_ids_;
  87. }
  88. private:
  89. std::unordered_set<base::ProcessId> included_process_ids_;
  90. };
  91. class BASE_EXPORT EventFilterConfig {
  92. public:
  93. explicit EventFilterConfig(const std::string& predicate_name);
  94. EventFilterConfig(const EventFilterConfig& tc);
  95. ~EventFilterConfig();
  96. EventFilterConfig& operator=(const EventFilterConfig& rhs);
  97. void InitializeFromConfigDict(const Value& event_filter);
  98. void SetCategoryFilter(const TraceConfigCategoryFilter& category_filter);
  99. void ToDict(Value::Dict& filter_dict) const;
  100. bool GetArgAsSet(const char* key, std::unordered_set<std::string>*) const;
  101. bool IsCategoryGroupEnabled(const StringPiece& category_group_name) const;
  102. const std::string& predicate_name() const { return predicate_name_; }
  103. const Value& filter_args() const { return args_; }
  104. const TraceConfigCategoryFilter& category_filter() const {
  105. return category_filter_;
  106. }
  107. private:
  108. std::string predicate_name_;
  109. TraceConfigCategoryFilter category_filter_;
  110. Value args_;
  111. };
  112. typedef std::vector<EventFilterConfig> EventFilters;
  113. static std::string TraceRecordModeToStr(TraceRecordMode record_mode);
  114. TraceConfig();
  115. // Create TraceConfig object from category filter and trace options strings.
  116. //
  117. // |category_filter_string| is a comma-delimited list of category wildcards.
  118. // A category can have an optional '-' prefix to make it an excluded category.
  119. // All the same rules apply above, so for example, having both included and
  120. // excluded categories in the same list would not be supported.
  121. //
  122. // |trace_options_string| is a comma-delimited list of trace options.
  123. // Possible options are: "record-until-full", "record-continuously",
  124. // "record-as-much-as-possible", "trace-to-console", "enable-systrace" and
  125. // "enable-argument-filter".
  126. // The first 4 options are trace recoding modes and hence
  127. // mutually exclusive. If more than one trace recording modes appear in the
  128. // options_string, the last one takes precedence. If none of the trace
  129. // recording mode is specified, recording mode is RECORD_UNTIL_FULL.
  130. //
  131. // The trace option will first be reset to the default option
  132. // (record_mode set to RECORD_UNTIL_FULL, enable_systrace and
  133. // enable_argument_filter set to false) before options parsed from
  134. // |trace_options_string| are applied on it. If |trace_options_string| is
  135. // invalid, the final state of trace options is undefined.
  136. //
  137. // Example: TraceConfig("test_MyTest*", "record-until-full");
  138. // Example: TraceConfig("test_MyTest*,test_OtherStuff",
  139. // "record-continuously");
  140. // Example: TraceConfig("-excluded_category1,-excluded_category2",
  141. // "record-until-full, trace-to-console");
  142. // would set ECHO_TO_CONSOLE as the recording mode.
  143. // Example: TraceConfig("-*,webkit", "");
  144. // would disable everything but webkit; and use default options.
  145. // Example: TraceConfig("-webkit", "");
  146. // would enable everything but webkit; and use default options.
  147. TraceConfig(StringPiece category_filter_string,
  148. StringPiece trace_options_string);
  149. TraceConfig(StringPiece category_filter_string, TraceRecordMode record_mode);
  150. // Create TraceConfig object from the trace config string.
  151. //
  152. // |config_string| is a dictionary formatted as a JSON string, containing both
  153. // category filters and trace options.
  154. //
  155. // Example:
  156. // {
  157. // "record_mode": "record-continuously",
  158. // "enable_systrace": true,
  159. // "enable_argument_filter": true,
  160. // "included_categories": ["included",
  161. // "inc_pattern*",
  162. // "disabled-by-default-memory-infra"],
  163. // "excluded_categories": ["excluded", "exc_pattern*"],
  164. // "memory_dump_config": {
  165. // "triggers": [
  166. // {
  167. // "mode": "detailed",
  168. // "periodic_interval_ms": 2000
  169. // }
  170. // ]
  171. // }
  172. // }
  173. //
  174. // Note: memory_dump_config can be specified only if
  175. // disabled-by-default-memory-infra category is enabled.
  176. explicit TraceConfig(StringPiece config_string);
  177. // Functionally identical to the above, but takes a parsed dictionary as input
  178. // instead of its JSON serialization.
  179. explicit TraceConfig(const Value& config);
  180. TraceConfig(const TraceConfig& tc);
  181. ~TraceConfig();
  182. TraceConfig& operator=(const TraceConfig& rhs);
  183. TraceRecordMode GetTraceRecordMode() const { return record_mode_; }
  184. size_t GetTraceBufferSizeInEvents() const {
  185. return trace_buffer_size_in_events_;
  186. }
  187. size_t GetTraceBufferSizeInKb() const { return trace_buffer_size_in_kb_; }
  188. bool IsSystraceEnabled() const { return enable_systrace_; }
  189. bool IsArgumentFilterEnabled() const { return enable_argument_filter_; }
  190. void SetTraceRecordMode(TraceRecordMode mode) { record_mode_ = mode; }
  191. void SetTraceBufferSizeInEvents(size_t size) {
  192. trace_buffer_size_in_events_ = size;
  193. }
  194. void SetTraceBufferSizeInKb(size_t size) { trace_buffer_size_in_kb_ = size; }
  195. void EnableSystrace() { enable_systrace_ = true; }
  196. void EnableSystraceEvent(const std::string& systrace_event);
  197. void EnableArgumentFilter() { enable_argument_filter_ = true; }
  198. void EnableHistogram(const std::string& histogram_name);
  199. // Writes the string representation of the TraceConfig. The string is JSON
  200. // formatted.
  201. std::string ToString() const;
  202. // Returns a copy of the TraceConfig wrapped in a ConvertableToTraceFormat
  203. std::unique_ptr<ConvertableToTraceFormat> AsConvertableToTraceFormat() const;
  204. // Write the string representation of the CategoryFilter part.
  205. std::string ToCategoryFilterString() const;
  206. // Write the string representation of the trace options part (record mode,
  207. // systrace, argument filtering). Does not include category filters, event
  208. // filters, or memory dump configs.
  209. std::string ToTraceOptionsString() const;
  210. // Returns true if at least one category in the list is enabled by this
  211. // trace config. This is used to determine if the category filters are
  212. // enabled in the TRACE_* macros.
  213. bool IsCategoryGroupEnabled(const StringPiece& category_group_name) const;
  214. // Merges config with the current TraceConfig
  215. void Merge(const TraceConfig& config);
  216. void Clear();
  217. // Clears and resets the memory dump config.
  218. void ResetMemoryDumpConfig(const MemoryDumpConfig& memory_dump_config);
  219. const TraceConfigCategoryFilter& category_filter() const {
  220. return category_filter_;
  221. }
  222. const MemoryDumpConfig& memory_dump_config() const {
  223. return memory_dump_config_;
  224. }
  225. const ProcessFilterConfig& process_filter_config() const {
  226. return process_filter_config_;
  227. }
  228. void SetProcessFilterConfig(const ProcessFilterConfig&);
  229. const EventFilters& event_filters() const { return event_filters_; }
  230. void SetEventFilters(const EventFilters& filter_configs) {
  231. event_filters_ = filter_configs;
  232. }
  233. // Returns true if event names should not contain package names.
  234. bool IsEventPackageNameFilterEnabled() const {
  235. return enable_event_package_name_filter_;
  236. }
  237. // If `enabled` is true, event names will not contain package names.
  238. void SetEventPackageNameFilterEnabled(bool enabled) {
  239. enable_event_package_name_filter_ = enabled;
  240. }
  241. const std::unordered_set<std::string>& systrace_events() const {
  242. return systrace_events_;
  243. }
  244. const std::unordered_set<std::string>& histogram_names() const {
  245. return histogram_names_;
  246. }
  247. private:
  248. FRIEND_TEST_ALL_PREFIXES(TraceConfigTest, TraceConfigFromValidLegacyFormat);
  249. FRIEND_TEST_ALL_PREFIXES(TraceConfigTest,
  250. TraceConfigFromInvalidLegacyStrings);
  251. FRIEND_TEST_ALL_PREFIXES(TraceConfigTest, SystraceEventsSerialization);
  252. // The default trace config, used when none is provided.
  253. // Allows all non-disabled-by-default categories through, except if they end
  254. // in the suffix 'Debug' or 'Test'.
  255. void InitializeDefault();
  256. // Initialize from a config dictionary.
  257. void InitializeFromConfigDict(const Value& dict);
  258. // Initialize from a config string.
  259. void InitializeFromConfigString(StringPiece config_string);
  260. // Initialize from category filter and trace options strings
  261. void InitializeFromStrings(StringPiece category_filter_string,
  262. StringPiece trace_options_string);
  263. void SetMemoryDumpConfigFromConfigDict(const Value& memory_dump_config);
  264. void SetDefaultMemoryDumpConfig();
  265. void SetHistogramNamesFromConfigList(const Value& histogram_names);
  266. void SetEventFiltersFromConfigList(const Value& event_filters);
  267. Value ToValue() const;
  268. TraceRecordMode record_mode_;
  269. size_t trace_buffer_size_in_events_ = 0; // 0 specifies default size
  270. size_t trace_buffer_size_in_kb_ = 0; // 0 specifies default size
  271. bool enable_systrace_ : 1;
  272. bool enable_argument_filter_ : 1;
  273. TraceConfigCategoryFilter category_filter_;
  274. MemoryDumpConfig memory_dump_config_;
  275. ProcessFilterConfig process_filter_config_;
  276. EventFilters event_filters_;
  277. bool enable_event_package_name_filter_ : 1;
  278. std::unordered_set<std::string> histogram_names_;
  279. std::unordered_set<std::string> systrace_events_;
  280. };
  281. } // namespace trace_event
  282. } // namespace base
  283. #endif // BASE_TRACE_EVENT_TRACE_CONFIG_H_