doc/examples/trigger-condition-event-matches/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 ## Running the example
  35
  36 1) Launch a session daemon using:
  37         ```
  38         $ lttng-sessiond
  39         ```
  40 2) Launch the `demo.sh` script
  41 3) Launch the `instrumented-app`
  42
  43 The following output should be produced:
  44
  45 ```
  46 $ ./demo.sh
  47 Registering a notification trigger named "demo_trigger" for the trigger_example:my_event user-space event
  48 Trigger registered successfully.
  49 Trigger registered successfully.
  50 Subscribed to notifications of trigger "demo_trigger_capture"
  51 Subscribed to notifications of trigger "demo_trigger"
  52 [08-24-2020] 17:20:33.598221 - Received notification of event rule matches trigger "demo_trigger"
  53 [08-24-2020] 17:20:33.598855 - Received notification of event rule matches trigger "demo_trigger_capture"
  54 Captured field values:
  55   Field: iteration Value: [Unsigned int] 0,
  56   Field: does_not_exist Value: Capture unavailable,
  57   Field: $ctx.vtid Value: [Unsigned int] 2302494,
  58   Field: $ctx.procname Value: [String] instrumented-ap.
  59 [08-24-2020] 17:20:35.598556 - Received notification of event rule matches trigger "demo_trigger"
  60 [08-24-2020] 17:20:35.599293 - Received notification of event rule matches trigger "demo_trigger_capture"
  61 Captured field values:
  62   Field: iteration Value: [Unsigned int] 1,
  63   Field: does_not_exist Value: Capture unavailable,
  64   Field: $ctx.vtid Value: [Unsigned int] 2302494,
  65   Field: $ctx.procname Value: [String] instrumented-ap.
  66 [08-24-2020] 17:20:37.598977 - Received notification of event rule matches trigger "demo_trigger"
  67 [08-24-2020] 17:20:37.599676 - Received notification of event rule matches trigger "demo_trigger_capture"
  68 Captured field values:
  69   Field: iteration Value: [Unsigned int] 2,
  70   Field: does_not_exist Value: Capture unavailable,
  71   Field: $ctx.vtid Value: [Unsigned int] 2302494,
  72   Field: $ctx.procname Value: [String] instrumented-ap.
  73 [08-24-2020] 17:20:39.599430 - Received notification of event rule matches trigger "demo_trigger"
  74 [08-24-2020] 17:20:39.600178 - Received notification of event rule matches trigger "demo_trigger_capture"
  75 Captured field values:
  76   Field: iteration Value: [Unsigned int] 3,
  77   Field: does_not_exist Value: Capture unavailable,
  78   Field: $ctx.vtid Value: [Unsigned int] 2302494,
  79   Field: $ctx.procname Value: [String] instrumented-ap.
  80 ...
  81 ```
  82
  83 ```
  84 $ ./instrumented-app
  85 [08-24-2020] 17:20:33.597441 - Tracing event "trigger_example:my_event"
  86 [08-24-2020] 17:20:35.597703 - Tracing event "trigger_example:my_event"
  87 [08-24-2020] 17:20:37.597997 - Tracing event "trigger_example:my_event"
  88 ...
  89 ```
  90
  91