include/lttng/error-query.h

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