base/trace_event/trace_config.h

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