components/tracing/trace_config_file.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 COMPONENTS_TRACING_TRACE_CONFIG_FILE_H_
   6 #define COMPONENTS_TRACING_TRACE_CONFIG_FILE_H_
   7
   8 #include "base/files/file_path.h"
   9 #include "base/macros.h"
  10 #include "base/trace_event/trace_config.h"
  11 #include "components/tracing/tracing_export.h"
  12
  13 template <typename Type> struct DefaultSingletonTraits;
  14
  15 namespace tracing {
  16
  17 // TraceConfigFile is a singleton that contains the configurations of tracing.
  18 // One can create a trace config file and use it to configure startup and/or
  19 // shutdown tracing.
  20 //
  21 // The trace config file should be JSON formated. One example is:
  22 //   {
  23 //     "trace_config": {
  24 //        "record_mode": "record-until-full",
  25 //        "included_categories": ["cc", "skia"]
  26 //      },
  27 //      "startup_duration": 5,
  28 //      "result_file": "chrometrace.log"
  29 //   }
  30 //
  31 // trace_config:     The configuration of tracing. Please see the details in
  32 //                   base/trace_event/trace_config.h.
  33 //
  34 // startup_duration: The duration for startup tracing in terms of seconds.
  35 //                   Tracing will stop automatically after the duration. If this
  36 //                   value is not specified, the duration is 0 and one needs
  37 //                   to stop tracing by other ways, e.g., by DevTools, or get
  38 //                   the result file after shutting the browser down.
  39 //
  40 // result_file:      The file that contains the trace log. The default result
  41 //                   file path is chrometrace.log. Chrome will dump the trace
  42 //                   log to this file
  43 //                   1) after startup_duration if it is specified;
  44 //                   2) or after browser shutdown if startup duration is 0.
  45 //                   One can also stop tracing and get the result by other ways,
  46 //                   e.g., by DevTools. In that case, the trace log will not be
  47 //                   saved to this file.
  48 //                   Notice: This is not supported on Android. The result file
  49 //                   path will be generated by tracing controller.
  50 //
  51 // The trace config file can be specified by the --trace-config-file flag on
  52 // most platforms except on Android, e.g., --trace-config-file=path/to/file/.
  53 // This flag should not be used with --trace-startup or --trace-shutdown. If
  54 // those two flags are used, --trace-config-file flag will be ignored. If the
  55 // --trace-config-file flag is used without the file path, Chrome will do
  56 // startup tracing with 5 seconds' startup duration.
  57 //
  58 // On Android, Chrome does not read the --trace-config-file flag, because not
  59 // all Chrome based browsers read customized flag, e.g., Android WebView. Chrome
  60 // on Android reads from a fixed file location:
  61 //   /data/local/chrome-trace-config.json
  62 // If this file exists, Chrome will start tracing according to the configuration
  63 // specified in the file, otherwise, Chrome will not start tracing.
  64 class TRACING_EXPORT TraceConfigFile {
  65  public:
  66   static TraceConfigFile* GetInstance();
  67
  68   bool IsEnabled() const;
  69   base::trace_event::TraceConfig GetTraceConfig() const;
  70   int GetStartupDuration() const;
  71 #if !defined(OS_ANDROID)
  72   base::FilePath GetResultFile() const;
  73 #endif
  74
  75  private:
  76   // This allows constructor and destructor to be private and usable only
  77   // by the Singleton class.
  78   friend struct DefaultSingletonTraits<TraceConfigFile>;
  79   TraceConfigFile();
  80   ~TraceConfigFile();
  81
  82   bool ParseTraceConfigFileContent(std::string content);
  83
  84   bool is_enabled_;
  85   base::trace_event::TraceConfig trace_config_;
  86   int startup_duration_;
  87   base::FilePath result_file_;
  88
  89   DISALLOW_COPY_AND_ASSIGN(TraceConfigFile);
  90 };
  91
  92 }  // namespace tracing
  93
  94 #endif  // COMPONENTS_TRACING_TRACE_CONFIG_FILE_H_