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 class` | `StatsControl.Profile` | The following semantics are attached to the Profile: - NONE: no 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 String` | `LOG_PREFIX` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    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 Detail

    - #### LOG_PREFIX

          static final String LOG_PREFIX

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### 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.