doc/examples/trigger-on-event/README.md

   1 # Trigger notification example
   2
   3 ## Description
   4 This example is made-up of three executables.
   5
   6 ### `notification-client`
   7
   8 ```
   9 Usage: notification-client TRIGGER_NAME TRIGGER_NAME2 ...
  10 ```
  11
  12 A simple client that subscribes to the notifications emitted by the `TRIGGER_NAME` trigger.
  13
  14 Multiple trigger names can be passed and subscribed to.
  15
  16
  17 ### `instrumented-app`
  18
  19 An application that emits the `trigger_example:my_event` event every 2 seconds.
  20
  21 ### `demo.sh`
  22
  23 This script adds a trigger named `demo_trigger` which emits a notification when
  24 the user-space `trigger_example:my_event` event occurs.
  25
  26 This script also adds a trigger named `demo_trigger_capture` which emits a
  27 notification when the user-space `trigger_example:my_event` event occurs and
  28 provides captured fields if present.
  29
  30 Once the triggers have been setup, the notification-client is launched to print
  31 all notifications emitted by the `demo_trigger` and `demo_trigger_capture`
  32 trigger.
  33
  34 ## Building
  35
  36 Simply run the included Makefile.
  37
  38 ## Running the example
  39
  40 1) Launch a session daemon using:
  41         ```
  42         $ lttng-sessiond
  43         ```
  44 2) Launch the `demo.sh` script
  45 3) Launch the `instrumented-app`
  46
  47 The following output should be produced:
  48
  49 ```
  50 $ ./demo.sh
  51 Registering a notification trigger named "demo_trigger" for the trigger_example:my_event user-space event
  52 Trigger registered successfully.
  53 Trigger registered successfully.
  54 Subscribed to notifications of trigger "demo_trigger_capture"
  55 Subscribed to notifications of trigger "demo_trigger"
  56 [08-24-2020] 17:20:33.598221 - Received notification of event rule trigger "demo_trigger"
  57 [08-24-2020] 17:20:33.598855 - Received notification of event rule trigger "demo_trigger_capture"
  58 Captured field values:
  59   Field: iteration Value: [Unsigned int] 0,
  60   Field: does_not_exist Value: Capture unavailable,
  61   Field: $ctx.vtid Value: [Unsigned int] 2302494,
  62   Field: $ctx.procname Value: [String] instrumented-ap.
  63 [08-24-2020] 17:20:35.598556 - Received notification of event rule trigger "demo_trigger"
  64 [08-24-2020] 17:20:35.599293 - Received notification of event rule trigger "demo_trigger_capture"
  65 Captured field values:
  66   Field: iteration Value: [Unsigned int] 1,
  67   Field: does_not_exist Value: Capture unavailable,
  68   Field: $ctx.vtid Value: [Unsigned int] 2302494,
  69   Field: $ctx.procname Value: [String] instrumented-ap.
  70 [08-24-2020] 17:20:37.598977 - Received notification of event rule trigger "demo_trigger"
  71 [08-24-2020] 17:20:37.599676 - Received notification of event rule trigger "demo_trigger_capture"
  72 Captured field values:
  73   Field: iteration Value: [Unsigned int] 2,
  74   Field: does_not_exist Value: Capture unavailable,
  75   Field: $ctx.vtid Value: [Unsigned int] 2302494,
  76   Field: $ctx.procname Value: [String] instrumented-ap.
  77 [08-24-2020] 17:20:39.599430 - Received notification of event rule trigger "demo_trigger"
  78 [08-24-2020] 17:20:39.600178 - Received notification of event rule trigger "demo_trigger_capture"
  79 Captured field values:
  80   Field: iteration Value: [Unsigned int] 3,
  81   Field: does_not_exist Value: Capture unavailable,
  82   Field: $ctx.vtid Value: [Unsigned int] 2302494,
  83   Field: $ctx.procname Value: [String] instrumented-ap.
  84 ...
  85 ```
  86
  87 ```
  88 $ ./instrumented-app
  89 [08-24-2020] 17:20:33.597441 - Tracing event "trigger_example:my_event"
  90 [08-24-2020] 17:20:35.597703 - Tracing event "trigger_example:my_event"
  91 [08-24-2020] 17:20:37.597997 - Tracing event "trigger_example:my_event"
  92 ...
  93 ```
  94
  95