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:

[nduca, 2013/01/28 08:15:28]

The first argument to traces is a comma-separated list of categories, for
example:

Sorry to change my mind on this since the last review, but now that I see this
patch, its starting to look clearer. I think we should try to go through and
where we say Category, instead say CategoryGroup. Category just means "tag", and
we avoid the word CategoryGroup to indicate cat1,cat2 type things.

+//
+// TRACE_EVENT_INSTANT0("MY_SUBSYSTEM_1, MY_SUB_SYSTEM_2", "ImportantEvent")

[nduca, 2013/01/28 08:15:28]

Lets give a concerete example here so its less abstract. So you could give an
example like "MouseMove" which is of interest to both Views and Rendering.

It is often the case that one trace may belong in multiple categories at the
same time. The first argument to the trace can be a comma-separated list of
categories, forming a category group, like so:
<example, "Input,Views" maybe.>

Once instrumente in this fashion, the trace event can be enabled or disabled by
either asking for Input, Views, or both.

+//
+// 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",

[nduca, 2013/01/28 08:15:28]

i think its safe to say category once we make the previously mentioned changes

 //                  "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_