::nsmcp::Tool ::nsmcp::Tool describe execute init jsonArguments name permission validate ::nsmcp::Object ::nsmcp::Object dict getdef ::nsmcp::Tool->::nsmcp::Object ::nsmcp::AccessSummaryTool ::nsmcp::AccessSummaryTool execute options validate ::nsmcp::AccessSummaryTool->::nsmcp::Tool

Class ::nsmcp::AccessSummaryTool

::nsmcp::AccessSummaryTool[i] create ... \
           [ -adminExample (default "") ] \
           [ -adminSummary (default "") ] \
           [ -analytics:required analytics:required ] \
           [ -description (default "Query the continuously populated shared access store; this reader does not parse or import logs. Live lag, historical backfill, record-age retention and shorter peer-address retention are explicit. Legacy configurations retain their previous cache behavior. Poll log_results with jobHandle. Defaults to the last 60 completed minutes. Use lastMinutes or period previous-hour for relative intervals, or reuse windowHandle to freeze bounds across comparisons. Time selectors are mutually exclusive; explicit from/to remain supported. Counts use request start times when available. Sub-minute bucketSeconds (1, 5, 10, 15, 30) supports peak analysis, with at most 3600 buckets. Sub-minute windows round outwards to bucket boundaries; other windows round to minutes. Counts are observed retained-cache traffic, not certified full-log totals; coverage reports recent-scan progress, historical backfill, completion-order assumptions, and possible rotation gaps. Reports authenticationStates aggregates derived from the logged user field (0 or - anonymous, other nonempty identities authenticated; old cache rows unknown). Does not disclose user identities. Supports authenticationState, exact path, status and pool filters and timing breakdowns by status. Coverage separates live-tail lag, historical backfill, cumulative parsing failures and outward bucket rounding; do not treat the rounded future minute as ingestion lag. Optional windowSeconds finds the maximum requests from one logged peer in a rolling inclusive window within the selected period; default 600 seconds. Peer addresses are retained internally; peer filtering and disclosure require diagnostics.logs.peers.read. Existing cache rows may lack peers; inspect unknownPeerCount, observedPeerCountsComplete, peerCountsComplete and peerCountsIncompleteReasons. Observed peer fields can be complete while the requested log window is incomplete; peerCountsIncompleteReasons explains both. Top paths omit queries and may be incomplete when cardinality limits are reached.") ] \
           [ -inputSchema (default "
        {
            "type": "object",
            "properties": {
                "lastMinutes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1440,
                    "description": "Trailing minutes ending at the last completed minute; default 60"
                },
                "period": {
                    "type": "string",
                    "enum": [
                        "previous-hour"
                    ],
                    "description": "Previous complete UTC clock hour"
                },
                "windowHandle": {
                    "type": "string",
                    "description": "Reuse bounds returned by an earlier summary; owned by this principal and server"
                },
                "from": {
                    "type": "integer",
                    "description": "Unix epoch seconds; explicit interval start"
                },
                "to": {
                    "type": "integer",
                    "description": "Unix epoch seconds; explicit interval end"
                },
                "authenticationState": {
                    "type": "string",
                    "enum": [
                        "anonymous",
                        "authenticated",
                        "unknown"
                    ]
                },
                "path": {
                    "type": "string",
                    "description": "Exact queryless path"
                },
                "peer": {
                    "type": "string",
                    "description": "Exact logged IP address; requires peer permission"
                },
                "windowSeconds": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 3600,
                    "description": "Rolling peer burst duration, defaults to 600; inclusive endpoints. Use 0 to skip peer-burst calculation for traffic-only analysis."
                },
                "includePeerAddresses": {
                    "type": "boolean",
                    "description": "Disclose the burst peer; requires peer permission"
                },
                "pool": {
                    "type": "string",
                    "description": "Exact connection pool"
                },
                "status": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 599,
                    "description": "HTTP status"
                },
                "bucketSeconds": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 3600,
                    "description": "1, 5, 10, 15, 30, or a multiple of 60; at most 3600 buckets"
                }
            },
            "additionalProperties": false
        }
    ") ] \
           [ -name (default "access_summary") ] \
           [ -outputSchema (default "") ] \
           [ -permission (default "diagnostics.logs.read") ] \
           [ -service:required service:required ]
Defined in /usr/local/ns/tcl/nsmcp/access-tools.tcl

