include/lttng/condition/event-rule.h

   1 /*
   2  * Copyright (C) 2019 Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-only
   5  *
   6  */
   7
   8 #ifndef LTTNG_CONDITION_EVENT_RULE_H
   9 #define LTTNG_CONDITION_EVENT_RULE_H
  10
  11 #include <lttng/event-rule/event-rule.h>
  12 #include <lttng/condition/condition.h>
  13 #include <lttng/condition/evaluation.h>
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif
  18
  19 struct lttng_event_expr;
  20
  21 /**
  22  * Event rule conditions allows an action to be taken whenever an event matching
  23  * the event rule is hit by the tracers.
  24  *
  25  * An event rule condition can also specify a payload to be captured at runtime.
  26  * This is done via the capture descriptor.
  27  *
  28  * Note: the dynamic runtime capture of payload is only available for the
  29  *       trigger notification subsystem.
  30  */
  31
  32 /*
  33  * Create a newly allocated event rule condition.
  34  *
  35  * Returns a new condition on success, NULL on failure. This condition must be
  36  * destroyed using lttng_condition_destroy().
  37  */
  38 extern struct lttng_condition *lttng_condition_event_rule_create(
  39                 struct lttng_event_rule *rule);
  40
  41 /*
  42  * Get the rule property of a event rule condition.
  43  *
  44  * The caller does not assume the ownership of the returned rule. The
  45  * rule shall only be used for the duration of the condition's
  46  * lifetime.
  47  *
  48  * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's rule
  49  * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
  50  * parameter is passed. */
  51 extern enum lttng_condition_status lttng_condition_event_rule_get_rule(
  52                  const struct lttng_condition *condition,
  53                 const struct lttng_event_rule **rule);
  54
  55 /**
  56  * lttng_evaluation_event_rule_hit are specialised lttng_evaluations which
  57  * allow users to query a number of properties resulting from the evaluation
  58  * of a condition which evaluated to true.
  59  *
  60  * The evaluation of a event rule hit yields two different results:
  61  *    TEMPORARY - The name of the triggers associated with the condition.
  62  *    TODO - The captured event payload if any
  63  */
  64
  65 /*
  66  * Get the trigger name property of a event rule hit evaluation.
  67  *
  68  * Returns LTTNG_EVALUATION_STATUS_OK on success and a trigger name
  69  * or LTTNG_EVALUATION_STATUS_INVALID if
  70  * an invalid parameter is passed.
  71  */
  72 extern enum lttng_evaluation_status
  73 lttng_evaluation_event_rule_get_trigger_name(
  74                 const struct lttng_evaluation *evaluation,
  75                 const char **name);
  76
  77 /*
  78  * Appends (transfering the ownership) the capture descriptor `expr` to
  79  * the event rule condition `condition`.
  80  *
  81  * Returns:
  82  *
  83  * `LTTNG_CONDITION_STATUS_OK`:
  84  *     Success.
  85  *
  86  * `LTTNG_CONDITION_STATUS_ERROR`:
  87  *     Memory error.
  88  *
  89  * `LTTNG_CONDITION_STATUS_INVALID`:
  90  *     * `condition` is `NULL`.
  91  *     * The type of `condition` is not
  92  *       `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
  93  *     * `expr` is `NULL`.
  94  *     * `expr` is not a locator expression, that is, its type is not
  95  *       one of:
  96  *
  97  *       * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`
  98  *       * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`
  99  *       * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`
 100  *       * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`
 101  */
 102 extern enum lttng_condition_status
 103 lttng_condition_event_rule_append_capture_descriptor(
 104                 struct lttng_condition *condition,
 105                 struct lttng_event_expr *expr);
 106
 107 /*
 108  * Sets `*count` to the number of capture descriptors in the event rule
 109  * condition `condition`.
 110  *
 111  * Returns:
 112  *
 113  * `LTTNG_CONDITION_STATUS_OK`:
 114  *     Success.
 115  *
 116  * `LTTNG_CONDITION_STATUS_INVALID`:
 117  *     * `condition` is `NULL`.
 118  *     * The type of `condition` is not
 119  *       `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
 120  *     * `count` is `NULL`.
 121  */
 122 extern enum lttng_condition_status
 123 lttng_condition_event_rule_get_capture_descriptor_count(
 124                 const struct lttng_condition *condition, unsigned int *count);
 125
 126 /*
 127  * Returns the capture descriptor (borrowed) of the event rule condition
 128  * `condition` at the index `index`, or `NULL` if:
 129  *
 130  * * `condition` is `NULL`.
 131  * * The type of `condition` is not
 132  *   `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
 133  * * `index` is greater than or equal to the number of capture
 134  *   descriptors in `condition` (as returned by
 135  *   lttng_condition_event_rule_get_capture_descriptor_count()).
 136  */
 137 extern const struct lttng_event_expr *
 138 lttng_condition_event_rule_get_capture_descriptor_at_index(
 139                 const struct lttng_condition *condition, unsigned int index);
 140
 141 #ifdef __cplusplus
 142 }
 143 #endif
 144
 145 #endif /* LTTNG_CONDITION_EVENT_RULE_H */