---

Class ::ns::stats::Sampler

::ns::stats::Sampler create ...

Defined in

Class Relations

• class: ::nx::Class
• superclass: ::ns::stats::Collector
• subclass: ::ns::ns_stats

Methods (to be applied on instances)

• calculate (scripted, public)

   <instance of ns::stats::Sampler> 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)

  previous (required)

  interval (required)

  instance (required)

  Testcases:

  No testcase defined.

• sample (scripted, public)

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

  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. Does not collect observations or advance the baseline. The internal raw baseline is omitted from the returned dictionary.

  Switches:

  -server (optional)

  Testcases:

  No testcase defined.

• sampling start (scripted, public)

   <instance of ns::stats::Sampler> 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")

  Testcases:

  No testcase defined.

• sampling status (scripted, public)

   <instance of ns::stats::Sampler> 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.

  Testcases:

  No testcase defined.

• sampling stop (scripted, public)

   <instance of ns::stats::Sampler> 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.

  Testcases:

  No testcase defined.

• sampling tick (scripted, public)

   <instance of ns::stats::Sampler> 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.

---