---

Class ::nsmcp::AccessSummaryTool

::nsmcp::AccessSummaryTool 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
• superclass: ::nsmcp::Tool

Methods (to be applied on instances)

• execute (scripted, public)

   <instance of nsmcp::AccessSummaryTool> 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.

• options (scripted, public)

   <instance of nsmcp::AccessSummaryTool> 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.

• validate (scripted, public)

   <instance of nsmcp::AccessSummaryTool> 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.

---