doc/proposals/0005-testpoint-mechanism.txt

   1 RFC - Testpoint mechanism
   2
   3 Author: Christian Babeux <christian.babeux@efficios.com>
   4
   5 Contributors:
   6         * Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   7
   8 Version:
   9         - v0.1: 11/09/2012
  10                 * Initial proposal
  11
  12 Motivation
  13 ----------
  14
  15 The main goal behind the testpoint mechanism is to be able to test and
  16 validate failure cases in different portion of the LTTng codebase. It
  17 could also be used by developers as a debugging aid.
  18
  19 By injecting code at runtime in the lttng daemons/processes/executables,
  20 we can painlessly trigger faulty behavior, test errors paths or even
  21 reproduce race conditions by introducing or exacerbating delays between
  22 threads.
  23
  24 Requirements
  25 ------------
  26
  27 The testpoint mechanism should be able to be triggered via scripts to
  28 automate testing efforts.
  29
  30 Ideally, the testpoint mechanism should *NOT* incur a significant
  31 performance hit if we want to leave it always on, in a similar fashion
  32 to the assert() macros.
  33
  34 By leaving it always on, any user is able to use our tests and validate
  35 the behavior of his installation via a simple 'make check' execution.
  36
  37 Proposed solution
  38 -----------------
  39
  40 This patch introduce two new macros: TESTPOINT_DECL(name)
  41 and testpoint(name).
  42
  43 Here a quick example that shows how to use the testpoint mechanism:
  44
  45 file: main.c
  46 #include <stdio.h>
  47 #include <common/testpoint/testpoint/testpoint.h>
  48
  49 /* Testpoint declaration */
  50 TESTPOINT_DECL(interesting_function)
  51
  52 void interesting_function(void)
  53 {
  54         testpoint(interesting_function);
  55         /* Some processing that can fail */
  56         ...
  57 }
  58
  59 int main(int argc, char *argv[])
  60 {
  61         interesting_function();
  62         ...
  63         printf("End");
  64 }
  65
  66 file: testpoint.c
  67 #include <stdio.h>
  68 void __testpoint_interesting_function(void)
  69 {
  70         printf("In testpoint of interesting function!");
  71 }
  72
  73 Compile:
  74 gcc -o test main.c
  75 gcc -fPIC -shared -o testpoint.so testpoint.c
  76
  77 Run:
  78 > ./test
  79   End
  80 > export LTTNG_TESTPOINT_ENABLE=1
  81 > LD_PRELOAD=testpoint.so ./test
  82   In testpoint of interesting function!
  83   End
  84 > export LTTNG_TESTPOINT_ENABLE=0
  85 > LD_PRELOAD=testpoint.so ./test
  86   End
  87
  88 The testpoint mechanism is triggered via the preloading of a shared
  89 object containing the appropriate testpoint symbols and by setting the
  90 LTTNG_TESTPOINT_ENABLE environment variable.
  91
  92 The check on this environment variable is done on the application
  93 startup with the help of a constructor (lttng_testpoint_check) which
  94 toggle a global state variable indicating whether or not the testpoints
  95 should be activated.
  96
  97 When enabled, the testpoint() macro calls an underlying wrapper specific
  98 to the testpoint and simply try to lookup the testpoint symbol via a
  99 dlsym() call.
 100
 101 When disabled, the testpoint() call will only incur an additionnal test
 102 per testpoint on a global variable. This performance 'hit' should be
 103 acceptable for production use.
 104
 105 As stated previously, the testpoint mechanism should be *always on*.  It
 106 can be explicitly disabled via CFLAGS="-DNTESTPOINT" in a way similar to
 107 NDEBUG and assert().