1/* 2 Copyright (c) 2013, 2021, Oracle and/or its affiliates. 3 4 This program is free software; you can redistribute it and/or modify 5 it under the terms of the GNU General Public License, version 2.0, 6 as published by the Free Software Foundation. 7 8 This program is also distributed with certain software (including 9 but not limited to OpenSSL) that is licensed under separate terms, 10 as designated in a particular file or component or in included license 11 documentation. The authors of MySQL hereby grant you an additional 12 permission to link the program and your derivative works with the 13 separately licensed software that they have included with MySQL. 14 15 This program is distributed in the hope that it will be useful, 16 but WITHOUT ANY WARRANTY; without even the implied warranty of 17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 GNU General Public License, version 2.0, for more details. 19 20 You should have received a copy of the GNU General Public License 21 along with this program; if not, write to the Free Software 22 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 23*/ 24 25/* 26 The connector maintains "statistics" -- internal counters recording certain 27 important method calls and database operations. 28 29 Statistics are stored hierarchically under a global object. 30 31 API-level counter names begin with "api", while adapter-level (SPI) counters 32 begin with "spi" followed by the name of the adapter. 33 34 It is possible to access the statistics through an HTTP server; first, 35 start the server from within application code, then send it a request. 36 The URL pathname components of the request correspond to nodes in the 37 hierarchy; "/" corresponds to all statistics; "/spi/ndb" only to NDB 38 adapter-level statistics, and so forth. 39 40 The application code itself can also make use of the statistics API to 41 record app-level information. 42 43 HOW TO ACCESS THE STATS API: 44 var stats_module = require(path.join(api_dir, "stats.js")); 45*/ 46 47 48/** Write complete global statistics to the console. 49 * IMMEDIATE 50 * 51 * No return value 52 */ 53 stats_module.peek(); 54 55 56/** Return an object containing a statistics tree. 57 * IMMEDIATE 58 * 59 * The domain is specified as an array literal 60 * query([]); // return global statistics 61 * query(["spi"]); // return all SPI-level statistics 62 * query(["spi","ndb"]); // return only statistics under spi.ndb 63 * 64 */ 65 stats_module.query(domain); 66 67 68 /** Start a web server to service statistics queries over HTTP. 69 * ASYNCHRONOUS 70 * 71 * Arguments (port, host, callback) are passed onward to http.server.listen(). 72 * 73 * The request pathname is interpreted as a hierarchical stats domain name. 74 * The response will be returned as a JSON serialized object. 75 * 76 * RETURNS an http.server referring to the running server. 77 */ 78 stats_module.startStatsServer(port, host, callback); 79 80 81 /** Stop all running statistics web servers. 82 * ASYNCHRONOUS 83 * 84 * Each server will emit a "close" event when finished. 85 * 86 */ 87 stats_module.stopStatsServers(); 88 89 90/********* WRITING APPLICATION-LEVEL STATISTICS **********/ 91 92/** 93 * To maintain statistics, a module keeps its own statistics object, 94 * and registers that object with the stats module. 95 96/** Register statistics for a domain. 97 * IMMEDIATE 98 * 99 * EXAMPLES: 100 * stats_module.register(my_stats, "app"); 101 * stats_module.register(module_stats, "app","sub_module_1"); 102 * 103 */ 104 register(stats_container, domain_part, ... ); 105