src/daemon/utils_complain.h

   1 /**
   2  * collectd - src/utils_complain.h
   3  * Copyright (C) 2006-2013  Florian octo Forster
   4  * Copyright (C) 2008       Sebastian tokkee Harl
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a
   7  * copy of this software and associated documentation files (the "Software"),
   8  * to deal in the Software without restriction, including without limitation
   9  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  10  * and/or sell copies of the Software, and to permit persons to whom the
  11  * Software is furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included in
  14  * all copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  22  * DEALINGS IN THE SOFTWARE.
  23  *
  24  * Authors:
  25  *   Florian octo Forster <octo at collectd.org>
  26  *   Sebastian tokkee Harl <sh at tokkee.org>
  27  **/
  28
  29 #ifndef UTILS_COMPLAIN_H
  30 #define UTILS_COMPLAIN_H 1
  31
  32 #include "utils_time.h"
  33
  34 typedef struct {
  35   /* time of the last report */
  36   cdtime_t last;
  37
  38   /* How long to wait until reporting again.
  39    * 0 indicates that the complaint is no longer valid. */
  40   cdtime_t interval;
  41
  42   bool complained_once;
  43 } c_complain_t;
  44
  45 #define C_COMPLAIN_INIT_STATIC                                                 \
  46   { 0, 0, 0 }
  47 #define C_COMPLAIN_INIT(c)                                                     \
  48   do {                                                                         \
  49     (c)->last = 0;                                                             \
  50     (c)->interval = 0;                                                         \
  51     (c)->complained_once = false;                                              \
  52   } while (0)
  53
  54 /*
  55  * NAME
  56  *   c_complain
  57  *
  58  * DESCRIPTION
  59  *   Complain about something. This function will report a message (usually
  60  *   indicating some error condition) using the collectd logging mechanism.
  61  *   When this function is called again, reporting the message again will be
  62  *   deferred by an increasing interval (up to one day) to prevent flooding
  63  *   the logs. A call to `c_release' resets the counter.
  64  *
  65  * PARAMETERS
  66  *   `level'  The log level passed to `plugin_log'.
  67  *   `c'      Identifier for the complaint.
  68  *   `format' Message format - see the documentation of printf(3).
  69  */
  70 __attribute__((format(printf, 3, 4))) void
  71 c_complain(int level, c_complain_t *c, const char *format, ...);
  72
  73 /*
  74  * NAME
  75  *   c_complain_once
  76  *
  77  * DESCRIPTION
  78  *   Complain about something once. This function will not report anything
  79  *   again, unless `c_release' has been called in between. If used after some
  80  *   calls to `c_complain', it will report again on the next interval and stop
  81  *   after that.
  82  *
  83  *   See `c_complain' for further details and a description of the parameters.
  84  */
  85 __attribute__((format(printf, 3, 4))) void
  86 c_complain_once(int level, c_complain_t *c, const char *format, ...);
  87
  88 /*
  89  * NAME
  90  *   c_would_release
  91  *
  92  * DESCRIPTION
  93  *   Returns true if the specified complaint would be released, false else.
  94  */
  95 #define c_would_release(c) ((c)->interval != 0)
  96
  97 /*
  98  * NAME
  99  *   c_release
 100  *
 101  * DESCRIPTION
 102  *   Release a complaint. This will report a message once, marking the
 103  *   complaint as released.
 104  *
 105  *   See `c_complain' for a description of the parameters.
 106  */
 107 __attribute__((format(printf, 3, 4))) void
 108 c_do_release(int level, c_complain_t *c, const char *format, ...);
 109 #define c_release(level, c, ...)                                               \
 110   do {                                                                         \
 111     if (c_would_release(c))                                                    \
 112       c_do_release(level, c, __VA_ARGS__);                                     \
 113   } while (0)
 114
 115 #endif /* UTILS_COMPLAIN_H */