[ltt-dev] [RFC] New UST 2.0 Tracepoint Event API

[mathieu.desnoyers@efficios.com (Mathieu Desnoyers)]

* Mathieu Desnoyers (compudj at krystal.dyndns.org) wrote:
> * Nathan Scott (nathans at debian.org) wrote:
> [...]
> > > I was also wondering if putting a "loglevel" information (could be
> > > optional) into the TRACEPOINT_EVENT declaration would be useful ? This
> > > could define log levels such as debug, info, warning, and error.
> > >
> > 
> > I think that'd be useful - ETW does this on Windows, FWIW.
> > Being able to enable/disable these sub-classes of events is probably useful
> > and it shows the programmers general intent with each event too.
> 
> Hrm, I thought about this loglevel idea a little more, and it does not
> seem like it belongs directly into TRACEPOINT_EVENT(). Although tracing
> *can* do logging, tracing is not logging. Therefore, it makes no sense
> to require information that is logging-specific to be declared for all
> tracepoints.
> 
> I foresee that we could eventually add API members to support loglevels
> defined alongside with the tracepoint instrumentation, e.g.:
> 
> TRACEPOINT_LOGLEVEL_ENUM(
> 	TP_LOGLEVEL(TP_LOG_DEBUG, 0),
> 	TP_LOGLEVEL(TP_LOG_WARN, 1),
> 	...
> )
> 
> TRACEPOINT_EVENT(
> 	some_tp_name,
> 	rest of standard tracepoint declaration, without any loglevel
> 	whatsoever...
> )
> 
> TRACEPOINT_LOGLEVEL(some_tp_name, TP_LOG_DEBUG)
> 
> With this, libust could export the application loglevels, along with the
> event name to loglevel mappings. I don't plan to implement this API
> right now though.
> 
> Thoughts ?

I have a client who would like this API to appear in UST 2.0 headers
soon so they can use it in their instrumentation (even before those
macros are actually implemented). So I think it makes sense to settle on
this:

#ifndef TRACEPOINT_LOGLEVEL

/*
 * Tracepoint Loglevel Declaration Facility
 *
 * This is a place-holder the tracepoint loglevel declaration,
 * overridden by the tracer implementation.
 *
 * Typical use of these loglevels:
 *
 * 1) Declare the mapping between loglevel names and an integer values
 *    within TRACEPOINT_LOGLEVEL_ENUM, using TP_LOGLEVEL for each tuple.
 *    Do _NOT_ add comma (,) nor semicolon (;) between the
 *    TRACEPOINT_LOGLEVEL_ENUM entries. Do _NOT_ add comma (,) nor
 *    semicolon (;) after the TRACEPOINT_LOGLEVEL_ENUM declaration.  The
 *    name should be a proper C99 identifier.
 *
 *      TRACEPOINT_LOGLEVEL_ENUM(
 *              TP_LOGLEVEL( < loglevel_name >, < value > )
 *              TP_LOGLEVEL( < loglevel_name >, < value > )
 *              ...
 *      )
 *
 *    e.g.:
 *
 *      TRACEPOINT_LOGLEVEL_ENUM(
 *              TP_LOGLEVEL(LOG_EMERG,   0)
 *              TP_LOGLEVEL(LOG_ALERT,   1)
 *              TP_LOGLEVEL(LOG_CRIT,    2)
 *              TP_LOGLEVEL(LOG_ERR,     3)
 *              TP_LOGLEVEL(LOG_WARNING, 4)
 *              TP_LOGLEVEL(LOG_NOTICE,  5)
 *              TP_LOGLEVEL(LOG_INFO,    6)
 *              TP_LOGLEVEL(LOG_DEBUG,   7)
 *      )
 *
 * 2) Then, declare tracepoint loglevels for tracepoints. The first
 *    field is the name of the tracepoint, the second field is the
 *    loglevel name.
 *
 *      TRACEPOINT_LOGLEVEL(< [com_company_]project_[component_]event >,
 *              < loglevel_name >)
 *
 * The TRACEPOINT_SYSTEM must be defined when declaring a
 * TRACEPOINT_LOGLEVEL_ENUM and TRACEPOINT_LOGLEVEL. The tracepoint
 * loglevel enumeration apply to the entire TRACEPOINT_SYSTEM. Only one
 * tracepoint loglevel enumeration should be declared per tracepoint
 * system.
 */

#define TRACEPOINT_LOGLEVEL_ENUM()
#define TRACEPOINT_LOGLEVEL(name, loglevel)

#endif /* #ifndef TRACEPOINT_LOGLEVEL */


So although I cannot say with a 100% confidence level that this will not
change when I will implement the actual macros (planned for this Fall),
I am fairly confident we should be fine with this API.

Feedback is, as always, welcome.

Thanks,

Mathieu

-- 
Mathieu Desnoyers
Operating System Efficiency R&D Consultant
EfficiOS Inc.
http://www.efficios.com