---

Class ::nsmcp::AccessSummaryTool

::nsmcp::AccessSummaryTool create ... \
           [ -analytics:required analytics:required ] \
           [ -description (default "Start an incremental access-log summary; 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. Windows are rounded outwards to minutes; coverage reports recent-scan progress, historical backfill, completion-order assumptions, and possible rotation gaps. Supports 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 and peerCountsComplete. Top paths omit queries and may be incomplete when cardinality limits are reached.") ] \
           [ -inputSchema (default "{} object {type string object properties object {
        lastMinutes object {type string integer minimum number 1 maximum number 1440 description string {Trailing minutes ending at the last completed minute; default 60}}
        period object {type string string enum array {0 string previous-hour} description string {Previous complete UTC clock hour}}
        windowHandle object {type string string description string {Reuse bounds returned by an earlier summary; owned by this principal and server}}
        from object {type string integer description string {Unix epoch seconds; explicit interval start}}
        to object {type string integer description string {Unix epoch seconds; explicit interval end}}
        path object {type string string description string {Exact queryless path}}
        peer object {type string string description string {Exact logged IP address; requires peer permission}}
        windowSeconds object {type string integer minimum number 1 maximum number 3600 description string {Rolling peer burst duration, defaults to 600; inclusive endpoints}}
        includePeerAddresses object {type string boolean description string {Disclose the burst peer; requires peer permission}}
        pool object {type string string description string {Exact connection pool}}
        status object {type string integer minimum number 100 maximum number 599 description string {HTTP status}}
        bucketSeconds object {type string integer minimum number 60 maximum number 3600 multipleOf number 60}
    } additionalProperties boolean false}") ] \
           [ -name (default "access_summary") ] \
           [ -outputSchema (default "") ] \
           [ -permission (default "diagnostics.logs.read") ] \
           [ -service:required service:required ]

Defined in /usr/local/ns/tcl/nsmcp/lib/access-tools.tcl

Class Relations

• class: ::nx::Class
• superclass: ::nsmcp::Tool

::nx::Class create ::nsmcp::AccessSummaryTool \
     -superclass ::nsmcp::Tool

Methods (to be applied on instances)

• execute (scripted, public)

   <instance of nsmcp::AccessSummaryTool> execute context arguments

  Parameters:

  context (required)

  arguments (required)

  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> options arguments

  Parameters:

  arguments (required)

  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 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> validate arguments

  Parameters:

  arguments (required)

  Testcases:

  No testcase defined.

  if {[catch {:options $arguments} message]} {
      return -code error -errorcode {NSMCP RPC -32602} $message
  }

---