Package oracle.nosql.driver

# Interface StatsControl

public interface StatsControl

This interface allows user to control the collection of driver statistics at runtime.

The statistics data is collected for an interval of time. At the end of the interval, the stats data is logged in a specified JSON format that can be filtered and parsed. After the logging, the counters are cleared and collection of data resumes.

Collection intervals are aligned to the top of the hour. This means first interval logs may contain stats for a shorter interval.

Collection of stats are controlled by the following system properties:

- -Dcom.oracle.nosql.sdk.nosqldriver.stats.profile=[none|regular|more|all] Specifies the stats profile: none - disabled, regular - per request: counters, errors, latencies, delays, retries more - stats above with 95th and 99th percentile latencies all - stats above with per query information.
- -Dcom.oracle.nosql.sdk.nosqldriver.stats.interval=600 Interval in seconds to log the stats, by default is 10 minutes.
- -Dcom.oracle.nosql.sdk.nosqldriver.stats.pretty-print=true Option to enable pretty printing of the JSON data, default value is false
- -Dcom.oracle.nosql.sdk.nosqldriver.stats.enable-log=false Option to turn on logging automatically if stats are enabled, default value is true

Statistics can also be enabled by using the API: `NoSQLHandleConfig.setStatsProfile(StatsControl.Profile)` or `setProfile(StatsControl.Profile)`. At runtime stats collection can be enabled selectively by using `start()` and `stop()`. The following example shows how to use a stats handler and control the stats at runtime:

         NoSQLHandleConfig config = new NoSQLHandleConfig( endpoint );
         config.setStatsProfile(StatsControl.Profile.REGULAR);
         config.setStatsInterval(600);
         config.setStatsPrettyPrint(false);
         config.setStatsHandler(
             new StatsControl.StatsHandler() {
                 public void accept(MapValue jsonStats) {
                     System.out.println("!!! Got a stat: " + jsonStats);
                 }
             });
         NoSQLHandle handle = NoSQLHandleFactory.createNoSQLHandle(config);

         StatsControl statsControl = handle.getStatsControl();

         //... application code without stats

         // enable observations
         statsControl.start();

         //... application code with REGULAR stats

         // For particular parts of code profile can be changed to collect more stats.
         statsControl.setProfile(StatsControl.Profile.ALL)
         //... more sensitive code with ALL stats
         statsControl.setProfile(StatsControl.Profile.REGULAR)

         //... application code with REGULAR stats

         // disable observations
         statsControl.stop();

         // ... application code without stats
         handle.close();

For a detailed statistics log entries structure and values see `oracle.nosql.driver`

Since:
  5.2.30

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static enum`
  `StatsControl.Profile`
  A Profile that determines what stats are logged
  `static interface`
  `StatsControl.StatsHandler`
  Handler interface that user can register to get access to stats at the end of the interval.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `LOG_PREFIX`
  prefix in log entries

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `getInterval()`
  Returns the current collection interval.
  `boolean`
  `getPrettyPrint()`
  Returns the current JSON pretty print flag.
  `StatsControl.Profile`
  `getProfile()`
  Returns the collection profile.
  `StatsControl.StatsHandler`
  `getStatsHandler()`
  Returns the registered stats handler.
  `boolean`
  `isStarted()`
  Returns true if collection of stats is enabled, otherwise returns false.
  `StatsControl`
  `setPrettyPrint(boolean enablePrettyPrint)`
  Enable JSON pretty print for easier human reading.
  `StatsControl`
  `setProfile(StatsControl.Profile profile)`
  Set the stats collection profile.
  `StatsControl`
  `setStatsHandler(StatsControl.StatsHandler handler)`
  Registers a stats handler.
  `void`
  `start()`
  Collection of stats is enabled only between start and stop or from the beginning if system property -Dcom.oracle.nosql.sdk.nosqldriver.stats.profile= is not "none".
  `void`
  `stop()`
  Stops collection of stats.

- ## Field Details

  - ### LOG_PREFIX

    static final String LOG_PREFIX
    prefix in log entries
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getInterval

    int getInterval()
    Returns the current collection interval. Default interval is 600 seconds, i.e. 10 min.
    Returns:
      the current collection interval

  - ### setProfile

    StatsControl setProfile(StatsControl.Profile profile)
    Set the stats collection profile. Default profile is NONE.
    Parameters:
      `profile` - the stats collection profile
    Returns:
      this

  - ### getProfile

    StatsControl.Profile getProfile()
    Returns the collection profile. Default profile is NONE.
    Returns:
      the current profile

  - ### setPrettyPrint

    StatsControl setPrettyPrint(boolean enablePrettyPrint)
    Enable JSON pretty print for easier human reading. Default is disabled.
    Parameters:
      `enablePrettyPrint` - flag to enable JSON pretty print
    Returns:
      this

  - ### getPrettyPrint

    boolean getPrettyPrint()
    Returns the current JSON pretty print flag. Default is disabled.
    Returns:
      the current JSON pretty print flag

  - ### getStatsHandler

    StatsControl.StatsHandler getStatsHandler()
    Returns the registered stats handler.
    Returns:
      the current handler, null if no handler has been registered.

  - ### setStatsHandler

    StatsControl setStatsHandler(StatsControl.StatsHandler handler)
    Registers a stats handler.
    Parameters:
      `handler` - User defined StatsHandler
    Returns:
      this

  - ### start

    void start()
    Collection of stats is enabled only between start and stop or from the beginning if system property -Dcom.oracle.nosql.sdk.nosqldriver.stats.profile= is not "none".

  - ### stop

    void stop()
    Stops collection of stats.

  - ### isStarted

    boolean isStarted()
    Returns true if collection of stats is enabled, otherwise returns false.
    Returns:
      true if start() was called last, false otherwise.