/* 
   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 write statistics, obtain a StatWriter for a particular domain, and then
 * use the writer's incr(), set(), and push() methods.
 *
 */
 
/** Get a stats writer for a domain.
 *  IMMEDIATE
 *
 *  The domain is specified as an array literal
 *  EXAMPLES:
 *    var stats = stats_module.get_writer(["app"]);
 *    var stats = stats_module.get_writer(["app","user_connections"]);
 *
 *    stats.incr(["created"]);
 *    stats.incr(["get","cached"]);
 *    stats.set(["login"],"enabled");
 *    stats.push(["users"], current_user);
 */
  getWriter([ domain ]);


/*** StatWriter methods ***/
  
/** Coerce the value at domain to a Number, then set it to 1 (if new) 
 *  or increment it (if existing).
 *  The domain is specified as an array literal.
 *  A single-part domain can alternately be given as a string
 *  IMMEDIATE
 * 
 */
 statWriter.incr(domain);
 
 
/** Set the current value at "domain" to "value".
 *  IMMEDIATE
 *  The domain is specified as an array literal.
 *  A single-part domain can alternately be given as a string
 *
 */
 statWriter.set(domain, value);


/** Coerce the value at "domain" to an Array, then push value to it.
 *  IMMEDIATE
 *  The domain is specified as an array literal.
 *  A single-part domain can alternately be given as a string
 *
 *  Note that pop(), etc. are missing; to access the array directly, use query() 
 *  to fetch it.
 *
 */
 statWriter.push(domain, value);

