::ns::stats::Sampler ::ns::stats::Sampler calculate delta init locked retainSample sample sampling history sampling start sampling status sampling stop sampling tick ::ns::stats::Collector ::ns::stats::Collector cpuCapacity cpuListCount describe mountPath selectServer snapshot systemText ::ns::stats::Sampler->::ns::stats::Collector ::ns::ns_stats ::ns::ns_stats history persist startup ::ns::ns_stats->::ns::stats::Sampler

Class ::ns::stats::Sampler

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

Class Relations

  • class: ::nx::Class[i]
  • superclass: ::ns::stats::Collector[i]
  • subclass: ::ns::ns_stats[i]

Methods (to be applied on instances)

  • calculate (scripted, public)

     <instance of ns::stats::Sampler[i]> calculate current previous \
    interval instance

    Derive interval diagnostics from current and previous snapshots. Return the current observations augmented with counter deltas, rates, average request phase times and thread CPU percentages. Rates use measured elapsed time; interval records the configured sampling cadence, and instance identifies the sampler lifetime. Interval results require a previous snapshot from the same process lifetime and positive elapsed time. Missing baselines or decreased counters yield empty derived values. CPU comparisons match thread identifiers and creation times; percentages use one core as 100%. Does not collect observations or modify shared state.

    Parameters:
    current (required)
    Current snapshot dictionary, including its epoch-microsecond timestamp and process identity.
    previous (required)
    Previous snapshot dictionary, or empty when no baseline exists.
    interval (required)
    Configured sampling cadence in seconds; rates use actual elapsed time instead.
    instance (required)
    Sampler lifetime identifier attached to the calculated sample.
    Returns:
    Current observations augmented with sampling metadata, counter deltas, rates, average timings and CPU percentages; unavailable derived values remain empty.

    Testcases:
    No testcase defined.

  • sample (scripted, public)

     <instance of ns::stats::Sampler[i]> sample [ -server server ] \
    [ -window window ]

    Return the latest published sample, updating its reported age and running state. Before any publication, return a dictionary with sampling readiness false and no interval observations. An optional server argument restricts virtual-server data; CPU measurements remain process-wide. Without -window, does not collect observations or advance the baseline. With -window (0..900 seconds, time units accepted), collect a fresh snapshot and compare it with the nearest retained endpoint to that age (within half a sampling interval). Missing history, gaps or sampler restarts leave readiness false. The measured elapsedSeconds reports the actual selected period. The internal raw baseline is omitted from the returned dictionary.

    Switches:
    -server (optional)
    Optional virtual-server name; empty returns all servers. CPU metrics remain process-wide.
    -window (optional, defaults to "0")
    Requested display period, accepting ns_baseunit time syntax; 0..900 seconds, default 0 for the latest published sample.
    Returns:
    Sample dictionary with sampling readiness and age; a positive window adds freshly calculated interval metrics when a suitable continuous baseline exists.

    Testcases:
    No testcase defined.

  • sampling history (scripted, public)

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

    Read the bounded process-wide recent sample buffer without SQLite. Retains at most 180 compact samples and 15 minutes at publication. Returns interval metrics, coverage and timestamp-based paging. Raw/per-thread CPU counters are omitted. Reading does not collect, start sampling, advance baselines or write persistent history. The buffer survives sampler stop/start but not a process restart.

    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; empty returns all stored server data.
    -limit (optional, integer, defaults to "180")
    Maximum records per page, 1..180; default 180.
    -cursor (optional, integer, defaults to "0")
    Nonnegative timestamp cursor in microseconds, default 0; pass nextCursor unchanged for continuation.
    Returns:
    Dictionary containing records, retained bounds, coverage, more and nextCursor for the in-memory history buffer.

    Testcases:
    No testcase defined.

  • sampling start (scripted, public)

     <instance of ns::stats::Sampler[i]> sampling start \
    [ -interval interval ]

    Start the process-wide sampling callback at the requested interval in seconds (default 10, range 1..3600). Time units and fractional seconds are normalized with ns_baseunit. Repeated calls with the same running interval reuse the scheduler; a different interval requires stopping the sampler first. Clears the previous sample and baseline when starting a stopped sampler. Returns the resulting status dictionary. Persistence must be enabled separately.

    Switches:
    -interval (optional, defaults to "10")
    Sampling cadence, accepting ns_baseunit time syntax; 1..3600 seconds, default 10 seconds.
    Returns:
    Resulting sampling status dictionary.

    Testcases:
    No testcase defined.

  • sampling status (scripted, public)

     <instance of ns::stats::Sampler[i]> sampling status

    Return the process-wide sampler configuration and status, including running state, scheduler identifier, interval, process instance, collection errors and readiness of the latest interval sample. latestAt is in epoch seconds; ageSeconds is the elapsed time since the latest publication. Both are empty before the first sample. Does not collect new observations or modify sampler state.

    Returns:
    Status dictionary including running, interval in seconds, scheduler, instance, errors, lastError, ready, latestAt and ageSeconds.

    Testcases:
    No testcase defined.

  • sampling stop (scripted, public)

     <instance of ns::stats::Sampler[i]> sampling stop

    Unschedule collection and invalidate any collection already in progress so it cannot publish into the stopped sampler. Retains the latest published sample for subsequent reads. Returns the resulting status dictionary. Does not disable the separately configured history persistence callback.

    Returns:
    Resulting sampling status dictionary; the last published sample remains available.

    Testcases:
    No testcase defined.

  • sampling tick (scripted, public)

     <instance of ns::stats::Sampler[i]> sampling tick

    Perform one scheduled collection and publish its interval sample. Skip collection when the sampler is stopped or another collection is in progress. Collect observations outside the coordination lock, then calculate and publish only if the sampler generation is still current. Retain the raw snapshot as the next interval baseline. Collection failures retain the previous publication, update error status and emit a warning. Does not write SQLite history; persistence runs through a separate callback.

    Testcases:
    No testcase defined.