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-export.h>
  14 #include <lttng/lttng.h>
  15 #include <lttng/trigger/trigger.h>
  16
  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. */
  63 LTTNG_EXPORT extern struct lttng_error_query *
  64 lttng_error_query_trigger_create(const struct lttng_trigger *trigger);
  65
  66 /* Create an error query targetting a trigger's condition object. */
  67 LTTNG_EXPORT extern struct lttng_error_query *
  68 lttng_error_query_condition_create(const struct lttng_trigger *trigger);
  69
  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  */
  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);
  79
  80 /* Destroy an error query. */
  81 LTTNG_EXPORT extern void lttng_error_query_destroy(struct lttng_error_query *query);
  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  */
  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);
  93
  94 /* Get the number of results in a result set. */
  95 LTTNG_EXPORT LTTNG_EXPORT extern enum lttng_error_query_results_status
  96 lttng_error_query_results_get_count(const struct lttng_error_query_results *results,
  97                                     unsigned int *count);
  98
  99 /* Get a result from a result set by index. */
 100 LTTNG_EXPORT extern enum lttng_error_query_results_status
 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);
 104
 105 /* Destroy an error query result set. */
 106 LTTNG_EXPORT extern void
 107 lttng_error_query_results_destroy(struct lttng_error_query_results *results);
 108
 109 /* Get the type of an error query result. */
 110 LTTNG_EXPORT extern enum lttng_error_query_result_type
 111 lttng_error_query_result_get_type(const struct lttng_error_query_result *result);
 112
 113 /* Get the name of result. */
 114 LTTNG_EXPORT extern enum lttng_error_query_result_status
 115 lttng_error_query_result_get_name(const struct lttng_error_query_result *result, const char **name);
 116
 117 /* Get the description of a result. */
 118 LTTNG_EXPORT extern enum lttng_error_query_result_status
 119 lttng_error_query_result_get_description(const struct lttng_error_query_result *result,
 120                                          const char **description);
 121
 122 /* Get the value of an error counter. */
 123 LTTNG_EXPORT extern enum lttng_error_query_result_status
 124 lttng_error_query_result_counter_get_value(const struct lttng_error_query_result *result,
 125                                            uint64_t *value);
 126
 127 #ifdef __cplusplus
 128 }
 129 #endif
 130
 131 #endif /* LTTNG_ERROR_QUERY_H */