[ltt-dev] [RFC] UST instrumentation API

Tue Apr 19 17:56:35 EDT 2011

* Mathieu Desnoyers (mathieu.desnoyers at efficios.com) wrote:
> * Nils Carlson (nils.carlson at ludd.ltu.se) wrote:
> >
> > On Apr 14, 2011, at 4:53 PM, David Goulet wrote:
> >
> >> Hola,
> >>
> >> I like the idea of making thing more simpler and more "namespace  
> >> oriented" for ust.
> >>
> >> On 11-04-13 04:59 PM, Mathieu Desnoyers wrote:
> >>> OK, so I took care of most of the instrumentation API, but some
> >>> questions need discussion.
> >>>
> >>> ->  given that the API presented to users will be "TRACE_EVENT()" 
> >>> (which
> >>> we should rename to something else to eliminate confusion), it might
> >>> make sense to make both of DECLARE_TRACE and DEFINE_TRACE internal to
> >>> tracepoints and don't expose them to the users.
> >>
> >> If I understand correctly what we want for ust, marker are staying,  
> >> tracepoint are getting replaced by trace event? So, considering this  
> >> fact, those two macros (declare_ and define_) should simply be not  
> >> supported anymore and eventually get rid of them?
> >
> > This sounds good, though it will mean that we will always generate the  
> > "TRACE_EVENT" part of the tracepoint, that is, no tracepoints that don't 
> > generate data... But I think this is fine.
> 
> In TRACE_EVENT, the probe code generation is only done if
> "CREATE_TRACE_POINTS" is defined before including the instrumentation
> header. This is necessary to make sure we don't generate duplicated
> probe code when including the header in multiple objects.
> 
> We'd have to ensure that this "define" is also standardized, as it is
> part of the API.
> 
> >>
> >>>
> >>> TRACE_EVENT() could be the macro replacing these, but I would  
> >>> recommend
> >>> using a name like "TRACEPOINT_TEMPLATE()", which is what it really  
> >>> is.
> >>>
> >>
> >> A good concern raised by Steven R. is the fact that "TRACE_EVENT" can 
> >> and will confuse people with the ones in the kernel (in terms of  
> >> google search mostly!). So, a name like "TRACEPOINT_TEMPLATE" says to 
> >> me (normal person, no tracing knowledge, maybe my grand mother!) : this 
> >> is tracepoint related, nothing to do with trace event and I don't want 
> >> to modify a template right... (totally confused :P).
> >>
> >> So, should it be more "TRACE EVENT" user-space oriented for the name?
> >>
> >> UTRACE_EVENT --> confusing with utrace
> >> UPROBE... --> again, confusing with uprobe...
> >> UST_TRACE_EVENT --> ust stands for user-space tracing (and not LTTng  
> >> user-space tracer :P)
> >>
> >> ... maybe we need more brainstorm... I'm out of ideas...
> >
> > What about UST_EVENT ? Though I thought we were going to "share" the  
> > tracepoints, so this might not be a good name, on the other hand, it  
> > does sound good: Userspace Trace Event, in fact, I would say that we can 
> > use this name even if we do share it. Its a good description.
> 
> I'd like to keep something close to "tracepoint", especially since we
> now use "tracepoint(name, ...)" as instrumentation API. I don't see much
> need to make the "event" declaration an entirely different API; this
> seems more confusing than anything else. It needed to be that way in the
> kernel to handle the transition, but here, in UST, we can design it
> properly.
> 
> I'd prefer to keep "ust_" and "UST_" only for ust-lib specific APIs,
> which is not the case for this one.
> 
> So maybe
> 
> TRACEPOINT_EVENT() ?
> 
> and while we are there, the #define that would control definition of
> tracepoint callbacks could be:
> 
> #define TRACEPOINT_DEFINE
> 
> (not sure if the preprocessor #define vs action of "defining" an object
> might not confuse users though)

How about:

"TRACEPOINT_EVENT()" and "#define TRACEPOINT_CREATE" ?

Ideally, I'd like to settle this API and release a UST 0.13 this week,
so people who want to start instrumenting their code can use the new
Markers API while we move to the TRACEPOINT_EVENT infrastructure.

Thanks,

Mathieu

> 
> >
> >>
> >>>
> >>> UST Markers (main API members):
> >>>
> >>> #include<ust/marker.h>
> >>>
> >>> ust_marker(name, "fmt", ...)
> >>> UST_MARKER_NOARGS
> >>> GET_UST_MARKER()
> >>> DEFINE_UST_MARKER(name, ...)
> >>> ust_marker_probe_unregister()
> >>> ust_marker_probe_register()
> >>> ust_marker_synchronize_unregister()
> >>> UST_MARKER_LIB
> >>>
> >>> Will be eventually phased-out with the new TRACEPOINT_TEMPLATE() and 
> >>> CTF:
> >>> DEFINE_UST_MARKER_TP()
> >>> ust_marker_tp()
> >>>
> >>
> >> No problem. Simpler is better and this API will be UST specific so  
> >> rtfm at that point :).
> >
> > Just one question, these are UST internal right? I mean, not to be  
> > confused with the ustctl functions?
> 
> Not sure I understand your question. But the "ust_marker()" is an API
> exposed to application willing to do ad-hoc tracing relying directly on
> UST. These application libraries using ust_marker() would have to define
> UST_MARKER_LIB. UST_MARKER_NOARGS is also needed. For the rest, I agree
> that it's more UST-internal.
> 
> Thanks,
> 
> Mathieu
> 
> >
> > /Nils
> >
> >>
> >> Thanks
> >> David
> >>
> >>> Feedback is welcome,
> >>>
> >>> Thanks,
> >>>
> >>> Mathieu
> >>>
> >>
> >> -- 
> >> David Goulet
> >> LTTng project, DORSAL Lab.
> >>
> >> PGP/GPG : 1024D/16BD8563
> >> BE3C 672B 9331 9796 291A  14C6 4AF7 C14B 16BD 8563
> >>
> >> _______________________________________________
> >> ltt-dev mailing list
> >> ltt-dev at lists.casi.polymtl.ca
> >> http://lists.casi.polymtl.ca/cgi-bin/mailman/listinfo/ltt-dev
> >
> 
> -- 
> Mathieu Desnoyers
> Operating System Efficiency R&D Consultant
> EfficiOS Inc.
> http://www.efficios.com

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