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