::nx::EnsembleObject ::ns::stats::Sampler::slot::_

Methods: All Methods Documented Methods Hide Methods
Source: Display Source Hide Source
Variables: Show Variables Hide Variables

Class Relations

class: ::nx::EnsembleObject

::nx::EnsembleObject create ::ns::stats::Sampler::slot::__sampling

Methods (to be applied on the object)

history (scripted)

#
# 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.
#
# @param from Inclusive lower bound in epoch seconds; must be nonnegative.
# @param to Exclusive upper bound in epoch seconds; after from, at most 24 hours later
#     and no later than now.
# @param server Optional historical virtual-server name; empty returns all stored server
#     data.
# @param limit Maximum records per page, 1..180; default 180.
# @param cursor Nonnegative timestamp cursor in microseconds, default 0; pass nextCursor
#     unchanged for continuation.
# @return Dictionary containing records, retained bounds, coverage, more and nextCursor
#     for the in-memory history buffer.
#
if {$from<0 || $to<=$from || $to-$from>86400 || $to>[clock seconds]
    || $limit<1 || $limit>180 || $cursor<0} {
    error "expected an epoch window up to 24 hours, limit 1..180 and nonnegative cursor"
}
if {[string length $server]>512 || [string first \x00 $server]>=0} {
    error "invalid server name"
}
:locked {
    set retained [nsv_get ns_stats recent]
    set dropped [nsv_get ns_stats recentDroppedThrough]
}
set records {}
set gaps {}
set restarts {}
set resets 0
set previous {}
set first {}
set last {}
set more false
foreach record $retained {
    set stamp [dict get $record timestamp]
    if {$first eq ""} {
        set first $stamp
    }
    set last $stamp
    if {$stamp<$from*1000000 || $stamp<=$cursor} {
        set previous $record
        continue
    }
    if {$stamp>=$to*1000000} {
        # A gap crossing the upper bound must not certify coverage.
        if {$previous ne ""} {
            set delta [expr {($stamp-[dict get $previous timestamp])/1000000.0}]
            if {$delta>1.5*max([dict get $previous sampling intervalSeconds],
                               [dict get $record sampling intervalSeconds])} {
                lappend gaps [dict create from [dict get $previous sampling to] to [dict get $record sampling to]]
            }
        }
        break
    }
    if {[llength $records]>=$limit} {
        set more true
        break
    }
    if {![dict get $record sampling ready]} {
        incr resets
    }
    if {$previous ne ""} {
        if {[dict get $previous instance] ne [dict get $record instance]} {
            lappend restarts [dict get $record sampling to]
        }
        set delta [expr {($stamp-[dict get $previous timestamp])/1000000.0}]
        if {$delta>1.5*max([dict get $previous sampling intervalSeconds],
                           [dict get $record sampling intervalSeconds])} {
            lappend gaps [dict create from [dict get $previous sampling to] to [dict get $record sampling to]]
        }
    }
    lappend records [:selectServer [dict remove $record cpu] $server false]
    set previous $record
}
# Retained bounds refer to the buffer, independently of the selected page.
if {$retained ne ""} {
    set first [dict get [lindex $retained 0] timestamp]
    set last [dict get [lindex $retained end] timestamp]
}
set overlap [expr {$dropped ne "" && $dropped>=$from*1000000}]
if {!$more && $cursor>0} {
    set window [:sampling history -from $from -to $to -server $server -limit 180]
    set coverage [dict get $window coverage]
    return [dict create schemaVersion 1 source memory from $from to $to records $records  nextCursor {} more false retentionSeconds 900 maxSamples 180 coverage $coverage]
}
set complete [expr {$first ne "" && $first<=$from*1000000 && $last>=$to*1000000
                     && !$more && $cursor==0 && !$overlap && $gaps eq ""
                     && $restarts eq "" && $resets==0}]
