Home | History | Annotate | Download | only in trace_event 
      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 
    142   TraceRecordMode GetTraceRecordMode() const { return record_mode_; }
    143   bool IsSamplingEnabled() const { return enable_sampling_; }
    144   bool IsSystraceEnabled() const { return enable_systrace_; }
    145   bool IsArgumentFilterEnabled() const { return enable_argument_filter_; }
    146 
    147   void SetTraceRecordMode(TraceRecordMode mode) { record_mode_ = mode; }
    148   void EnableSampling() { enable_sampling_ = true; }
    149   void EnableSystrace() { enable_systrace_ = true; }
    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 
    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