::nx::Object ::nx::Object ::ns::stats::SQLiteHistory ::ns::stats::SQLiteHistory allocatorPoint history allocator history configure history disable history query history save history status history storage historyConnect historyDrop historySchema historyStorage historyWindowCoverage pack quote scalar sql unpack ::ns::stats::SQLiteHistory->::nx::Object

Class ::ns::stats::SQLiteHistory

::ns::stats::SQLiteHistory[i] create ...
Defined in

Class Relations

  • class: ::nx::Class[i]
  • superclass: ::nx::Object[i]
  • mixinof: ::ns_stats[i]

Methods (to be applied on instances)

  • history allocator (scripted, public)

     <instance of ns::stats::SQLiteHistory[i]> history allocator \
    -from from  -to to  [ -limit limit ] [ -cursor cursor ]

    Read compact process-wide allocator history from the configured owner server using one bounded sample SELECT. New samples provide stored projections; old rows without a projection are decoded once in this read. No topology loading or full-window payload rescan is performed. Preserve missing gauges as absent dictionary keys. Timestamps are epoch microseconds; instance and intervalSeconds allow callers to preserve restart boundaries and gaps. Reading does not collect or write samples. Coverage complete and windowExamined remain false: this projection does not certify window boundaries or absence of eviction/write failures. Use history query when full-window coverage assessment is required. Timings distinguish checkout, sample SQL read, decoding and total time.

    Switches:
    -from (required, integer)
    Inclusive lower bound in epoch seconds; must be nonnegative.
    -to (required, integer)
    Exclusive upper bound in epoch seconds; after from, at most 24 hours later and no later than now.
    -limit (optional, integer, defaults to "10000")
    Maximum compact records per page, 1..10000; default 10000.
    -cursor (optional, integer, defaults to "0")
    Nonnegative timestamp cursor in microseconds, default 0; pass nextCursor unchanged for continuation.
    Returns:
    Dictionary containing compact records (timestamp, instance, sampling.intervalSeconds and memory), more, nextCursor, legacyDecoded, timings in milliseconds and conservative coverage metadata.

    Testcases:
    No testcase defined.

  • history configure (scripted, public)

     <instance of ns::stats::SQLiteHistory[i]> history configure \
    -pool pool  [ -retention retention ] [ -maxBytes maxBytes ]

    Validate the database pool and retention limits, initialize the schema and start a separate persistence callback. Repeated configuration with identical settings is harmless; changing active settings requires disabling persistence first. Return the resulting history status. Does not start sampling. Normalize retention to fractional seconds and maxBytes to bytes with ns_baseunit before validating the bounds.

    Switches:
    -pool (required)
    Required dedicated persistent nsdbsqlite pool, accessible to the configuring virtual server.
    -retention (optional, defaults to "86400")
    Retention duration accepting ns_baseunit time syntax; 60..604800 seconds, default 86400 seconds.
    -maxBytes (optional, defaults to "67108864")
    Storage budget accepting ns_baseunit size syntax; at least 4 MiB, default 67108864 bytes. Includes database journal headroom.
    Returns:
    History status dictionary after schema initialization and persistence scheduling.

    Testcases:
    No testcase defined.

  • history disable (scripted, public)

     <instance of ns::stats::SQLiteHistory[i]> history disable

    Stop future persistence callbacks without deleting stored history or stopping sampling. An outstanding write may finish. Return the resulting history status.

    Returns:
    Resulting history status dictionary; retained database records are not deleted.

    Testcases:
    No testcase defined.

  • history query (scripted, public)

     <instance of ns::stats::SQLiteHistory[i]> history query -from from  \
    -to to  [ -server server ] [ -limit limit ] [ -cursor cursor ]

    Return stored samples, associated topology, paging information and coverage for an epoch interval. Queries run in the configuring virtual server and use an operation-local database handle. Historical server selection may include servers no longer active.

    Switches:
    -from (required, integer)
    Inclusive lower bound in epoch seconds; must be nonnegative.
    -to (required, integer)
    Exclusive upper bound in epoch seconds; after from, at most 24 hours later and no later than now.
    -server (optional)
    Optional historical virtual-server name, including one no longer configured; empty returns all stored server data.
    -limit (optional, integer, defaults to "1000")
    Maximum records per page, 1..1000; default 1000.
    -cursor (optional, integer, defaults to "0")
    Nonnegative timestamp cursor in microseconds, default 0; pass nextCursor unchanged for continuation.
    Returns:
    Dictionary containing records, referenced topologies, storage statistics, coverage, more and nextCursor. Final-page coverage examines the full requested window.

    Testcases:
    No testcase defined.

  • history save (scripted, public)

     <instance of ns::stats::SQLiteHistory[i]> history save

    Persist the latest published sample if history is enabled, no write is in progress and its timestamp has not already been saved. Claim the write under the shared coordination lock, then perform database operations outside that lock. Store the compressed sample and associated topology in one transaction, deduplicating samples by timestamp. Apply age and storage-budget eviction, retain coverage events and remove topology no longer referenced by retained samples. On failure, roll back the transaction, retain the pending sample for retry and update failure status. Repeated identical warnings are throttled. A subsequent successful write records the failed interval for coverage reporting. Release the database handle and clear the write claim on completion. Does not collect observations or advance the sampling baseline; callers inspect history status for the persistence outcome.

    Testcases:
    No testcase defined.

  • history status (scripted, public)

     <instance of ns::stats::SQLiteHistory[i]> history status

    Return shared history configuration and persistence status without opening the database. Internal coordination and cached topology fields are omitted.

    Returns:
    Persistence status dictionary including owner, pool, retention, maxBytes, scheduler and write failures; enabled is false when never configured.

    Testcases:
    No testcase defined.

  • history storage (scripted, public)

     <instance of ns::stats::SQLiteHistory[i]> history storage

    Return retained bounds/count and SQLite space usage for sizing the dedicated history database. Run in the history owner server. Does not collect samples, write history or change its configuration.

    Returns:
    Dictionary of retained epoch-second bounds, sample count, SQLite page usage, effective byte cap and estimated bytes per sample/second; unavailable estimates are empty.

    Testcases:
    No testcase defined.