1 /* $NetBSD: stats.h,v 1.9 2025/01/26 16:25:28 christos Exp $ */ 2 3 /* 4 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5 * 6 * SPDX-License-Identifier: MPL-2.0 7 * 8 * This Source Code Form is subject to the terms of the Mozilla Public 9 * License, v. 2.0. If a copy of the MPL was not distributed with this 10 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 11 * 12 * See the COPYRIGHT file distributed with this work for additional 13 * information regarding copyright ownership. 14 */ 15 16 #pragma once 17 18 /*! \file dns/stats.h */ 19 20 #include <inttypes.h> 21 22 #include <isc/histo.h> 23 24 #include <dns/types.h> 25 26 /*% 27 * Statistics counters. Used as isc_statscounter_t values. 28 */ 29 enum { 30 /*% 31 * Resolver statistics counters. 32 */ 33 dns_resstatscounter_queryv4 = 0, 34 dns_resstatscounter_queryv6 = 1, 35 dns_resstatscounter_responsev4 = 2, 36 dns_resstatscounter_responsev6 = 3, 37 dns_resstatscounter_nxdomain = 4, 38 dns_resstatscounter_servfail = 5, 39 dns_resstatscounter_formerr = 6, 40 dns_resstatscounter_othererror = 7, 41 dns_resstatscounter_edns0fail = 8, 42 dns_resstatscounter_mismatch = 9, 43 dns_resstatscounter_truncated = 10, 44 dns_resstatscounter_lame = 11, 45 dns_resstatscounter_retry = 12, 46 dns_resstatscounter_gluefetchv4 = 13, 47 dns_resstatscounter_gluefetchv6 = 14, 48 dns_resstatscounter_gluefetchv4fail = 15, 49 dns_resstatscounter_gluefetchv6fail = 16, 50 dns_resstatscounter_val = 17, 51 dns_resstatscounter_valsuccess = 18, 52 dns_resstatscounter_valnegsuccess = 19, 53 dns_resstatscounter_valfail = 20, 54 dns_resstatscounter_dispabort = 21, 55 dns_resstatscounter_dispsockfail = 22, 56 dns_resstatscounter_querytimeout = 23, 57 dns_resstatscounter_queryrtt0 = 24, 58 dns_resstatscounter_queryrtt1 = 25, 59 dns_resstatscounter_queryrtt2 = 26, 60 dns_resstatscounter_queryrtt3 = 27, 61 dns_resstatscounter_queryrtt4 = 28, 62 dns_resstatscounter_queryrtt5 = 29, 63 dns_resstatscounter_nfetch = 30, 64 dns_resstatscounter_disprequdp = 31, 65 dns_resstatscounter_dispreqtcp = 32, 66 dns_resstatscounter_buckets = 33, 67 dns_resstatscounter_refused = 34, 68 dns_resstatscounter_cookienew = 35, 69 dns_resstatscounter_cookieout = 36, 70 dns_resstatscounter_cookiein = 37, 71 dns_resstatscounter_cookieok = 38, 72 dns_resstatscounter_badvers = 39, 73 dns_resstatscounter_badcookie = 40, 74 dns_resstatscounter_zonequota = 41, 75 dns_resstatscounter_serverquota = 42, 76 dns_resstatscounter_clientquota = 43, 77 dns_resstatscounter_nextitem = 44, 78 dns_resstatscounter_priming = 45, 79 dns_resstatscounter_max = 46, 80 81 /* 82 * DNSSEC stats. 83 */ 84 dns_dnssecstats_asis = 0, 85 dns_dnssecstats_downcase = 1, 86 dns_dnssecstats_wildcard = 2, 87 dns_dnssecstats_fail = 3, 88 89 dns_dnssecstats_max = 4, 90 91 /*% 92 * Zone statistics counters. 93 */ 94 dns_zonestatscounter_notifyoutv4 = 0, 95 dns_zonestatscounter_notifyoutv6 = 1, 96 dns_zonestatscounter_notifyinv4 = 2, 97 dns_zonestatscounter_notifyinv6 = 3, 98 dns_zonestatscounter_notifyrej = 4, 99 dns_zonestatscounter_soaoutv4 = 5, 100 dns_zonestatscounter_soaoutv6 = 6, 101 dns_zonestatscounter_axfrreqv4 = 7, 102 dns_zonestatscounter_axfrreqv6 = 8, 103 dns_zonestatscounter_ixfrreqv4 = 9, 104 dns_zonestatscounter_ixfrreqv6 = 10, 105 dns_zonestatscounter_xfrsuccess = 11, 106 dns_zonestatscounter_xfrfail = 12, 107 108 dns_zonestatscounter_max = 13, 109 110 /* 111 * Adb statistics values. 112 */ 113 dns_adbstats_nentries = 0, 114 dns_adbstats_entriescnt = 1, 115 dns_adbstats_nnames = 2, 116 dns_adbstats_namescnt = 3, 117 118 dns_adbstats_max = 4, 119 120 /* 121 * Cache statistics values. 122 */ 123 dns_cachestatscounter_hits = 1, 124 dns_cachestatscounter_misses = 2, 125 dns_cachestatscounter_queryhits = 3, 126 dns_cachestatscounter_querymisses = 4, 127 dns_cachestatscounter_deletelru = 5, 128 dns_cachestatscounter_deletettl = 6, 129 dns_cachestatscounter_coveringnsec = 7, 130 131 dns_cachestatscounter_max = 8, 132 133 /*% 134 * Query statistics counters (obsolete). 135 */ 136 dns_statscounter_success = 0, /*%< Successful lookup */ 137 dns_statscounter_referral = 1, /*%< Referral result */ 138 dns_statscounter_nxrrset = 2, /*%< NXRRSET result */ 139 dns_statscounter_nxdomain = 3, /*%< NXDOMAIN result */ 140 dns_statscounter_recursion = 4, /*%< Recursion was used */ 141 dns_statscounter_failure = 5, /*%< Some other failure */ 142 dns_statscounter_duplicate = 6, /*%< Duplicate query */ 143 dns_statscounter_dropped = 7, /*%< Duplicate query (dropped) */ 144 145 /*% 146 * DNSTAP statistics counters. 147 */ 148 dns_dnstapcounter_success = 0, 149 dns_dnstapcounter_drop = 1, 150 dns_dnstapcounter_max = 2, 151 152 /* 153 * Glue cache statistics counters. 154 */ 155 dns_gluecachestatscounter_hits_present = 0, 156 dns_gluecachestatscounter_hits_absent = 1, 157 dns_gluecachestatscounter_inserts_present = 2, 158 dns_gluecachestatscounter_inserts_absent = 3, 159 160 dns_gluecachestatscounter_max = 4, 161 }; 162 163 /*% 164 * Traffic size statistics, according to RSSAC002 section 2.4 165 * https://www.icann.org/en/system/files/files/rssac-002-measurements-root-20nov14-en.pdf 166 * 167 * The RSSAC002 linear bucketing does not directly match the log-linear 168 * bucketing of an `isc_histo_t`, so we need to adjust some parameters 169 * to fit. 170 * 171 * To map a message size to an `isc_histo_t`, first divide by 172 * DNS_SIZEHISTO_QUANTUM so that `isc_histo_inc()` is presented with 173 * one value per RSSAC002 bucket. 174 * 175 * Configure the `isc_histo_t` with large enough `sigbits` that its 176 * one-value-per-bucket range (its `UNITBUCKETS`) covers the range 177 * required by RSSAC002. 178 */ 179 #define DNS_SIZEHISTO_QUANTUM 16 180 #define DNS_SIZEHISTO_MAXIN (288 / DNS_SIZEHISTO_QUANTUM) 181 #define DNS_SIZEHISTO_MAXOUT (4096 / DNS_SIZEHISTO_QUANTUM) 182 #define DNS_SIZEHISTO_SIGBITSIN 4 183 #define DNS_SIZEHISTO_SIGBITSOUT 7 184 185 #define DNS_SIZEHISTO_BUCKETIN(size) \ 186 ISC_MIN(size / DNS_SIZEHISTO_QUANTUM, DNS_SIZEHISTO_MAXIN) 187 188 #define DNS_SIZEHISTO_BUCKETOUT(size) \ 189 ISC_MIN(size / DNS_SIZEHISTO_QUANTUM, DNS_SIZEHISTO_MAXOUT) 190 191 STATIC_ASSERT(DNS_SIZEHISTO_MAXIN <= 192 ISC_HISTO_UNITBUCKETS(DNS_SIZEHISTO_SIGBITSIN), 193 "must be enough histogram buckets for RSSAC002"); 194 195 STATIC_ASSERT(DNS_SIZEHISTO_MAXOUT <= 196 ISC_HISTO_UNITBUCKETS(DNS_SIZEHISTO_SIGBITSOUT), 197 "must be enough histogram buckets for RSSAC002"); 198 199 /* 200 * For consistency with other stats counters 201 */ 202 enum { 203 dns_sizecounter_in_max = DNS_SIZEHISTO_MAXIN + 1, 204 dns_sizecounter_out_max = DNS_SIZEHISTO_MAXOUT + 1, 205 }; 206 207 /*% 208 * Attributes for statistics counters of RRset and Rdatatype types. 209 * 210 * _OTHERTYPE 211 * The rdata type is not explicitly supported and the corresponding counter 212 * is counted for other such types, too. When this attribute is set, 213 * the base type is of no use. 214 * 215 * _NXRRSET 216 * RRset type counters only. Indicates the RRset is non existent. 217 * 218 * _NXDOMAIN 219 * RRset type counters only. Indicates a non existent name. When this 220 * attribute is set, the base type is of no use. 221 * 222 * _STALE 223 * RRset type counters only. This indicates a record that is stale 224 * but may still be served. 225 * 226 * _ANCIENT 227 * RRset type counters only. This indicates a record that is marked for 228 * removal. 229 */ 230 #define DNS_RDATASTATSTYPE_ATTR_OTHERTYPE 0x0001 231 #define DNS_RDATASTATSTYPE_ATTR_NXRRSET 0x0002 232 #define DNS_RDATASTATSTYPE_ATTR_NXDOMAIN 0x0004 233 #define DNS_RDATASTATSTYPE_ATTR_STALE 0x0008 234 #define DNS_RDATASTATSTYPE_ATTR_ANCIENT 0x0010 235 236 /*%< 237 * Conversion macros among dns_rdatatype_t, attributes and isc_statscounter_t. 238 */ 239 #define DNS_RDATASTATSTYPE_BASE(type) ((dns_rdatatype_t)((type) & 0xFFFF)) 240 #define DNS_RDATASTATSTYPE_ATTR(type) ((type) >> 16) 241 #define DNS_RDATASTATSTYPE_VALUE(b, a) (((a) << 16) | (b)) 242 243 /*% 244 * Types of DNSSEC sign statistics operations. 245 */ 246 typedef enum { 247 dns_dnssecsignstats_sign = 1, 248 dns_dnssecsignstats_refresh = 2 249 } dnssecsignstats_type_t; 250 251 /*%< 252 * Types of dump callbacks. 253 */ 254 typedef void (*dns_generalstats_dumper_t)(isc_statscounter_t, uint64_t, void *); 255 typedef void (*dns_rdatatypestats_dumper_t)(dns_rdatastatstype_t, uint64_t, 256 void *); 257 typedef void (*dns_dnssecsignstats_dumper_t)(uint32_t, uint64_t, void *); 258 typedef void (*dns_opcodestats_dumper_t)(dns_opcode_t, uint64_t, void *); 259 typedef void (*dns_rcodestats_dumper_t)(dns_rcode_t, uint64_t, void *); 260 261 ISC_LANG_BEGINDECLS 262 263 void 264 dns_generalstats_create(isc_mem_t *mctx, dns_stats_t **statsp, int ncounters); 265 /*%< 266 * Create a statistics counter structure of general type. It counts a general 267 * set of counters indexed by an ID between 0 and ncounters -1. 268 * This function is obsolete. A more general function, isc_stats_create(), 269 * should be used. 270 * 271 * Requires: 272 *\li 'mctx' must be a valid memory context. 273 * 274 *\li 'statsp' != NULL && '*statsp' == NULL. 275 */ 276 277 void 278 dns_rdatatypestats_create(isc_mem_t *mctx, dns_stats_t **statsp); 279 /*%< 280 * Create a statistics counter structure per rdatatype. 281 * 282 * Requires: 283 *\li 'mctx' must be a valid memory context. 284 * 285 *\li 'statsp' != NULL && '*statsp' == NULL. 286 */ 287 288 void 289 dns_rdatasetstats_create(isc_mem_t *mctx, dns_stats_t **statsp); 290 /*%< 291 * Create a statistics counter structure per RRset. 292 * 293 * Requires: 294 *\li 'mctx' must be a valid memory context. 295 * 296 *\li 'statsp' != NULL && '*statsp' == NULL. 297 */ 298 299 void 300 dns_opcodestats_create(isc_mem_t *mctx, dns_stats_t **statsp); 301 /*%< 302 * Create a statistics counter structure per opcode. 303 * 304 * Requires: 305 *\li 'mctx' must be a valid memory context. 306 * 307 *\li 'statsp' != NULL && '*statsp' == NULL. 308 */ 309 310 void 311 dns_rcodestats_create(isc_mem_t *mctx, dns_stats_t **statsp); 312 /*%< 313 * Create a statistics counter structure per assigned rcode. 314 * 315 * Requires: 316 *\li 'mctx' must be a valid memory context. 317 * 318 *\li 'statsp' != NULL && '*statsp' == NULL. 319 */ 320 321 void 322 dns_dnssecsignstats_create(isc_mem_t *mctx, dns_stats_t **statsp); 323 /*%< 324 * Create a statistics counter structure per assigned DNSKEY id. 325 * 326 * Requires: 327 *\li 'mctx' must be a valid memory context. 328 * 329 *\li 'statsp' != NULL && '*statsp' == NULL. 330 */ 331 332 void 333 dns_stats_attach(dns_stats_t *stats, dns_stats_t **statsp); 334 /*%< 335 * Attach to a statistics set. 336 * 337 * Requires: 338 *\li 'stats' is a valid dns_stats_t. 339 * 340 *\li 'statsp' != NULL && '*statsp' == NULL 341 */ 342 343 void 344 dns_stats_detach(dns_stats_t **statsp); 345 /*%< 346 * Detaches from the statistics set. 347 * 348 * Requires: 349 *\li 'statsp' != NULL and '*statsp' is a valid dns_stats_t. 350 */ 351 352 void 353 dns_generalstats_increment(dns_stats_t *stats, isc_statscounter_t counter); 354 /*%< 355 * Increment the counter-th counter of stats. This function is obsolete. 356 * A more general function, isc_stats_increment(), should be used. 357 * 358 * Requires: 359 *\li 'stats' is a valid dns_stats_t created by dns_generalstats_create(). 360 * 361 *\li counter is less than the maximum available ID for the stats specified 362 * on creation. 363 */ 364 365 void 366 dns_rdatatypestats_increment(dns_stats_t *stats, dns_rdatatype_t type); 367 /*%< 368 * Increment the statistics counter for 'type'. 369 * 370 * Requires: 371 *\li 'stats' is a valid dns_stats_t created by dns_rdatatypestats_create(). 372 */ 373 374 void 375 dns_rdatasetstats_increment(dns_stats_t *stats, dns_rdatastatstype_t rrsettype); 376 /*%< 377 * Increment the statistics counter for 'rrsettype'. 378 * 379 * Note: if 'rrsettype' has the _STALE attribute set the corresponding 380 * non-stale counter will be decremented. 381 * 382 * Requires: 383 *\li 'stats' is a valid dns_stats_t created by dns_rdatasetstats_create(). 384 */ 385 386 void 387 dns_rdatasetstats_decrement(dns_stats_t *stats, dns_rdatastatstype_t rrsettype); 388 /*%< 389 * Decrement the statistics counter for 'rrsettype'. 390 * 391 * Requires: 392 *\li 'stats' is a valid dns_stats_t created by dns_rdatasetstats_create(). 393 */ 394 395 void 396 dns_opcodestats_increment(dns_stats_t *stats, dns_opcode_t code); 397 /*%< 398 * Increment the statistics counter for 'code'. 399 * 400 * Requires: 401 *\li 'stats' is a valid dns_stats_t created by dns_opcodestats_create(). 402 */ 403 404 void 405 dns_rcodestats_increment(dns_stats_t *stats, dns_opcode_t code); 406 /*%< 407 * Increment the statistics counter for 'code'. 408 * 409 * Requires: 410 *\li 'stats' is a valid dns_stats_t created by dns_rcodestats_create(). 411 */ 412 413 void 414 dns_dnssecsignstats_increment(dns_stats_t *stats, dns_keytag_t id, uint8_t alg, 415 dnssecsignstats_type_t operation); 416 /*%< 417 * Increment the statistics counter for the DNSKEY 'id' with algorithm 'alg'. 418 * The 'operation' determines what counter is incremented. 419 * 420 * Requires: 421 *\li 'stats' is a valid dns_stats_t created by dns_dnssecsignstats_create(). 422 */ 423 424 void 425 dns_dnssecsignstats_clear(dns_stats_t *stats, dns_keytag_t id, uint8_t alg); 426 /*%< 427 * Clear the statistics counter for the DNSKEY 'id' with algorithm 'alg'. 428 * 429 * Requires: 430 *\li 'stats' is a valid dns_stats_t created by dns_dnssecsignstats_create(). 431 */ 432 433 void 434 dns_generalstats_dump(dns_stats_t *stats, dns_generalstats_dumper_t dump_fn, 435 void *arg, unsigned int options); 436 /*%< 437 * Dump the current statistics counters in a specified way. For each counter 438 * in stats, dump_fn is called with its current value and the given argument 439 * arg. By default counters that have a value of 0 is skipped; if options has 440 * the ISC_STATSDUMP_VERBOSE flag, even such counters are dumped. 441 * 442 * This function is obsolete. A more general function, isc_stats_dump(), 443 * should be used. 444 * 445 * Requires: 446 *\li 'stats' is a valid dns_stats_t created by dns_generalstats_create(). 447 */ 448 449 void 450 dns_rdatatypestats_dump(dns_stats_t *stats, dns_rdatatypestats_dumper_t dump_fn, 451 void *arg, unsigned int options); 452 /*%< 453 * Dump the current statistics counters in a specified way. For each counter 454 * in stats, dump_fn is called with the corresponding type in the form of 455 * dns_rdatastatstype_t, the current counter value and the given argument 456 * arg. By default counters that have a value of 0 is skipped; if options has 457 * the ISC_STATSDUMP_VERBOSE flag, even such counters are dumped. 458 * 459 * Requires: 460 *\li 'stats' is a valid dns_stats_t created by dns_generalstats_create(). 461 */ 462 463 void 464 dns_rdatasetstats_dump(dns_stats_t *stats, dns_rdatatypestats_dumper_t dump_fn, 465 void *arg, unsigned int options); 466 /*%< 467 * Dump the current statistics counters in a specified way. For each counter 468 * in stats, dump_fn is called with the corresponding type in the form of 469 * dns_rdatastatstype_t, the current counter value and the given argument 470 * arg. By default counters that have a value of 0 is skipped; if options has 471 * the ISC_STATSDUMP_VERBOSE flag, even such counters are dumped. 472 * 473 * Requires: 474 *\li 'stats' is a valid dns_stats_t created by dns_generalstats_create(). 475 */ 476 477 void 478 dns_dnssecsignstats_dump(dns_stats_t *stats, dnssecsignstats_type_t operation, 479 dns_dnssecsignstats_dumper_t dump_fn, void *arg, 480 unsigned int options); 481 /*%< 482 * Dump the current statistics counters in a specified way. For each counter 483 * in stats, dump_fn is called with the corresponding type in the form of 484 * dns_rdatastatstype_t, the current counter value and the given argument 485 * arg. By default counters that have a value of 0 is skipped; if options has 486 * the ISC_STATSDUMP_VERBOSE flag, even such counters are dumped. 487 * 488 * Requires: 489 *\li 'stats' is a valid dns_stats_t created by dns_generalstats_create(). 490 */ 491 492 void 493 dns_opcodestats_dump(dns_stats_t *stats, dns_opcodestats_dumper_t dump_fn, 494 void *arg, unsigned int options); 495 /*%< 496 * Dump the current statistics counters in a specified way. For each counter 497 * in stats, dump_fn is called with the corresponding opcode, the current 498 * counter value and the given argument arg. By default counters that have a 499 * value of 0 is skipped; if options has the ISC_STATSDUMP_VERBOSE flag, even 500 * such counters are dumped. 501 * 502 * Requires: 503 *\li 'stats' is a valid dns_stats_t created by dns_generalstats_create(). 504 */ 505 506 void 507 dns_rcodestats_dump(dns_stats_t *stats, dns_rcodestats_dumper_t dump_fn, 508 void *arg, unsigned int options); 509 /*%< 510 * Dump the current statistics counters in a specified way. For each counter 511 * in stats, dump_fn is called with the corresponding rcode, the current 512 * counter value and the given argument arg. By default counters that have a 513 * value of 0 is skipped; if options has the ISC_STATSDUMP_VERBOSE flag, even 514 * such counters are dumped. 515 * 516 * Requires: 517 *\li 'stats' is a valid dns_stats_t created by dns_generalstats_create(). 518 */ 519 520 ISC_LANG_ENDDECLS 521