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

   1 /*
   2  * Copyright (C) 2004-2009, 2012  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$ */
  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          * DNSSEC stats.
  69          */
  70         dns_dnssecstats_asis = 0,
  71         dns_dnssecstats_downcase = 1,
  72         dns_dnssecstats_wildcard = 2,
  73         dns_dnssecstats_fail = 3,
  74
  75         dns_dnssecstats_max = 4,
  76
  77         /*%
  78          * Zone statistics counters.
  79          */
  80         dns_zonestatscounter_notifyoutv4 = 0,
  81         dns_zonestatscounter_notifyoutv6 = 1,
  82         dns_zonestatscounter_notifyinv4 = 2,
  83         dns_zonestatscounter_notifyinv6 = 3,
  84         dns_zonestatscounter_notifyrej = 4,
  85         dns_zonestatscounter_soaoutv4 = 5,
  86         dns_zonestatscounter_soaoutv6 = 6,
  87         dns_zonestatscounter_axfrreqv4 = 7,
  88         dns_zonestatscounter_axfrreqv6 = 8,
  89         dns_zonestatscounter_ixfrreqv4 = 9,
  90         dns_zonestatscounter_ixfrreqv6 = 10,
  91         dns_zonestatscounter_xfrsuccess = 11,
  92         dns_zonestatscounter_xfrfail = 12,
  93
  94         dns_zonestatscounter_max = 13,
  95
  96         /*%
  97         * Query statistics counters (obsolete).
  98         */
  99         dns_statscounter_success = 0,    /*%< Successful lookup */
 100         dns_statscounter_referral = 1,   /*%< Referral result */
 101         dns_statscounter_nxrrset = 2,    /*%< NXRRSET result */
 102         dns_statscounter_nxdomain = 3,   /*%< NXDOMAIN result */
 103         dns_statscounter_recursion = 4,  /*%< Recursion was used */
 104         dns_statscounter_failure = 5,    /*%< Some other failure */
 105         dns_statscounter_duplicate = 6,  /*%< Duplicate query */
 106         dns_statscounter_dropped = 7     /*%< Duplicate query (dropped) */
 107 };
 108
 109 #define DNS_STATS_NCOUNTERS 8
 110
 111 #if 0
 112 /*%<
 113  * Flag(s) for dns_xxxstats_dump().  DNS_STATSDUMP_VERBOSE is obsolete.
 114  * ISC_STATSDUMP_VERBOSE should be used instead.  These two values are
 115  * intentionally defined to be the same value to ensure binary compatibility.
 116  */
 117 #define DNS_STATSDUMP_VERBOSE   0x00000001 /*%< dump 0-value counters */
 118 #endif
 119
 120 /*%<
 121  * (Obsoleted)
 122  */
 123 LIBDNS_EXTERNAL_DATA extern const char *dns_statscounter_names[];
 124
 125 /*%
 126  * Attributes for statistics counters of RRset and Rdatatype types.
 127  *
 128  * _OTHERTYPE
 129  *      The rdata type is not explicitly supported and the corresponding counter
 130  *      is counted for other such types, too.  When this attribute is set,
 131  *      the base type is of no use.
 132  *
 133  * _NXRRSET
 134  *      RRset type counters only.  Indicates the RRset is non existent.
 135  *
 136  * _NXDOMAIN
 137  *      RRset type counters only.  Indicates a non existent name.  When this
 138  *      attribute is set, the base type is of no use.
 139  */
 140 #define DNS_RDATASTATSTYPE_ATTR_OTHERTYPE       0x0001
 141 #define DNS_RDATASTATSTYPE_ATTR_NXRRSET         0x0002
 142 #define DNS_RDATASTATSTYPE_ATTR_NXDOMAIN        0x0004
 143
 144 /*%<
 145  * Conversion macros among dns_rdatatype_t, attributes and isc_statscounter_t.
 146  */
 147 #define DNS_RDATASTATSTYPE_BASE(type)   ((dns_rdatatype_t)((type) & 0xFFFF))
 148 #define DNS_RDATASTATSTYPE_ATTR(type)   ((type) >> 16)
 149 #define DNS_RDATASTATSTYPE_VALUE(b, a)  (((a) << 16) | (b))
 150
 151 /*%<
 152  * Types of dump callbacks.
 153  */
 154 typedef void (*dns_generalstats_dumper_t)(isc_statscounter_t, isc_uint64_t,
 155                                           void *);
 156 typedef void (*dns_rdatatypestats_dumper_t)(dns_rdatastatstype_t, isc_uint64_t,
 157                                             void *);
 158 typedef void (*dns_opcodestats_dumper_t)(dns_opcode_t, isc_uint64_t, void *);
 159
 160 ISC_LANG_BEGINDECLS
 161
 162 isc_result_t
 163 dns_generalstats_create(isc_mem_t *mctx, dns_stats_t **statsp, int ncounters);
 164 /*%<
 165  * Create a statistics counter structure of general type.  It counts a general
 166  * set of counters indexed by an ID between 0 and ncounters -1.
 167  * This function is obsolete.  A more general function, isc_stats_create(),
 168  * should be used.
 169  *
 170  * Requires:
 171  *\li   'mctx' must be a valid memory context.
 172  *
 173  *\li   'statsp' != NULL && '*statsp' == NULL.
 174  *
 175  * Returns:
 176  *\li   ISC_R_SUCCESS   -- all ok
 177  *
 178  *\li   anything else   -- failure
 179  */
 180
 181 isc_result_t
 182 dns_rdatatypestats_create(isc_mem_t *mctx, dns_stats_t **statsp);
 183 /*%<
 184  * Create a statistics counter structure per rdatatype.
 185  *
 186  * Requires:
 187  *\li   'mctx' must be a valid memory context.
 188  *
 189  *\li   'statsp' != NULL && '*statsp' == NULL.
 190  *
 191  * Returns:
 192  *\li   ISC_R_SUCCESS   -- all ok
 193  *
 194  *\li   anything else   -- failure
 195  */
 196
 197 isc_result_t
 198 dns_rdatasetstats_create(isc_mem_t *mctx, dns_stats_t **statsp);
 199 /*%<
 200  * Create a statistics counter structure per RRset.
 201  *
 202  * Requires:
 203  *\li   'mctx' must be a valid memory context.
 204  *
 205  *\li   'statsp' != NULL && '*statsp' == NULL.
 206  *
 207  * Returns:
 208  *\li   ISC_R_SUCCESS   -- all ok
 209  *
 210  *\li   anything else   -- failure
 211  */
 212
 213 isc_result_t
 214 dns_opcodestats_create(isc_mem_t *mctx, dns_stats_t **statsp);
 215 /*%<
 216  * Create a statistics counter structure per opcode.
 217  *
 218  * Requires:
 219  *\li   'mctx' must be a valid memory context.
 220  *
 221  *\li   'statsp' != NULL && '*statsp' == NULL.
 222  *
 223  * Returns:
 224  *\li   ISC_R_SUCCESS   -- all ok
 225  *
 226  *\li   anything else   -- failure
 227  */
 228
 229 void
 230 dns_stats_attach(dns_stats_t *stats, dns_stats_t **statsp);
 231 /*%<
 232  * Attach to a statistics set.
 233  *
 234  * Requires:
 235  *\li   'stats' is a valid dns_stats_t.
 236  *
 237  *\li   'statsp' != NULL && '*statsp' == NULL
 238  */
 239
 240 void
 241 dns_stats_detach(dns_stats_t **statsp);
 242 /*%<
 243  * Detaches from the statistics set.
 244  *
 245  * Requires:
 246  *\li   'statsp' != NULL and '*statsp' is a valid dns_stats_t.
 247  */
 248
 249 void
 250 dns_generalstats_increment(dns_stats_t *stats, isc_statscounter_t counter);
 251 /*%<
 252  * Increment the counter-th counter of stats.  This function is obsolete.
 253  * A more general function, isc_stats_increment(), should be used.
 254  *
 255  * Requires:
 256  *\li   'stats' is a valid dns_stats_t created by dns_generalstats_create().
 257  *
 258  *\li   counter is less than the maximum available ID for the stats specified
 259  *      on creation.
 260  */
 261
 262 void
 263 dns_rdatatypestats_increment(dns_stats_t *stats, dns_rdatatype_t type);
 264 /*%<
 265  * Increment the statistics counter for 'type'.
 266  *
 267  * Requires:
 268  *\li   'stats' is a valid dns_stats_t created by dns_rdatatypestats_create().
 269  */
 270
 271 void
 272 dns_rdatasetstats_increment(dns_stats_t *stats, dns_rdatastatstype_t rrsettype);
 273 /*%<
 274  * Increment the statistics counter for 'rrsettype'.
 275  *
 276  * Requires:
 277  *\li   'stats' is a valid dns_stats_t created by dns_rdatasetstats_create().
 278  */
 279
 280 void
 281 dns_rdatasetstats_decrement(dns_stats_t *stats, dns_rdatastatstype_t rrsettype);
 282 /*%<
 283  * Decrement the statistics counter for 'rrsettype'.
 284  *
 285  * Requires:
 286  *\li   'stats' is a valid dns_stats_t created by dns_rdatasetstats_create().
 287  */
 288
 289 void
 290 dns_opcodestats_increment(dns_stats_t *stats, dns_opcode_t code);
 291 /*%<
 292  * Increment the statistics counter for 'code'.
 293  *
 294  * Requires:
 295  *\li   'stats' is a valid dns_stats_t created by dns_opcodestats_create().
 296  */
 297
 298 void
 299 dns_generalstats_dump(dns_stats_t *stats, dns_generalstats_dumper_t dump_fn,
 300                       void *arg, unsigned int options);
 301 /*%<
 302  * Dump the current statistics counters in a specified way.  For each counter
 303  * in stats, dump_fn is called with its current value and the given argument
 304  * arg.  By default counters that have a value of 0 is skipped; if options has
 305  * the ISC_STATSDUMP_VERBOSE flag, even such counters are dumped.
 306  *
 307  * This function is obsolete.  A more general function, isc_stats_dump(),
 308  * should be used.
 309  *
 310  * Requires:
 311  *\li   'stats' is a valid dns_stats_t created by dns_generalstats_create().
 312  */
 313
 314 void
 315 dns_rdatatypestats_dump(dns_stats_t *stats, dns_rdatatypestats_dumper_t dump_fn,
 316                         void *arg, unsigned int options);
 317 /*%<
 318  * Dump the current statistics counters in a specified way.  For each counter
 319  * in stats, dump_fn is called with the corresponding type in the form of
 320  * dns_rdatastatstype_t, the current counter value and the given argument
 321  * arg.  By default counters that have a value of 0 is skipped; if options has
 322  * the ISC_STATSDUMP_VERBOSE flag, even such counters are dumped.
 323  *
 324  * Requires:
 325  *\li   'stats' is a valid dns_stats_t created by dns_generalstats_create().
 326  */
 327
 328 void
 329 dns_rdatasetstats_dump(dns_stats_t *stats, dns_rdatatypestats_dumper_t dump_fn,
 330                        void *arg, unsigned int options);
 331 /*%<
 332  * Dump the current statistics counters in a specified way.  For each counter
 333  * in stats, dump_fn is called with the corresponding type in the form of
 334  * dns_rdatastatstype_t, the current counter value and the given argument
 335  * arg.  By default counters that have a value of 0 is skipped; if options has
 336  * the ISC_STATSDUMP_VERBOSE flag, even such counters are dumped.
 337  *
 338  * Requires:
 339  *\li   'stats' is a valid dns_stats_t created by dns_generalstats_create().
 340  */
 341
 342 void
 343 dns_opcodestats_dump(dns_stats_t *stats, dns_opcodestats_dumper_t dump_fn,
 344                      void *arg, unsigned int options);
 345 /*%<
 346  * Dump the current statistics counters in a specified way.  For each counter
 347  * in stats, dump_fn is called with the corresponding opcode, the current
 348  * counter value and the given argument arg.  By default counters that have a
 349  * value of 0 is skipped; if options has the ISC_STATSDUMP_VERBOSE flag, even
 350  * such counters are dumped.
 351  *
 352  * Requires:
 353  *\li   'stats' is a valid dns_stats_t created by dns_generalstats_create().
 354  */
 355
 356 isc_result_t
 357 dns_stats_alloccounters(isc_mem_t *mctx, isc_uint64_t **ctrp);
 358 /*%<
 359  * Allocate an array of query statistics counters from the memory
 360  * context 'mctx'.
 361  *
 362  * This function is obsoleted.  Use dns_xxxstats_create() instead.
 363  */
 364
 365 void
 366 dns_stats_freecounters(isc_mem_t *mctx, isc_uint64_t **ctrp);
 367 /*%<
 368  * Free an array of query statistics counters allocated from the memory
 369  * context 'mctx'.
 370  *
 371  * This function is obsoleted.  Use dns_stats_destroy() instead.
 372  */
 373
 374 ISC_LANG_ENDDECLS
 375
 376 #endif /* DNS_STATS_H */