---

Class ::nsmcp::AccessFileSummaryTool

::nsmcp::AccessFileSummaryTool create ... \
           [ -adminExample (default "") ] \
           [ -adminSummary (default "") ] \
           [ -description (default "Start broad/day traffic analysis with mode totals to read stored status/context counts without importing missing records or computing origin rankings. totals.coverage reports missing source bytes, countsCompleteForSnapshots and whether counts are lower bounds; zero stored records with incomplete ingestion is not zero traffic. If storage is disabled or busy, counts are unavailable, never fabricated. Use one bounded evidence query for paths/origins, clearly separate its prefix from stored totals. When accessRecordDirectory is configured, summary mode incrementally stores parsed uncompressed ranges and reuses them through indexed SQL; recordStorage reports ingestion/reuse and persistence. Compressed-source jobs and evidence mode retain the direct scanner. Storage is private per server with configurable retention and disk budget; SQL temporary sort files are outside that database/journal budget. Scan configured access-log files in a background job, independent of cache retention. Failed-traffic analysis supports status OR statusClass, exact pool/method and recordSource (all/driver/connection/unknown). All selected counts, rankings, origins and samples are computed after filters. Failed-traffic answers must include the returned paths ranking with counts and its breakdowns.paths capacity/ranking omissions. Path/status aggregation is independent of SQLite peer/User-Agent storage: identity aggregation failure does not justify replacing path rankings with samples. aggregateStorage.failure gives a bounded phase/class/code/diagnosticId; poolWaitCount and poolWaitMilliseconds describe bounded transient pool retries. waiting-aggregation yields without consuming log records. Do not infer a disk-limit failure from pool contention. context counts the same scanned time/path/pool/method/source traffic before status filtering; trafficBuckets provide up to 50 busiest occupied buckets with explicit omissions. Use bucketSeconds 1 for short bursts (at most 3600 buckets); default about 60 buckets. Driver pool and protocol-module labels come from the log header only. Driver names are reused threads, not unique request IDs. Driver 503 does not prove queue-full; queueFullReasonAvailable is false. Driver synthetic timing phases never enter timing averages; unavailableTimingCount is separate from timestamp fallbackCount. statusTimings separate admitted-worker measurements by response status. Default selection ordered reads endpoint records and seeks by request-start timestamps under an explicit approximate ordering assumption, with five seconds of selection padding filtered against the original bounds; completion timestamps are fallback values. Observed inversions exceeding five seconds or unusable probes fall back to bounded scanning. This does not certify unsampled ordering or include every delayed completion. Use selection exhaustive for full verification. For prompt origin hints start with mode evidence (default 5000 matching records, at most 50000 parsed candidates, 32MiB byte budget, maxRecords 1..10000). Its bounded prefix rankings describe only the observed evidence span, not the entire requested interval; follow with mode summary only when full counts are needed. Poll log_results with jobHandle until complete; the result is a summary, not record pages. Omit pathLiteral for all parsed request paths, including empty or non-slash targets. Use pathLiteral ".php" for case-sensitive literal substring matching on the logged queryless path, never query values; no regexp or URL decoding. Defaults to today UTC; set timezone for today/yesterday, or lastMinutes, or explicit from/to. includeRotations defaults true and includes recognized numbered/dated siblings and gzip rotations. ASCII literals use bounded ns_fseekchars candidate searches; Unicode/ANSI cases retain conservative parsing. In exhaustive selection, a bounded server-local time index stores exhaustive start-time bounds for byte ranges independently of path filters. It skips unrelated rotations and seeks over disjoint ranges without assuming timestamp order. Cold scans build the index; changed/append-only snapshots verify complete cached ranges by digest before exclusion, counting verification reads against the scan budget. Unknown, malformed, oversized and unindexed ranges are scanned. Cache metadata is bounded and lost on process restart; filenames and endpoint samples never prove absence. coverage.rotationsSkippedOutsideWindow and eligibleFilesFullyExamined distinguish verified pruning from missing coverage. Parsing diagnostics in literal mode concern candidates and fallback rows, not every unrelated record. Fixed snapshots, bounded streaming/decompression, file/byte/cardinality limits and changed/unreadable files are reported. Counts use logged request start time, falling back to completion time; end is exclusive. Returns all-match totals before bounded path, method, status, pool, UTC-hour, redacted User-Agent and address-free peer-concentration rankings, authentication states, timing totals and distributed samples including status below 400. When a native SQLite aggregation pool is configured (accessAggregationPool, falling back to databasePool), peers and full User-Agent identity hashes are counted in a private per-job SQLite spool with bounded buffers and disk budget. Otherwise aggregateStorage explicitly reports bounded-memory fallback. maxGroups 1..50 limits rankings, not scanning. Inspect aggregateStorage status/reason, breakdowns storageOmittedRecords separately from capacity/ranking omissions, exact observedDistinctPeers/observedDistinctUserAgents and peerConcentration top1/top10/top100 shares. Exactness concerns scanned matching records, not retention or verified identities. Unknown values, clipped/redacted labels, storage failures and ranking omissions are separate. Counts are access records, not unique requests/incidents. No user IDs, peer addresses, query strings or caller-supplied filenames are exposed. sourceFullyExamined does not certify full-day retention; windowComplete remains false without verified rotation history.") ] \
           [ -inputSchema (default "{"type":"object","properties":{"selection":{"type":"string","enum":["ordered","exhaustive"],"default":"ordered","description":"ordered uses endpoint start times and byte bisection, assuming sorted start times; exhaustive retains full scanning/index verification"},"mode":{"type":"string","enum":["summary","evidence","totals"],"default":"summary"},"maxRecords":{"type":"integer","minimum":1,"maximum":10000,"default":5000,"description":"Maximum matching records in evidence mode; a separate candidate ceiling is max(50000,10*maxRecords). Results are a bounded prefix, not an unbiased window distribution"},"pathLiteral":{"type":"string","minLength":1,"maxLength":256,"description":"Case-sensitive literal substring in the logged queryless path, at most 256 UTF-8 bytes; no regexp or decoding"},"includeRotations":{"type":"boolean","default":true},"period":{"type":"string","enum":["today","yesterday"]},"timezone":{"type":"string"},"lastMinutes":{"type":"integer","minimum":1,"maximum":10080},"from":{"type":"integer","minimum":0},"to":{"type":"integer","minimum":1},"maxGroups":{"type":"integer","minimum":1,"maximum":50},"status":{"type":"integer","minimum":100,"maximum":599,"description":"Exact HTTP response status; mutually exclusive with statusClass"},"statusClass":{"type":"string","enum":["1xx","2xx","3xx","4xx","5xx","4xx/5xx"],"description":"Response status class; 4xx/5xx selects all failed responses. Mutually exclusive with status"},"pool":{"type":"string","minLength":1,"maxLength":128,"description":"Exact case-sensitive pool, including driver pool suffixes; unknown is explicit"},"method":{"type":"string","minLength":1,"maxLength":32,"description":"Exact uppercase HTTP method"},"recordSource":{"type":"string","enum":["all","driver","connection","unknown"],"default":"all","description":"Driver identifies synthetic driver-side access records, not a unique request or proven queue-full reason"},"bucketSeconds":{"type":"integer","minimum":1,"description":"Positive seconds, at most 3600 buckets; default about 60 buckets across the window. Returns top 50 occupied buckets with omission counts."}},"additionalProperties":false}") ] \
           [ -name (default "access_log_summary") ] \
           [ -outputSchema (default "") ] \
           [ -permission (default "diagnostics.logs.read") ] \
           [ -service:required service:required ]

Defined in /usr/local/ns/tcl/nsmcp/log-traffic-summary.tcl

Class Relations

• class: ::nx::Class
• superclass: ::nsmcp::LogErrorSummaryTool

::nx::Class create ::nsmcp::AccessFileSummaryTool \
     -superclass ::nsmcp::LogErrorSummaryTool

---