set next {}
if {$more} {
    set next [dict get [lindex $records end] timestamp]
}
return [dict create schemaVersion 1 source memory from $from to $to records $records  nextCursor $next more $more retentionSeconds 900 maxSamples 180  coverage [dict create complete $complete windowExamined [expr {!$more && $cursor==0}]  retainedFrom [expr {$first eq "" ? 0 : $first/1000000.0}]  retainedTo [expr {$last eq "" ? 0 : $last/1000000.0}]  gaps $gaps restartBoundaries $restarts resetSamples $resets  evictionOrFailureOverlap $overlap droppedThrough $dropped]]

start (scripted)

#
# 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.
#
# @param interval Sampling cadence, accepting ns_baseunit time syntax; 1..3600 seconds,
#     default 10 seconds.
# @return Resulting sampling status dictionary.
#

set interval [ns_baseunit -time $interval]
if {$interval < 1 || $interval > 3600} {
    error "interval must be 1..3600 seconds"
}
:locked {
    set state [nsv_get ns_stats control]
    if {[dict get $state running]} {
        if {[dict get $state interval]!=$interval} {
            error "sampler already running with a different interval; stop it before reconfiguring"
        }
    } else {
        dict incr state generation
        dict set state running true
        dict set state interval $interval
        dict set state busy false
        dict set state scheduler [ns_schedule_proc -thread $interval [self] sampling tick]
        nsv_set ns_stats pair {}
        nsv_set ns_stats control $state
    }
}
return [:sampling status]

status (scripted)

#
# 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.
#
# @return Status dictionary including running, interval in seconds, scheduler, instance,
#     errors, lastError, ready, latestAt and ageSeconds.
#

set result [nsv_get ns_stats control]
dict unset result busy
dict unset result generation
set sample [nsv_get ns_stats pair]
dict set result ready [expr {$sample ne "" && [dict get $sample sampling ready]}]
dict set result latestAt {}
dict set result ageSeconds {}
if {$sample ne ""} {
    set stamp [dict get $sample timestamp]
    dict set result latestAt [expr {$stamp/1000000.0}]
    dict set result ageSeconds [expr {max(0,([clock microseconds]-$stamp)/1000000.0)}]
}
return $result

stop (scripted)

#
# 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.
#
# @return Resulting sampling status dictionary; the last published sample remains
#     available.
#
:locked {
    set state [nsv_get ns_stats control]
    if {[dict get $state running]} {
        ns_unschedule_proc [dict get $state scheduler]
    }
    dict set state running false
    dict incr state generation
    dict set state busy false
    dict set state scheduler {}
    nsv_set ns_stats control $state
}
return [:sampling status]

tick (scripted)

#
# 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.
#
#
set generation {}
:locked {
    set state [nsv_get ns_stats control]
    if {![dict get $state running] || [dict get $state busy]} {
        return
    }
    set generation [dict get $state generation]
    dict set state busy true
    nsv_set ns_stats control $state
}
if {$generation eq ""} {
    return
}
try {
    set current [:snapshot]
    :locked {
        set state [nsv_get ns_stats control]
        if {$generation!=[dict get $state generation]} {
            return
        }
        set pair [nsv_get ns_stats pair]
        set previous [expr {$pair eq "" ? "" : [dict get $pair raw]}]
        set sample [:calculate $current $previous [dict get $state interval] [dict get $state instance]]
        :retainSample $sample
        dict set sample raw $current
        nsv_set ns_stats pair $sample
        dict set state busy false
        dict set state lastError {}
        nsv_set ns_stats control $state
    }
} on error {message options} {
    :locked {
        set state [nsv_get ns_stats control]
        if {$generation == [dict get $state generation]} {
            dict set state busy false
            dict incr state errors
            dict set state lastError $message
            nsv_set ns_stats control $state
        }
    }
    ns_log warning "ns_stats: sampling failed: $message"
}

Methods: All Methods Documented Methods Hide Methods
Source: Display Source Hide Source
Variables: Show Variables Hide Variables