contrib/bind/lib/dns/include/dns/stats.h

   1 /*
   2  * Copyright (C) 2004-2009  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000, 2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and/or distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: stats.h,v 1.13.128.7 2009/01/29 23:47:13 tbox Exp $ */
  19
  20 #ifndef DNS_STATS_H
  21 #define DNS_STATS_H 1
  22
  23 /*! \file dns/stats.h */
  24
  25 #include <dns/types.h>
  26
  27 /*%
  28  * Statistics counters.  Used as isc_statscounter_t values.
  29  */
  30 enum {
  31         /*%
  32          * Resolver statistics counters.
  33          */
  34         dns_resstatscounter_queryv4 = 0,
  35         dns_resstatscounter_queryv6 = 1,
  36         dns_resstatscounter_responsev4 = 2,
  37         dns_resstatscounter_responsev6 = 3,
  38         dns_resstatscounter_nxdomain = 4,
  39         dns_resstatscounter_servfail = 5,
  40         dns_resstatscounter_formerr = 6,
  41         dns_resstatscounter_othererror = 7,
  42         dns_resstatscounter_edns0fail = 8,
  43         dns_resstatscounter_mismatch = 9,
  44         dns_resstatscounter_truncated = 10,
  45         dns_resstatscounter_lame = 11,
  46         dns_resstatscounter_retry = 12,
  47         dns_resstatscounter_gluefetchv4 = 13,
  48         dns_resstatscounter_gluefetchv6 = 14,
  49         dns_resstatscounter_gluefetchv4fail = 15,
  50         dns_resstatscounter_gluefetchv6fail = 16,
  51         dns_resstatscounter_val = 17,
  52         dns_resstatscounter_valsuccess = 18,
  53         dns_resstatscounter_valnegsuccess = 19,
  54         dns_resstatscounter_valfail = 20,
  55         dns_resstatscounter_dispabort = 21,
  56         dns_resstatscounter_dispsockfail = 22,
  57         dns_resstatscounter_querytimeout = 23,
  58         dns_resstatscounter_queryrtt0 = 24,
  59         dns_resstatscounter_queryrtt1 = 25,
  60         dns_resstatscounter_queryrtt2 = 26,
  61         dns_resstatscounter_queryrtt3 = 27,
  62         dns_resstatscounter_queryrtt4 = 28,
  63         dns_resstatscounter_queryrtt5 = 29,
  64
  65         dns_resstatscounter_max = 30,
  66
  67         /*%
  68          * Zone statistics counters.
  69          */
  70         dns_zonestatscounter_notifyoutv4 = 0,
  71         dns_zonestatscounter_notifyoutv6 = 1,
  72         dns_zonestatscounter_notifyinv4 = 2,
  73         dns_zonestatscounter_notifyinv6 = 3,
  74         dns_zonestatscounter_notifyrej = 4,
  75         dns_zonestatscounter_soaoutv4 = 5,
  76         dns_zonestatscounter_soaoutv6 = 6,
  77         dns_zonestatscounter_axfrreqv4 = 7,
  78         dns_zonestatscounter_axfrreqv6 = 8,
  79         dns_zonestatscounter_ixfrreqv4 = 9,
  80         dns_zonestatscounter_ixfrreqv6 = 10,
  81         dns_zonestatscounter_xfrsuccess = 11,
  82         dns_zonestatscounter_xfrfail = 12,
  83
  84         dns_zonestatscounter_max = 13,
  85
  86         /*%
  87         * Query statistics counters (obsolete).
  88         */
  89         dns_statscounter_success = 0,    /*%< Successful lookup */
  90         dns_statscounter_referral = 1,   /*%< Referral result */
  91         dns_statscounter_nxrrset = 2,    /*%< NXRRSET result */
  92         dns_statscounter_nxdomain = 3,   /*%< NXDOMAIN result */
  93         dns_statscounter_recursion = 4,  /*%< Recursion was used */
  94         dns_statscounter_failure = 5,    /*%< Some other failure */
  95         dns_statscounter_duplicate = 6,  /*%< Duplicate query */
  96         dns_statscounter_dropped = 7     /*%< Duplicate query (dropped) */
  97 };
  98
  99 #define DNS_STATS_NCOUNTERS 8
 100
 101 #if 0
 102 /*%<
 103  * Flag(s) for dns_xxxstats_dump().  DNS_STATSDUMP_VERBOSE is obsolete.
 104  * ISC_STATSDUMP_VERBOSE should be used instead.  These two values are
 105  * intentionally defined to be the same value to ensure binary compatibility.
 106  */
 107 #define DNS_STATSDUMP_VERBOSE   0x00000001 /*%< dump 0-value counters */
 108 #endif
 109
 110 /*%<
 111  * (Obsoleted)
 112  */
 113 LIBDNS_EXTERNAL_DATA extern const char *dns_statscounter_names[];
 114
 115 /*%
 116  * Attributes for statistics counters of RRset and Rdatatype types.
 117  *
 118  * _OTHERTYPE
 119  *      The rdata type is not explicitly supported and the corresponding counter
 120  *      is counted for other such types, too.  When this attribute is set,
 121  *      the base type is of no use.
 122  *
 123  * _NXRRSET
 124  *      RRset type counters only.  Indicates the RRset is non existent.
 125  *
 126  * _NXDOMAIN
 127  *      RRset type counters only.  Indicates a non existent name.  When this
 128  *      attribute is set, the base type is of no use.
 129  */
 130 #define DNS_RDATASTATSTYPE_ATTR_OTHERTYPE       0x0001
 131 #define DNS_RDATASTATSTYPE_ATTR_NXRRSET         0x0002
 132 #define DNS_RDATASTATSTYPE_ATTR_NXDOMAIN        0x0004
 133
 134 /*%<
 135  * Conversion macros among dns_rdatatype_t, attributes and isc_statscounter_t.
 136  */
 137 #define DNS_RDATASTATSTYPE_BASE(type)   ((dns_rdatatype_t)((type) & 0xFFFF))
 138 #define DNS_RDATASTATSTYPE_ATTR(type)   ((type) >> 16)
 139 #define DNS_RDATASTATSTYPE_VALUE(b, a)  (((a) << 16) | (b))
 140
 141 /*%<
 142  * Types of dump callbacks.
 143  */
 144 typedef void (*dns_generalstats_dumper_t)(isc_statscounter_t, isc_uint64_t,
 145                                           void *);
 146 typedef void (*dns_rdatatypestats_dumper_t)(dns_rdatastatstype_t, isc_uint64_t,
 147                                             void *);
 148 typedef void (*dns_opcodestats_dumper_t)(dns_opcode_t, isc_uint64_t, void *);
 149
 150 isc_result_t
 151 dns_generalstats_create(isc_mem_t *mctx, dns_stats_t **statsp, int ncounters);
 152 /*%<
 153  * Create a statistics counter structure of general type.  It counts a general
 154  * set of counters indexed by an ID between 0 and ncounters -1.
 155  * This function is obsolete.  A more general function, isc_stats_create(),
 156  * should be used.
 157  *
 158  * Requires:
 159  *\li   'mctx' must be a valid memory context.
 160  *
 161  *\li   'statsp' != NULL && '*statsp' == NULL.
 162  *
 163  * Returns:
 164  *\li   ISC_R_SUCCESS   -- all ok
 165  *
 166  *\li   anything else   -- failure
 167  */
 168
 169 isc_result_t
 170 dns_rdatatypestats_create(isc_mem_t *mctx, dns_stats_t **statsp);
 171 /*%<
 172  * Create a statistics counter structure per rdatatype.
 173  *
 174  * Requires:
 175  *\li   'mctx' must be a valid memory context.
 176  *
 177  *\li   'statsp' != NULL && '*statsp' == NULL.
 178  *
 179  * Returns:
 180  *\li   ISC_R_SUCCESS   -- all ok
 181  *
 182  *\li   anything else   -- failure
 183  */
 184
 185 isc_result_t
 186 dns_rdatasetstats_create(isc_mem_t *mctx, dns_stats_t **statsp);
 187 /*%<
 188  * Create a statistics counter structure per RRset.
 189  *
 190  * Requires:
 191  *\li   'mctx' must be a valid memory context.
 192  *
 193  *\li   'statsp' != NULL && '*statsp' == NULL.
 194  *
 195  * Returns:
 196  *\li   ISC_R_SUCCESS   -- all ok
 197  *
 198  *\li   anything else   -- failure
 199  */
 200
 201 isc_result_t
 202 dns_opcodestats_create(isc_mem_t *mctx, dns_stats_t **statsp);
 203 /*%<
 204  * Create a statistics counter structure per opcode.
 205  *
 206  * Requires:
 207  *\li   'mctx' must be a valid memory context.
 208  *
 209  *\li   'statsp' != NULL && '*statsp' == NULL.
 210  *
 211  * Returns:
 212  *\li   ISC_R_SUCCESS   -- all ok
 213  *
 214  *\li   anything else   -- failure
 215  */
 216
 217 void
 218 dns_stats_attach(dns_stats_t *stats, dns_stats_t **statsp);
 219 /*%<
 220  * Attach to a statistics set.
 221  *
 222  * Requires:
 223  *\li   'stats' is a valid dns_stats_t.
 224  *
 225  *\li   'statsp' != NULL && '*statsp' == NULL
 226  */
 227
 228 void
 229 dns_stats_detach(dns_stats_t **statsp);
 230 /*%<
 231  * Detaches from the statistics set.
 232  *
 233  * Requires:
 234  *\li   'statsp' != NULL and '*statsp' is a valid dns_stats_t.
 235  */
 236
 237 void
 238 dns_generalstats_increment(dns_stats_t *stats, isc_statscounter_t counter);
 239 /*%<
 240  * Increment the counter-th counter of stats.  This function is obsolete.
 241  * A more general function, isc_stats_increment(), should be used.
 242  *
 243  * Requires:
 244  *\li   'stats' is a valid dns_stats_t created by dns_generalstats_create().
 245  *
 246  *\li   counter is less than the maximum available ID for the stats specified
 247  *      on creation.
 248  */
 249
 250 void
 251 dns_rdatatypestats_increment(dns_stats_t *stats, dns_rdatatype_t type);
 252 /*%<
 253  * Increment the statistics counter for 'type'.
 254  *
 255  * Requires:
 256  *\li   'stats' is a valid dns_stats_t created by dns_rdatatypestats_create().
 257  */
 258
 259 void
 260 dns_rdatasetstats_increment(dns_stats_t *stats, dns_rdatastatstype_t rrsettype);
 261 /*%<
 262  * Increment the statistics counter for 'rrsettype'.
 263  *
 264  * Requires:
 265  *\li   'stats' is a valid dns_stats_t created by dns_rdatasetstats_create().
 266  */
 267
 268 void
 269 dns_rdatasetstats_decrement(dns_stats_t *stats, dns_rdatastatstype_t rrsettype);
 270 /*%<
 271  * Decrement the statistics counter for 'rrsettype'.
 272  *
 273  * Requires:
 274  *\li   'stats' is a valid dns_stats_t created by dns_rdatasetstats_create().
 275  */
 276
 277 void
 278 dns_opcodestats_increment(dns_stats_t *stats, dns_opcode_t code);
 279 /*%<
 280  * Increment the statistics counter for 'code'.
 281  *
 282  * Requires:
 283  *\li   'stats' is a valid dns_stats_t created by dns_opcodestats_create().
 284  */
 285
 286 void
 287 dns_generalstats_dump(dns_stats_t *stats, dns_generalstats_dumper_t dump_fn,
 288                       void *arg, unsigned int options);
 289 /*%<
 290  * Dump the current statistics counters in a specified way.  For each counter
 291  * in stats, dump_fn is called with its current value and the given argument
 292  * arg.  By default counters that have a value of 0 is skipped; if options has
 293  * the ISC_STATSDUMP_VERBOSE flag, even such counters are dumped.
 294  *
 295  * This function is obsolete.  A more general function, isc_stats_dump(),
 296  * should be used.
 297  *
 298  * Requires:
 299  *\li   'stats' is a valid dns_stats_t created by dns_generalstats_create().
 300  */
 301
 302 void
 303 dns_rdatatypestats_dump(dns_stats_t *stats, dns_rdatatypestats_dumper_t dump_fn,
 304                         void *arg, unsigned int options);
 305 /*%<
 306  * Dump the current statistics counters in a specified way.  For each counter
 307  * in stats, dump_fn is called with the corresponding type in the form of
 308  * dns_rdatastatstype_t, the current counter value and the given argument
 309  * arg.  By default counters that have a value of 0 is skipped; if options has
 310  * the ISC_STATSDUMP_VERBOSE flag, even such counters are dumped.
 311  *
 312  * Requires:
 313  *\li   'stats' is a valid dns_stats_t created by dns_generalstats_create().
 314  */
 315
 316 void
 317 dns_rdatasetstats_dump(dns_stats_t *stats, dns_rdatatypestats_dumper_t dump_fn,
 318                        void *arg, unsigned int options);
 319 /*%<
 320  * Dump the current statistics counters in a specified way.  For each counter
 321  * in stats, dump_fn is called with the corresponding type in the form of
 322  * dns_rdatastatstype_t, the current counter value and the given argument
 323  * arg.  By default counters that have a value of 0 is skipped; if options has
 324  * the ISC_STATSDUMP_VERBOSE flag, even such counters are dumped.
 325  *
 326  * Requires:
 327  *\li   'stats' is a valid dns_stats_t created by dns_generalstats_create().
 328  */
 329
 330 void
 331 dns_opcodestats_dump(dns_stats_t *stats, dns_opcodestats_dumper_t dump_fn,
 332                      void *arg, unsigned int options);
 333 /*%<
 334  * Dump the current statistics counters in a specified way.  For each counter
 335  * in stats, dump_fn is called with the corresponding opcode, the current
 336  * counter value and the given argument arg.  By default counters that have a
 337  * value of 0 is skipped; if options has the ISC_STATSDUMP_VERBOSE flag, even
 338  * such counters are dumped.
 339  *
 340  * Requires:
 341  *\li   'stats' is a valid dns_stats_t created by dns_generalstats_create().
 342  */
 343
 344 isc_result_t
 345 dns_stats_alloccounters(isc_mem_t *mctx, isc_uint64_t **ctrp);
 346 /*%<
 347  * Allocate an array of query statistics counters from the memory
 348  * context 'mctx'.
 349  *
 350  * This function is obsoleted.  Use dns_xxxstats_create() instead.
 351  */
 352
 353 void
 354 dns_stats_freecounters(isc_mem_t *mctx, isc_uint64_t **ctrp);
 355 /*%<
 356  * Free an array of query statistics counters allocated from the memory
 357  * context 'mctx'.
 358  *
 359  * This function is obsoleted.  Use dns_stats_destroy() instead.
 360  */
 361
 362 ISC_LANG_ENDDECLS
 363
 364 #endif /* DNS_STATS_H */