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/lttng-export.h>
  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. */
  62 LTTNG_EXPORT extern struct lttng_error_query *lttng_error_query_trigger_create(
  63                 const struct lttng_trigger *trigger);
  64
  65 /* Create an error query targetting a trigger's condition object. */
  66 LTTNG_EXPORT extern struct lttng_error_query *lttng_error_query_condition_create(
  67                 const struct lttng_trigger *trigger);
  68
  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  */
  75 LTTNG_EXPORT extern struct lttng_error_query *lttng_error_query_action_create(
  76                 const struct lttng_trigger *trigger,
  77                 const struct lttng_action_path *action_path);
  78
  79 /* Destroy an error query. */
  80 LTTNG_EXPORT extern void lttng_error_query_destroy(struct lttng_error_query *query);
  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  */
  88 LTTNG_EXPORT extern enum lttng_error_code lttng_error_query_execute(
  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. */
  94 LTTNG_EXPORT LTTNG_EXPORT extern enum lttng_error_query_results_status
  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. */
 100 LTTNG_EXPORT extern enum lttng_error_query_results_status
 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. */
 107 LTTNG_EXPORT extern void lttng_error_query_results_destroy(
 108                 struct lttng_error_query_results *results);
 109
 110 /* Get the type of an error query result. */
 111 LTTNG_EXPORT extern enum lttng_error_query_result_type lttng_error_query_result_get_type(
 112                 const struct lttng_error_query_result *result);
 113
 114 /* Get the name of result. */
 115 LTTNG_EXPORT extern enum lttng_error_query_result_status lttng_error_query_result_get_name(
 116                 const struct lttng_error_query_result *result,
 117                 const char **name);
 118
 119 /* Get the description of a result. */
 120 LTTNG_EXPORT extern enum lttng_error_query_result_status
 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. */
 126 LTTNG_EXPORT extern enum lttng_error_query_result_status
 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 */