[lttng-tools.git] / include / lttng / error-query.h

/*
 * error-query.h
 *
 * Copyright (C) 2021 Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * SPDX-License-Identifier: GPL-2.1-only
 *
 */

#ifndef LTTNG_ERROR_QUERY_H
#define LTTNG_ERROR_QUERY_H

#include <lttng/lttng.h>
#include <lttng/lttng-export.h>
#include <lttng/trigger/trigger.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* An error query. */
struct lttng_error_query;

/*
 * A collection of "lttng_error_query_result" returned after executing an error
 * query against an endpoint.
 */
struct lttng_error_query_results;

/* A 'result' is an opaque error type. */
struct lttng_error_query_result;

enum lttng_error_query_status {
	LTTNG_ERROR_QUERY_STATUS_OK = 0,
	/* An error occurred while querying for errors. */
	LTTNG_ERROR_QUERY_STATUS_ERROR = -1,
	/* The target of the query does not make sense for this endpoint. */
	LTTNG_ERROR_QUERY_STATUS_INVALID_QUERY_TARGET = -2,
	LTTNG_ERROR_QUERY_STATUS_INVALID_PARAMETER = -3,
};

enum lttng_error_query_result_type {
	/* A count of errors provided as an unsigned integral value. */
	LTTNG_ERROR_QUERY_RESULT_TYPE_COUNTER = 0,
	LTTNG_ERROR_QUERY_RESULT_TYPE_UNKNOWN = -1,
};

enum lttng_error_query_result_status {
	LTTNG_ERROR_QUERY_RESULT_STATUS_OK = 0,
	LTTNG_ERROR_QUERY_RESULT_STATUS_ERROR = -1,
	LTTNG_ERROR_QUERY_RESULT_STATUS_INVALID_PARAMETER = -2,
};

enum lttng_error_query_results_status {
	LTTNG_ERROR_QUERY_RESULTS_STATUS_OK = 0,
	LTTNG_ERROR_QUERY_RESULTS_STATUS_ERROR = -1,
	LTTNG_ERROR_QUERY_RESULTS_STATUS_INVALID_PARAMETER = -2,
};

/* Create an error query targetting a trigger object. */
LTTNG_EXPORT extern struct lttng_error_query *lttng_error_query_trigger_create(
		const struct lttng_trigger *trigger);

/* Create an error query targetting a trigger's condition object. */
LTTNG_EXPORT extern struct lttng_error_query *lttng_error_query_condition_create(
		const struct lttng_trigger *trigger);

/*
 * Create an error query targetting an action object.
 *
 * `action_path` is copied internally. The root of the `action_path` is the
 * action of `trigger`.
 */
LTTNG_EXPORT extern struct lttng_error_query *lttng_error_query_action_create(
		const struct lttng_trigger *trigger,
		const struct lttng_action_path *action_path);

/* Destroy an error query. */
LTTNG_EXPORT extern void lttng_error_query_destroy(struct lttng_error_query *query);

/*
 * Run an error query against an endpoint.
 *
 * Currently, only the `lttng_session_daemon_command_endpoint` is supported,
 * see `lttng/endpoint.h`.
 */
LTTNG_EXPORT extern enum lttng_error_code lttng_error_query_execute(
		const struct lttng_error_query *query,
		const struct lttng_endpoint *endpoint,
		struct lttng_error_query_results **results);

/* Get the number of results in a result set. */
LTTNG_EXPORT LTTNG_EXPORT extern enum lttng_error_query_results_status
lttng_error_query_results_get_count(
		const struct lttng_error_query_results *results,
		unsigned int *count);

/* Get a result from a result set by index. */
LTTNG_EXPORT extern enum lttng_error_query_results_status
lttng_error_query_results_get_result(
		const struct lttng_error_query_results *results,
		const struct lttng_error_query_result **result,
		unsigned int index);

/* Destroy an error query result set. */
LTTNG_EXPORT extern void lttng_error_query_results_destroy(
		struct lttng_error_query_results *results);

/* Get the type of an error query result. */
LTTNG_EXPORT extern enum lttng_error_query_result_type lttng_error_query_result_get_type(
		const struct lttng_error_query_result *result);

/* Get the name of result. */
LTTNG_EXPORT extern enum lttng_error_query_result_status lttng_error_query_result_get_name(
		const struct lttng_error_query_result *result,
		const char **name);

/* Get the description of a result. */
LTTNG_EXPORT extern enum lttng_error_query_result_status
lttng_error_query_result_get_description(
		const struct lttng_error_query_result *result,
		const char **description);

/* Get the value of an error counter. */
LTTNG_EXPORT extern enum lttng_error_query_result_status
lttng_error_query_result_counter_get_value(
		const struct lttng_error_query_result *result, uint64_t *value);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_ERROR_QUERY_H */
Commit	Line	Data
b99a0cb3 JG	1	/*
	2	* error-query.h
	3	*
	4	* Copyright (C) 2021 Jérémie Galarneau <jeremie.galarneau@efficios.com>
	5	*
	6	* SPDX-License-Identifier: GPL-2.1-only
	7	*
	8	*/
	9
	10	#ifndef LTTNG_ERROR_QUERY_H
	11	#define LTTNG_ERROR_QUERY_H
	12
	13	#include <lttng/lttng.h>
