[lttng-dev] Question about TRACEPOINT_EVENT_CLASS and TRACEPOINT_EVENT_INSTANCE

[Thibault, Daniel]

> Date: Wed, 19 Nov 2014 15:35:01 +0400
> From: Eugene Ivanov <eiva at tbricks.com>
>
> I found description of TRACEPOINT_EVENT_CLASS on the website and in ust-tracepoint-event.h as well, but it is not documented in the lttng-ust man page.
> According the header TRACEPOINT_EVENT_INSTANCE declares an instance of a tracepoint, with its own provider and name.
> Does it mean that I can define classes for usage in different providers? Why do we need provider in _CLASS then?
> According the code on the first glance it seems that it is required that CLASS and INSTANCE must share in same provider.

   You will also have seen that the "default" macro TRACEPOINT_EVENT simply wraps both TRACEPOINT_EVENT_CLASS and TRACEPOINT_EVENT_INSTANCE together.  When used separately, the TRACEPOINT_EVENT_INSTANCE must match its template's params; the event class then takes care of the mapping of parameters to fields in the event output.  This allows you to declare a single event class somewhere, then declare various instances that vary by name only, typically because they're events of the same nature but occurring in varying contexts.  Having the trace label them under different names makes the analyst's life easier.

   Normally you use TRACEPOINT_EVENT_CLASS and _INSTANCE within the same provider, but you could theoretically have varying instances rely on different providers.  I guess this would allow you some flexibility in picking which sets of instances to enable/disable by picking which provider shared objects (.so) to preload or not.

   Kernel space has essentially the same macros under the names DECLARE_EVENT_CLASS and TRACE_EVENT, respectively.  You can see those at work in the lttng-modules package and in some kernel modules such as drivers/staging/android/binder_trace.h.  In the latter, for example, you see a binder_lock_class which is then instantiated as binder_lock, binder_locked, and binder_unlock.  These three events carry very different semantics, but they have precisely the same parameter signatures.  Grouping them under an event class avoids a lot of cutting-and-pasting and diminishes the risk of errors later on (e.g. if you had to modify the field layout of binder_lock and forgot to copy it to binder_unlock).

   "Why do we need provider in _CLASS then?"  Because the provider name is part of the fully-qualified event class name.  This allows different event classes (and event instances) to have the same short names within different providers.  You would be bound to run into collisions if all the event class or event instance names were global.

Daniel U. Thibault
Protection des systèmes et contremesures (PSC) | Systems Protection & Countermeasures (SPC)
Cyber sécurité pour les missions essentielles (CME) | Mission Critical Cyber Security (MCCS)
RDDC - Centre de recherches de Valcartier | DRDC - Valcartier Research Centre
2459 route de la Bravoure
Québec QC  G3J 1X5
CANADA
Vox : (418) 844-4000 x4245
Fax : (418) 844-4538
NAC : 918V QSDJ <http://www.travelgis.com/map.asp?addr=918V%20QSDJ>
Gouvernement du Canada | Government of Canada
<http://www.valcartier.drdc-rddc.gc.ca/>