/* 
   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, ... );