4bd69c5f	14	#include <lttng/lttng-export.h>
b99a0cb3 JG	15	#include <lttng/trigger/trigger.h>
	16	#include <stdint.h>
	17
	18	#ifdef __cplusplus
	19	extern "C" {
	20	#endif
	21
	22	/* An error query. */
	23	struct lttng_error_query;
	24
	25	/*
	26	* A collection of "lttng_error_query_result" returned after executing an error
	27	* query against an endpoint.
	28	*/
	29	struct lttng_error_query_results;
	30
	31	/* A 'result' is an opaque error type. */
	32	struct lttng_error_query_result;
	33
	34	enum lttng_error_query_status {
	35	LTTNG_ERROR_QUERY_STATUS_OK = 0,
	36	/* An error occurred while querying for errors. */
	37	LTTNG_ERROR_QUERY_STATUS_ERROR = -1,
	38	/* The target of the query does not make sense for this endpoint. */
	39	LTTNG_ERROR_QUERY_STATUS_INVALID_QUERY_TARGET = -2,
	40	LTTNG_ERROR_QUERY_STATUS_INVALID_PARAMETER = -3,
	41	};
	42
	43	enum lttng_error_query_result_type {
	44	/* A count of errors provided as an unsigned integral value. */
	45	LTTNG_ERROR_QUERY_RESULT_TYPE_COUNTER = 0,
	46	LTTNG_ERROR_QUERY_RESULT_TYPE_UNKNOWN = -1,
	47	};
	48
	49	enum lttng_error_query_result_status {
	50	LTTNG_ERROR_QUERY_RESULT_STATUS_OK = 0,
	51	LTTNG_ERROR_QUERY_RESULT_STATUS_ERROR = -1,
	52	LTTNG_ERROR_QUERY_RESULT_STATUS_INVALID_PARAMETER = -2,
	53	};
	54
	55	enum lttng_error_query_results_status {
	56	LTTNG_ERROR_QUERY_RESULTS_STATUS_OK = 0,
	57	LTTNG_ERROR_QUERY_RESULTS_STATUS_ERROR = -1,
	58	LTTNG_ERROR_QUERY_RESULTS_STATUS_INVALID_PARAMETER = -2,
	59	};
	60
	61	/* Create an error query targetting a trigger object. */
4bd69c5f	62	LTTNG_EXPORT extern struct lttng_error_query *lttng_error_query_trigger_create(
b99a0cb3 JG	63	const struct lttng_trigger *trigger);
b99a0cb3 JG	64
63dd3d7b	65	/* Create an error query targetting a trigger's condition object. */
4bd69c5f	66	LTTNG_EXPORT extern struct lttng_error_query *lttng_error_query_condition_create(
63dd3d7b JG	67	const struct lttng_trigger *trigger);
63dd3d7b JG	68
cb9222ff JG	69	/*
	70	* Create an error query targetting an action object.
	71	*
	72	* `action_path` is copied internally. The root of the `action_path` is the
	73	* action of `trigger`.
	74	*/
4bd69c5f	75	LTTNG_EXPORT extern struct lttng_error_query *lttng_error_query_action_create(
b99a0cb3	76	const struct lttng_trigger *trigger,
cb9222ff	77	const struct lttng_action_path *action_path);
b99a0cb3 JG	78
b99a0cb3 JG	79	/* Destroy an error query. */
4bd69c5f	80	LTTNG_EXPORT extern void lttng_error_query_destroy(struct lttng_error_query *query);
b99a0cb3 JG	81
	82	/*
	83	* Run an error query against an endpoint.
	84	*
	85	* Currently, only the `lttng_session_daemon_command_endpoint` is supported,
	86	* see `lttng/endpoint.h`.
	87	*/
4bd69c5f	88	LTTNG_EXPORT extern enum lttng_error_code lttng_error_query_execute(
b99a0cb3 JG	89	const struct lttng_error_query *query,
	90	const struct lttng_endpoint *endpoint,
	91	struct lttng_error_query_results **results);
	92
	93	/* Get the number of results in a result set. */
4bd69c5f	94	LTTNG_EXPORT LTTNG_EXPORT extern enum lttng_error_query_results_status
b99a0cb3 JG	95	lttng_error_query_results_get_count(
	96	const struct lttng_error_query_results *results,
	97	unsigned int *count);
	98
	99	/* Get a result from a result set by index. */
4bd69c5f	100	LTTNG_EXPORT extern enum lttng_error_query_results_status
b99a0cb3 JG	101	lttng_error_query_results_get_result(
	102	const struct lttng_error_query_results *results,
	103	const struct lttng_error_query_result **result,
	104	unsigned int index);
	105
	106	/* Destroy an error query result set. */
4bd69c5f	107	LTTNG_EXPORT extern void lttng_error_query_results_destroy(
b99a0cb3 JG	108	struct lttng_error_query_results *results);
	109
	110	/* Get the type of an error query result. */
4bd69c5f	111	LTTNG_EXPORT extern enum lttng_error_query_result_type lttng_error_query_result_get_type(
b99a0cb3 JG	112	const struct lttng_error_query_result *result);
	113
	114	/* Get the name of result. */
4bd69c5f	115	LTTNG_EXPORT extern enum lttng_error_query_result_status lttng_error_query_result_get_name(
b99a0cb3 JG	116	const struct lttng_error_query_result *result,
	117	const char **name);
	118
	119	/* Get the description of a result. */
4bd69c5f	120	LTTNG_EXPORT extern enum lttng_error_query_result_status
b99a0cb3 JG	121	lttng_error_query_result_get_description(
	122	const struct lttng_error_query_result *result,
	123	const char **description);
	124
	125	/* Get the value of an error counter. */
4bd69c5f	126	LTTNG_EXPORT extern enum lttng_error_query_result_status
b99a0cb3 JG	127	lttng_error_query_result_counter_get_value(
	128	const struct lttng_error_query_result result, uint64_t value);
	129
	130	#ifdef __cplusplus
	131	}
	132	#endif
	133
	134	#endif /* LTTNG_ERROR_QUERY_H */