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