doc/developer/tpvsmk.txt

   1
   2 Mathieu Desnoyers and Michel Dagenais, January 19, 2009
   3
   4 Markers vs Tracepoints :
   5
   6 What markers are good for :
   7
   8 * One-liner instrumentation of kernel code. (fast debug-style instrumentation)
   9 * Specify the basic data types exported by the tracer in a format string placed into the marker.
  10 * Exports those format strings along with the trace metadata so the event types are automatically identified.
  11
  12 What they are _not_ good for :
  13
  14 * Cannot identify more complex data type to be presented to a specialized tracer (e.g. pointer to a struct task_struct).
  15 * Lack of declaration of kernel instrumentation in a global header.  Presence in a global header could make it easier for someone to quickly review the list of markers, especially if "git grep trace_mark" is not satisfactory.
  16 * Markers are mostly aimed at LTTng, which takes the data identified by the marker and sends it to the trace buffers directly. It's less convenient for specialized tracers such as ftrace, kmemtrace, blktrace because those tracers need to access more complex types to do more work on the data (e.g. filtering) before it is either written to the trace or used to generate statistics.
  17   - LTTng tracing buffer format API is available here :
  18     http://git.kernel.org/?p=linux/kernel/git/compudj/linux-2.6-lttng.git;a=blob;f=ltt/probes/ltt-type-serializer.h
  19     With usage examples here :
  20     http://git.kernel.org/?p=linux/kernel/git/compudj/linux-2.6-lttng.git;a=blob;f=ltt/probes/kernel-trace.c
  21
  22 * Markers are tying the inner kernel instrumentation to the exported userspace "API".  (It's not an actual Application Programming Interface to user space, but a potential data stream that might be construed as long-lasting as /proc file formats.) This is actually one of their worse aspect in terms of kernel development. No developer will want to add new markers in their code if they know it will fix a new interface exported to userspace.
  23
  24 Tracepoints address those issues by adding a layer which separates the
  25 instrumentation from the binary representation of the event in the trace.
  26 Tracepoints are meant to stay an in-kernel API which is never exported
  27 to userspace, which makes it easier to adapt and change when the kernel
  28 code evolves. Markers are now used to declare the events in the form
  29 they will be written into the trace, which does not necessarily
  30 correspond to the way the instrumentation will appear in the kernel
  31 code.
  32
  33 So, typically, a "standardized" event will appear in the kernel code
  34 with a tracepoint declared in a global header in include/trace/subsys.h
  35 which is easy to manage by the kernel community. It will then be
  36 inserted into the core kernel code. Tracers can then connect on this
  37 event source to do any type of work they need to do in their callback,
  38 including marker invocation to record data in the trace. Tracepoint name
  39 should start with the name of the header in which it is located (e.g. subsys_).
  40
  41 Tracepoints allows kernel modules (tracers) to connected multiple callbacks on
  42 a given tracepoint. Tracepoints also have a low impact on system performance
  43 when no probe is connected, exactly like markers.
  44