Trace category groups and category filter.

base/debug/trace_event.h

 // Copyright (c) 2012 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.
 
 // This header is designed to give you trace_event macros without specifying
 // how the events actually get collected and stored. If you need to expose trace
 // event to some other universe, you can copy-and-paste this file,
 // implement the TRACE_EVENT_API macros, and do any other necessary fixup for
 // the target platform. The end result is that multiple libraries can funnel
 // events through to a shared trace event collector.
 
 // 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")
 //
+// A category can be made up of several tags, for example:
+//
+// TRACE_EVENT_INSTANT0("MY_SUBSYSTEM_1, MY_SUB_SYSTEM_2", "ImportantEvent")
+//
+// We can enable/disable tracing of ImportantEvent by enabling/disabling either
+// tag.
+//
 // Events can be INSTANT, or can be pairs of BEGIN and END in the same scope:
 //   TRACE_EVENT_BEGIN0("MY_SUBSYSTEM", "SomethingCostly")
 //   doSomethingCostly()
 //   TRACE_EVENT_END0("MY_SUBSYSTEM", "SomethingCostly")
 // Note: our tools can't always determine the correct BEGIN/END pairs unless
 // these are used in the same scope. Use ASYNC_BEGIN/ASYNC_END macros if you
 // need them to be in separate scopes.
 //
 // A common use case is to trace entire function scopes. This
 // issues a trace BEGIN and END automatically:
@@ skipping 62 matching lines @@
 // 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:
-//     char* str = strdup("impprtantName");
+//     char* str = strdup("importantName");
 //     TRACE_EVENT_INSTANT0("SUBSYSTEM", str);  // BAD!
 //     free(str);                   // Trace system now has dangling pointer
 //
 // To avoid this issue with the |name| and |arg_name| parameters, use the
 // TRACE_EVENT_COPY_XXX overloads of the macros at additional runtime overhead.
 // Notes: The category must always be in a long-lived char* (i.e. static const).
 //        The |arg_values|, when used, are always deep copied with the _COPY
 //        macros.
 //
 // When are string argument values copied:
 // const char* arg_values are only referenced by default:
-//     TRACE_EVENT1("category", "name",
+//     TRACE_EVENT1("category_tag1", "name",
 //                  "arg1", "literal string is only referenced");
 // Use TRACE_STR_COPY to force copying of a const char*:
-//     TRACE_EVENT1("category", "name",
+//     TRACE_EVENT1("category_tag1", "name",
 //                  "arg1", TRACE_STR_COPY("string will be copied"));
 // std::string arg_values are always copied:
-//     TRACE_EVENT1("category", "name",
+//     TRACE_EVENT1("category_tag1", "name",
 //                  "arg1", std::string("string will be copied"));
 //
 //
 // Thread Safety:
 // A thread safe singleton and mutex are used for thread safety. Category
 // enabled flags are used to limit the performance impact when the system
 // is not enabled.
 //
 // TRACE_EVENT macros first cache a pointer to a category. The categories are
 // statically allocated and safe at all times, even after exit. Fetching a
@@ skipping 780 matching lines @@
     const char* name;
   };
   Data* p_data_;
   Data data_;
 };
 
 
 }  // namespace trace_event_internal
 
 #endif  // BASE_DEBUG_TRACE_EVENT_H_