/*
   Copyright (c) 2013, 2021, Oracle and/or its affiliates.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License, version 2.0,
   as published by the Free Software Foundation.

   This program is also distributed with certain software (including
   but not limited to OpenSSL) that is licensed under separate terms,
   as designated in a particular file or component or in included license
   documentation.  The authors of MySQL hereby grant you an additional
   permission to link the program and your derivative works with the
   separately licensed software that they have included with MySQL.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License, version 2.0, for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA
*/

/* 
   The connector maintains "statistics" -- internal counters recording certain
   important method calls and database operations.
   
   Statistics are stored hierarchically under a global object.
   
   API-level counter names begin with "api", while adapter-level (SPI) counters
   begin with "spi" followed by the name of the adapter.
   
   It is possible to access the statistics through an HTTP server; first, 
   start the server from within application code, then send it a request. 
   The URL pathname components of the request correspond to nodes in the
   hierarchy; "/" corresponds to all statistics; "/spi/ndb" only to NDB 
   adapter-level statistics, and so forth.
   
   The application code itself can also make use of the statistics API to
   record app-level information.

   HOW TO ACCESS THE STATS API:
   var stats_module = require(path.join(api_dir, "stats.js"));
*/
  

/** Write complete global statistics to the console.
 *  IMMEDIATE
 *  
 *  No return value
 */
 stats_module.peek();
 

/** Return an object containing a statistics tree.
 *  IMMEDIATE
 *
 *  The domain is specified as an array literal
 *  query([]);               // return global statistics
 *  query(["spi"]);          // return all SPI-level statistics
 *  query(["spi","ndb"]);    // return only statistics under spi.ndb
 *
 */
 stats_module.query(domain);
 
 
 /** Start a web server to service statistics queries over HTTP.
  *  ASYNCHRONOUS
  *  
  *  Arguments (port, host, callback) are passed onward to http.server.listen().
  *  
  *  The request pathname is interpreted as a hierarchical stats domain name.
  *  The response will be returned as a JSON serialized object.
  *
  *  RETURNS an http.server referring to the running server.
  */
  stats_module.startStatsServer(port, host, callback); 
  

 /** Stop all running statistics web servers.
  *  ASYNCHRONOUS 
  *
  *  Each server will emit a "close" event when finished.
  *
  */
  stats_module.stopStatsServers();
  

/********* WRITING APPLICATION-LEVEL STATISTICS **********/

/**
 * To maintain statistics, a module keeps its own statistics object,
 * and registers that object with the stats module.
 
/** Register statistics for a domain.
 *  IMMEDIATE
 *
 *  EXAMPLES:
 *    stats_module.register(my_stats, "app");
 *    stats_module.register(module_stats, "app","sub_module_1");
 *
 */
  register(stats_container, domain_part, ... );