Class Relations

  • class: ::nx::Class[i]
  • superclass: ::nsmcp::Tool[i]
::nx::Class create ::nsmcp::AccessSummaryTool \
     -superclass ::nsmcp::Tool

Methods (to be applied on instances)

  • execute (scripted, public)

     <instance of nsmcp::AccessSummaryTool[i]> execute context arguments

    Start an owned access-log summary operation. Resolve retained window handles through the service before queuing the validated summary options.

    Parameters:
    context (required)
    Authenticated request context carrying the principal, grants and selected server.
    arguments (required)
    Rooted ns_json typed triples for the tool's JSON argument object.
    Returns:
    A rooted JSON tool-result object, including availability or job metadata as appropriate.

    Testcases:
    No testcase defined.
    set options [:options $arguments]
if {[dict exists $options windowHandle]} {
    set bounds [${:service} resolveWindow $context [dict get $options windowHandle]]
    dict unset options windowHandle
    set options [${:analytics} validateWindow [dict merge $options $bounds]]
}
return [${:service} start $context accessSummary $options]

  • options (scripted, public)

     <instance of nsmcp::AccessSummaryTool[i]> options arguments

    Decode and validate access-summary tool options. Convert the rooted JSON arguments to the supported query and pagination settings.

    Parameters:
    arguments (required)
    Rooted ns_json typed triples for the tool's JSON argument object.
    Returns:
    A Tcl dictionary of access-summary options.

    Testcases:
    No testcase defined.
    set options {windowSeconds 600}
if {[lindex $arguments 1] ne "object"} {
    error "Expected arguments object"
}
foreach {key type value} [lindex $arguments 2] {
    if {$key eq "includePeerAddresses"} {
        if {$type ne "boolean"} {
            error "Expected boolean includePeerAddresses"
        }
    } elseif {$key in {path pool peer authenticationState period windowHandle}} {
        if {$type ne "string"} {
            error "Expected string path or pool"
        }
    } elseif {$key ni {from to bucketSeconds status windowSeconds lastMinutes} || $type ne "number" || ![string is entier -strict $value]} {
        error "Expected integer times/status or string path/pool"
    }
    dict set options $key $value
}
set selectors 0
foreach key {lastMinutes period windowHandle} {
    if {[dict exists $options $key]} {
        incr selectors
    }
}
set explicit [expr {[dict exists $options from] || [dict exists $options to]}]
if {$selectors>1 || ($selectors && $explicit)} {
    error "Use one of lastMinutes, period, windowHandle, or explicit from/to"
}
if {[dict exists $options windowHandle]} {
    set handle [dict get $options windowHandle]
    if {![regexp {^[0-9a-f]{64}$} $handle]} {
        error "Invalid windowHandle"
    }
    dict unset options windowHandle
    set checked [${:analytics} validateWindow $options]
    dict unset checked from
    dict unset checked to
    dict set checked windowHandle $handle
    return $checked
}
set now [clock seconds]
if {[dict exists $options period]} {
    if {[dict get $options period] ne "previous-hour"} {
        error "period must be previous-hour"
    }
    dict unset options period
    set end [expr {($now/3600)*3600}]
    dict set options from [expr {$end-3600}]
    dict set options to $end
} elseif {[dict exists $options lastMinutes] || !$explicit} {
    set minutes 60
    if {[dict exists $options lastMinutes]} {
        set minutes [dict get $options lastMinutes]
        dict unset options lastMinutes
    }
    if {$minutes<1 || $minutes>1440} {
        error "lastMinutes must be between 1 and 1440"
    }
    set end [expr {($now/60)*60}]
    dict set options from [expr {$end-$minutes*60}]
    dict set options to $end
}
return [${:analytics} validateWindow $options]

  • validate (scripted, public)

     <instance of nsmcp::AccessSummaryTool[i]> validate arguments

    Validate access-summary arguments. Decode the rooted JSON argument object and enforce this tool's option, range and combination constraints.

    Parameters:
    arguments (required)
    Rooted ns_json typed triples for the tool's JSON argument object.
    Returns:
    An empty result on success; invalid input raises RPC error -32602.

    Testcases:
    No testcase defined.
    if {[catch {
    :options $arguments
} message]} {
    return -code error -errorcode {NSMCP RPC -32602} $message
}