Implement TRACE_COUNTER

base/debug/trace_event.h

 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-// Trace events are for tracking application performance.
+// Trace events are for tracking application performance and resource usage.
+// Macros are provided to track:
+//    Begin and end of function calls
+//    Counters
 //
 // Events are issued against categories. Whereas LOG's
 // categories are statically defined, TRACE categories are created
 // implicitly with a string. For example:
 //   TRACE_EVENT_INSTANT0("MY_SUBSYSTEM", "SomeImportantEvent")
 //
 // Events can be INSTANT, or can be pairs of BEGIN and END:
 //   TRACE_EVENT_BEGIN0("MY_SUBSYSTEM", "SomethingCostly")
 //   doSomethingCostly()
 //   TRACE_EVENT_END0("MY_SUBSYSTEM", "SomethingCostly")
 //
 // A common use case is to trace entire function scopes. This
 // issues a trace BEGIN and END automatically:
 //   void doSomethingCostly() {
 //     TRACE_EVENT0("MY_SUBSYSTEM", "doSomethingCostly");
 //     ...
 //   }
 //
 // Additional parameters can be associated with an event:
 //   void doSomethingCostly2(int howMuch) {
 //     TRACE_EVENT1("MY_SUBSYSTEM", "doSomethingCostly",
 //         "howMuch", howMuch);
 //     ...
 //   }
 //
 // The trace system will automatically add to this information the
 // current process id, thread id, and a timestamp in microseconds.
 //
+// Trace event also supports counters, which is a way to track a quantity
+// as it varies over time. Counters are created with the following macro:
+//   TRACE_COUNTER1("MY_SUBSYSTEM", "myCounter", g_myCounterValue);
+//
+// Counters are process-specific. The macro itself can be issued from any
+// thread, however.
+//
+// Sometimes, you want to track two counters at once. You cand o this with two

[jbates, 2011/11/16 19:16:17]

s/o/do

[jar (doing other things), 2011/11/16 20:18:41]

nit: typo: "cand o" --> "can do"

+// counter macros:
+//   TRACE_COUNTER1("MY_SUBSYSTEM", "myCounter0", g_myCounterValue[0]);
+//   TRACE_COUNTER1("MY_SUBSYSTEM", "myCounter1", g_myCounterValue[1]);
+// Or you can do it with a combined macro:
+//   TRACE_COUNTER2("MY_SUBSYSTEM", "myCounter",
+//       "bytesPinned", g_myCounterValue[0],
+//       "bytesAllocated", g_myCounterValue[1]);
+// This indicates to the tracing UI that these counters should be displayed
+// in a single graph, as a summed area chart.
+//
 // By default, trace collection is compiled in, but turned off at runtime.
 // Collecting trace data is the responsibility of the embedding
 // application. In Chrome's case, navigating to about:tracing will turn on
 // tracing and display data collected across all active processes.
 //
 //
 // Memory scoping note:
 // Tracing copies the pointers, not the string content, of the strings passed
 // in for category, name, and arg_names.  Thus, the following code will
 // cause problems:
@@ skipping 203 matching lines @@
     TRACE_EVENT_IF_LONGER_THAN1(threshold_us, category, name, NULL, 0)
 #define TRACE_EVENT_IF_LONGER_THAN1( \
         threshold_us, category, name, arg1_name, arg1_val) \
     TRACE_EVENT_IF_LONGER_THAN2(threshold_us, category, name, \
                            arg1_name, arg1_val, NULL, 0)
 #define TRACE_EVENT_IF_LONGER_THAN2( \
     threshold_us, category, name, arg1_name, arg1_val, arg2_name, arg2_val) \
     INTERNAL_TRACE_EVENT_ADD_SCOPED_IF_LONGER_THAN(threshold_us, \
         category, name, arg1_name, arg1_val, arg2_name, arg2_val)
 
+// Records the value of a counter called "name" immediately. Value
+// must be representable as a 32 bit integer.
+// - category and name strings must have application lifetime (statics or
+//   literals). They may not include " chars.
+#define TRACE_COUNTER1(category, name, value) \
+    TRACE_COUNTER2(category, name, "value", value, NULL, 0)
+#define TRACE_COPY_COUNTER1(category, name, value) \
+    TRACE_COPY_COUNTER2(category, name, "value", value, NULL, 0)
+
+// Records the values of a multi-parted counter called "name" immediately.
+// The UI will treat value1 and value2 as parts of a whole, displaying their
+// values as a stacked-bar chart.
+// - category and name strings must have application lifetime (statics or
+//   literals). They may not include " chars.
+#define TRACE_COUNTER2(category, name, value1_name, value1_val, \
+        value2_name, value2_val) \
+    INTERNAL_TRACE_EVENT_ADD_COUNTER( \
+        category, name, value1_name, value1_val, value2_name, value2_val, \
+        base::debug::TraceLog::EVENT_FLAG_NONE)
+#define TRACE_COPY_COUNTER2(category, name, value1_name, value1_val, \
+        value2_name, value2_val) \
+    INTERNAL_TRACE_EVENT_ADD_COUNTER( \
+        category, name, \
+        value1_name, value1_val, \
+        value2_name, value2_val, \
+        base::debug::TraceLog::EVENT_FLAG_COPY)
+
 
 // Implementation detail: trace event macros create temporary variables
 // to keep instrumentation overhead low. These macros give each temporary
 // variable a unique name based on the line number to prevent name collissions.
 #define INTERNAL_TRACE_EVENT_UID3(a,b) \
     trace_event_unique_##a##b
 #define INTERNAL_TRACE_EVENT_UID2(a,b) \
     INTERNAL_TRACE_EVENT_UID3(a,b)
 #define INTERNAL_TRACE_EVENT_UID(name_prefix) \
     INTERNAL_TRACE_EVENT_UID2(name_prefix, __LINE__)
