[lttng-tools.git] / include / lttng / condition / event-rule.h

/*
 * Copyright (C) 2019 Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef LTTNG_CONDITION_EVENT_RULE_H
#define LTTNG_CONDITION_EVENT_RULE_H

#include <lttng/event-rule/event-rule.h>
#include <lttng/condition/condition.h>
#include <lttng/condition/evaluation.h>

#ifdef __cplusplus
extern "C" {
#endif

struct lttng_event_expr;

/**
 * Event rule conditions allows an action to be taken whenever an event matching
 * the event rule is hit by the tracers.
 *
 * An event rule condition can also specify a payload to be captured at runtime.
 * This is done via the capture descriptor.
 *
 * Note: the dynamic runtime capture of payload is only available for the
 *       trigger notification subsystem.
 */

/*
 * Create a newly allocated event rule condition.
 *
 * Returns a new condition on success, NULL on failure. This condition must be
 * destroyed using lttng_condition_destroy().
 */
extern struct lttng_condition *lttng_condition_event_rule_create(
		struct lttng_event_rule *rule);

/*
 * Get the rule property of a event rule condition.
 *
 * The caller does not assume the ownership of the returned rule. The
 * rule shall only be used for the duration of the condition's
 * lifetime.
 *
 * Returns LTTNG_CONDITION_STATUS_OK and a pointer to the condition's rule
 * on success, LTTNG_CONDITION_STATUS_INVALID if an invalid
 * parameter is passed. */
extern enum lttng_condition_status lttng_condition_event_rule_get_rule(
		 const struct lttng_condition *condition,
		const struct lttng_event_rule **rule);

/**
 * lttng_evaluation_event_rule_hit are specialised lttng_evaluations which
 * allow users to query a number of properties resulting from the evaluation
 * of a condition which evaluated to true.
 *
 * The evaluation of a event rule hit yields two different results:
 *    TEMPORARY - The name of the triggers associated with the condition.
 *    TODO - The captured event payload if any
 */

/*
 * Get the trigger name property of a event rule hit evaluation.
 *
 * Returns LTTNG_EVALUATION_STATUS_OK on success and a trigger name
 * or LTTNG_EVALUATION_STATUS_INVALID if
 * an invalid parameter is passed.
 */
extern enum lttng_evaluation_status
lttng_evaluation_event_rule_get_trigger_name(
		const struct lttng_evaluation *evaluation,
		const char **name);

/*
 * Appends (transfering the ownership) the capture descriptor `expr` to
 * the event rule condition `condition`.
 *
 * Returns:
 *
 * `LTTNG_CONDITION_STATUS_OK`:
 *     Success.
 *
 * `LTTNG_CONDITION_STATUS_ERROR`:
 *     Memory error.
 *
 * `LTTNG_CONDITION_STATUS_INVALID`:
 *     * `condition` is `NULL`.
 *     * The type of `condition` is not
 *       `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
 *     * `expr` is `NULL`.
 *     * `expr` is not a locator expression, that is, its type is not
 *       one of:
 *
 *       * `LTTNG_EVENT_EXPR_TYPE_EVENT_PAYLOAD_FIELD`
 *       * `LTTNG_EVENT_EXPR_TYPE_CHANNEL_CONTEXT_FIELD`
 *       * `LTTNG_EVENT_EXPR_TYPE_APP_SPECIFIC_CONTEXT_FIELD`
 *       * `LTTNG_EVENT_EXPR_TYPE_ARRAY_FIELD_ELEMENT`
 */
extern enum lttng_condition_status
lttng_condition_event_rule_append_capture_descriptor(
		struct lttng_condition *condition,
		struct lttng_event_expr *expr);

/*
 * Sets `*count` to the number of capture descriptors in the event rule
 * condition `condition`.
 *
 * Returns:
 *
 * `LTTNG_CONDITION_STATUS_OK`:
 *     Success.
 *
 * `LTTNG_CONDITION_STATUS_INVALID`:
 *     * `condition` is `NULL`.
 *     * The type of `condition` is not
 *       `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
 *     * `count` is `NULL`.
 */
extern enum lttng_condition_status
lttng_condition_event_rule_get_capture_descriptor_count(
		const struct lttng_condition *condition, unsigned int *count);

/*
 * Returns the capture descriptor (borrowed) of the event rule condition
 * `condition` at the index `index`, or `NULL` if:
 *
 * * `condition` is `NULL`.
 * * The type of `condition` is not
 *   `LTTNG_CONDITION_TYPE_EVENT_RULE_HIT`.
 * * `index` is greater than or equal to the number of capture
 *   descriptors in `condition` (as returned by
 *   lttng_condition_event_rule_get_capture_descriptor_count()).
 */
extern const struct lttng_event_expr *
lttng_condition_event_rule_get_capture_descriptor_at_index(
		const struct lttng_condition *condition, unsigned int index);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_CONDITION_EVENT_RULE_H */
Commit	Line	Data
	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 */