[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: LGPL-2.1-only
 *
 */

#ifndef LTTNG_ERROR_QUERY_H
#define LTTNG_ERROR_QUERY_H

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