SoW-2020-0002: Trace Hit Counters: trigger error reporting integration
[lttng-tools.git] / 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 struct lttng_event_field_value;
21
22 /**
23 * Event rule conditions allows an action to be taken whenever an event matching
24 * the event rule is hit by the tracers.
25 *
26 * An event rule condition can also specify payload to be captured at runtime.
27 * This is done via the capture descriptor.
28 *
29 * Note: the dynamic runtime capture of payload is only available for the
30 * trigger notification subsystem.
31 */
32
33 /*
34 * Create a newly allocated event rule condition.
35 *
36 * Returns a new condition on success, NULL on failure. This condition must be
37 * destroyed using lttng_condition_destroy().
38 */
39 extern struct lttng_condition *lttng_condition_event_rule_create(
40 struct lttng_event_rule *rule);
41
42 /*
43 * Get the rule property of a event rule condition.
44 *
45 * The caller does not assume the ownership of the returned rule. The
46 * rule shall only be used for the duration of the condition's
47 * lifetime.
48 *
49 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's rule
50 * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
51 * parameter is passed. */
52 extern enum lttng_condition_status lttng_condition_event_rule_get_rule(
53 const struct lttng_condition *condition, 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 * Sets `*field_val` to the array event field value of the event rule
79 * condition evaluation `evaluation` which contains its captured values.
80 *
81 * Returns:
82 *
83 * `LTTNG_EVALUATION_STATUS_OK`:
84 * Success.
85 *
86 * `*field_val` is an array event field value with a length of at
87 * least one.
88 *
89 * `LTTNG_EVALUATION_STATUS_INVALID`:
90 * * `evaluation` is `NULL`.
91 * * The type of the condition of `evaluation` is not
92 * `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
93 * * The condition of `evaluation` has no capture descriptors.
94 * * `field_val` is `NULL`.
95 */
96 extern enum lttng_evaluation_status
97 lttng_evaluation_get_captured_values(
98 const struct lttng_evaluation *evaluation,
99 const struct lttng_event_field_value **field_val);
100
101 /*
102 * Appends (transfering the ownership) the capture descriptor `expr` to
103 * the event rule condition `condition`.
104 *
105 * Returns:
106 *
107 * `LTTNG_CONDITION_STATUS_OK`:
108 * Success.
109 *
110 * `LTTNG_CONDITION_STATUS_ERROR`:
111 * Memory error.
112 *
113 * `LTTNG_CONDITION_STATUS_INVALID`:
114 * * `condition` is `NULL`.
115 * * The type of `condition` is not
116 * `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
117 * * `expr` is `NULL`.
118 * * `expr` is not a locator expression, that is, its type is not
119 * one of:
120 *
121 * * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`
122 * * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`
123 * * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`
124 * * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`
125 * `LTTNG_CONDITION_STATUS_UNSUPPORTED`:
126 * * The associated event-rule does not support runtime capture.
127 */
128 extern enum lttng_condition_status
129 lttng_condition_event_rule_append_capture_descriptor(
130 struct lttng_condition *condition,
131 struct lttng_event_expr *expr);
132
133 /*
134 * Sets `*count` to the number of capture descriptors in the event rule
135 * condition `condition`.
136 *
137 * Returns:
138 *
139 * `LTTNG_CONDITION_STATUS_OK`:
140 * Success.
141 *
142 * `LTTNG_CONDITION_STATUS_INVALID`:
143 * * `condition` is `NULL`.
144 * * The type of `condition` is not
145 * `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
146 * * `count` is `NULL`.
147 */
148 extern enum lttng_condition_status
149 lttng_condition_event_rule_get_capture_descriptor_count(
150 const struct lttng_condition *condition, unsigned int *count);
151
152 /*
153 * Returns the capture descriptor (borrowed) of the event rule condition
154 * `condition` at the index `index`, or `NULL` if:
155 *
156 * * `condition` is `NULL`.
157 * * The type of `condition` is not
158 * `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
159 * * `index` is greater than or equal to the number of capture
160 * descriptors in `condition` (as returned by
161 * lttng_condition_event_rule_get_capture_descriptor_count()).
162 */
163 extern const struct lttng_event_expr *
164 lttng_condition_event_rule_get_capture_descriptor_at_index(
165 const struct lttng_condition *condition, unsigned int index);
166
167 #ifdef __cplusplus
168 }
169 #endif
170
171 #endif /* LTTNG_CONDITION_EVENT_RULE_H */
This page took 0.051355 seconds and 5 git commands to generate.