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 /*
  65  * Create an error query targetting an action object.
  66  *
  67  * `action_path` is copied internally. The root of the `action_path` is the
  68  * action of `trigger`.
  69  */
  70 extern struct lttng_error_query *lttng_error_query_action_create(
  71                 const struct lttng_trigger *trigger,
  72                 const struct lttng_action_path *action_path);
  73
  74 /* Destroy an error query. */
  75 extern void lttng_error_query_destroy(struct lttng_error_query *query);
  76
  77 /*
  78  * Run an error query against an endpoint.
  79  *
  80  * Currently, only the `lttng_session_daemon_command_endpoint` is supported,
  81  * see `lttng/endpoint.h`.
  82  */
  83 extern enum lttng_error_code lttng_error_query_execute(
  84                 const struct lttng_error_query *query,
  85                 const struct lttng_endpoint *endpoint,
  86                 struct lttng_error_query_results **results);
  87
  88 /* Get the number of results in a result set. */
  89 extern enum lttng_error_query_results_status
  90 lttng_error_query_results_get_count(
  91                 const struct lttng_error_query_results *results,
  92                 unsigned int *count);
  93
  94 /* Get a result from a result set by index. */
  95 extern enum lttng_error_query_results_status
  96 lttng_error_query_results_get_result(
  97                 const struct lttng_error_query_results *results,
  98                 const struct lttng_error_query_result **result,
  99                 unsigned int index);
 100
 101 /* Destroy an error query result set. */
 102 extern void lttng_error_query_results_destroy(
 103                 struct lttng_error_query_results *results);
 104
 105 /* Get the type of an error query result. */
 106 extern enum lttng_error_query_result_type lttng_error_query_result_get_type(
 107                 const struct lttng_error_query_result *result);
 108
 109 /* Get the name of result. */
 110 extern enum lttng_error_query_result_status lttng_error_query_result_get_name(
 111                 const struct lttng_error_query_result *result,
 112                 const char **name);
 113
 114 /* Get the description of a result. */
 115 extern enum lttng_error_query_result_status
 116 lttng_error_query_result_get_description(
 117                 const struct lttng_error_query_result *result,
 118                 const char **description);
 119
 120 /* Get the value of an error counter. */
 121 extern enum lttng_error_query_result_status
 122 lttng_error_query_result_counter_get_value(
 123                 const struct lttng_error_query_result *result, uint64_t *value);
 124
 125 #ifdef __cplusplus
 126 }
 127 #endif
 128
 129 #endif /* LTTNG_ERROR_QUERY_H */