[ltt-dev] [RFC] UST instrumentation API

[Mathieu Desnoyers]

* 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)

>
>>
>>>
>>> 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