@@ skipping 13 matching lines @@
 // event if the category is enabled.
 #define INTERNAL_TRACE_EVENT_ADD( \
       phase, category, name, arg1_name, arg1_val, arg2_name, arg2_val, flags) \
     INTERNAL_TRACE_EVENT_GET_CATEGORY_INFO(category); \
     if (INTERNAL_TRACE_EVENT_UID(catstatic)->enabled) { \
       base::debug::TraceLog::GetInstance()->AddTraceEvent( \
           phase, INTERNAL_TRACE_EVENT_UID(catstatic), \
           name, arg1_name, arg1_val, arg2_name, arg2_val, -1, 0, flags); \
     }
 
+// Implementation detail: internal macro to create static category and
+// add the counter event if it is enabled.
+#define INTERNAL_TRACE_EVENT_ADD_COUNTER( \
+      category, name, arg1_name, arg1_val, arg2_name, arg2_val, flags) \
+    INTERNAL_TRACE_EVENT_GET_CATEGORY_INFO(category); \
+    if (INTERNAL_TRACE_EVENT_UID(catstatic)->enabled) { \
+      base::debug::TraceLog::GetInstance()->AddCounterEvent( \
+          INTERNAL_TRACE_EVENT_UID(catstatic), \
+          name, arg1_name, arg1_val, arg2_name, arg2_val, flags); \
+    }
+
 // Implementation detail: internal macro to create static category and add begin
 // event if the category is enabled. Also adds the end event when the scope
 // ends.
 #define INTERNAL_TRACE_EVENT_ADD_SCOPED( \
       category, name, arg1_name, arg1_val, arg2_name, arg2_val) \
     INTERNAL_TRACE_EVENT_GET_CATEGORY_INFO(category); \
     base::debug::internal::TraceEndOnScopeClose \
         INTERNAL_TRACE_EVENT_UID(profileScope); \
     if (INTERNAL_TRACE_EVENT_UID(catstatic)->enabled) { \
       base::debug::TraceLog::GetInstance()->AddTraceEvent( \
@@ skipping 40 matching lines @@
   volatile bool enabled;
 };
 
 const size_t kTraceMaxNumArgs = 2;
 
 // Phase indicates the nature of an event entry. E.g. part of a begin/end pair.
 enum TraceEventPhase {
   TRACE_EVENT_PHASE_BEGIN,
   TRACE_EVENT_PHASE_END,
   TRACE_EVENT_PHASE_INSTANT,
-  TRACE_EVENT_PHASE_METADATA
+  TRACE_EVENT_PHASE_METADATA,
+  TRACE_EVENT_PHASE_COUNTER
 };
 
 // Simple union of values. This is much lighter weight than base::Value, which
 // requires dynamic allocation and a vtable. To keep the trace runtime overhead
 // low, we want constant size storage here.
 class BASE_EXPORT TraceValue {
  public:
   enum Type {
     TRACE_TYPE_UNDEFINED,
     TRACE_TYPE_BOOL,
@@ skipping 296 matching lines @@
                     EventFlags flags);
   static void AddTraceEventEtw(TraceEventPhase phase,
                                const char* name,
                                const void* id,
                                const char* extra);
   static void AddTraceEventEtw(TraceEventPhase phase,
                                const char* name,
                                const void* id,
                                const std::string& extra);
 
+  // A wrapper around AddTraceEvent used by TRACE_COUNTERx macros
+  // that allows only integer values for the counters.
+  int AddCounterEvent(const TraceCategory* category,
+                      const char* name,
+                      const char* arg1_name, int32 arg1_val,
+                      const char* arg2_name, int32 arg2_val,
+                      EventFlags flags);
+
   // Exposed for unittesting:
 
   // Allows deleting our singleton instance.
   static void DeleteForTesting();
 
   // Allows resurrecting our singleton instance post-AtExit processing.
   static void Resurrect();
 
   // Allow tests to inspect TraceEvents.
   size_t GetEventsSize() const { return logged_events_.size(); }
@@ skipping 94 matching lines @@
   Data* p_data_;
   Data data_;
 };
 
 }  // namespace internal
 
 }  // namespace debug
 }  // namespace base
 
 #endif  // BASE_DEBUG_TRACE_EVENT_H_