@intflow/sentinelctl 0.2.0 → 0.3.1

package/README.md

@@ -52,10 +52,15 @@ sentinelctl logs search -l error -f                        # follow new errors (
 sentinelctl logs search -q boom -o ndjson | jq .message
 sentinelctl logs context -a <agent-id> -s app.service -t 2026-09-30T01:02:03.456Z
 sentinelctl logs histogram -l error -r 24h
+sentinelctl logs stats -l error -r 1h --by source          # exact counts, one server-side query
+sentinelctl logs stats -l error -r 24h --by agent --top 10
+sentinelctl logs stats -a <agent-id> -r 7d --by message    # message patterns, numbers collapsed to <N>
 sentinelctl logs sources -r 24h
 ```
 
-Windows are `15m`, `1h`, `6h`, `24h`, `7d`, or `--from`/`--to` up to 30 days. One page holds 50, 100 or 250 logs; when you ask for several pages (`--pages N`, `--all`) the CLI fetches 250 per request, up to the server cap of 10,000. `--fields` (raw fields) is admin-only and audited.
+Windows are `15m`, `1h`, `6h`, `24h`, `7d`, or `--from`/`--to` up to 30 days. One page holds 50, 100 or 250 logs; when you ask for several pages (`--pages N`, at most 40, or `--all`) the CLI fetches 250 per request and stops at 10,000 logs. To answer "how many" or "which devices the most", use `logs stats`: it aggregates on the server and returns exact counts instead of downloading logs. `--fields` (raw fields) is admin-only and audited. `--follow` polls at most every 5 seconds.
+
+Each user can run 2 log queries at a time, web and CLI combined; a third concurrent query gets 429 and GET requests retry automatically.
 
 ## Devices and metadata
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intflow/sentinelctl",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Sentinel Fleet Console CLI: search device logs, inspect status and metrics, edit metadata and manage roles",
   "type": "module",
   "bin": {

package/src/commands.mjs

@@ -9,6 +9,7 @@ const deviceRanges = ['30m', '1h', '6h', '24h', '7d', '30d'];
 const logLevels = ['emergency', 'critical', 'error', 'warning', 'info', 'debug'];
 const deviceStatuses = ['all', 'online', 'delayed', 'offline', 'unknown', 'maintenance', 'retired'];
 const lifecycles = ['operational', 'all', 'active', 'maintenance', 'retired'];
+const maxPages = 40;
 const deviceSorts = ['attention', 'status', 'displayName', 'cpu', 'memory', 'disk', 'load', 'temperature', 'ageSeconds', 'role', 'site', 'group', 'incidentCount'];
 
 const logFilterOptions = {
@@ -75,11 +76,14 @@ async function logsSearch(context, { options, positionals }) {
   const limit = options.fields ? 50 : (options.limit ?? (paging ? 250 : 100));
   const query = { ...criteria, limit, includeFields: options.fields ? 1 : undefined };
   if (options.follow) return followLogs(context, query, options);
-  const maxPages = options.all ? 200 : Math.max(1, options.pages ?? 1);
+  if (options.pages !== undefined && (options.pages < 1 || options.pages > maxPages)) {
+    throw new UsageError(`--pages must be between 1 and ${maxPages}.`, { hint: 'For counts over large windows use `sentinelctl logs stats` instead of fetching logs.' });
+  }
+  const pageBudget = options.all ? maxPages : (options.pages ?? 1);
   const logs = [];
   let cursor;
   let last;
-  for (let page = 0; page < maxPages; page += 1) {
+  for (let page = 0; page < pageBudget; page += 1) {
     last = await context.client.get('/api/logs', { ...query, cursor });
     logs.push(...last.logs);
     if (!last.hasMore || !last.nextCursor) break;
@@ -92,12 +96,13 @@ async function logsSearch(context, { options, positionals }) {
   }
   if (!logs.length) context.hint(emptyLogHint(criteria));
   else context.note(`${logs.length} logs · ${localTime(last.window.start)} → ${localTime(last.window.end)}`);
-  if (last.hasMore) context.hint('More logs match. Continue with --pages N or --all (up to 10,000), or narrow the filters.');
+  if (last.hasMore && options.all) context.hint(`Stopped at the ${maxPages * 250}-log cap. Narrow the filters, or use \`sentinelctl logs stats\` for counts.`);
+  else if (last.hasMore) context.hint('More logs match. Continue with --pages N or --all (up to 10,000), narrow the filters, or count them with `sentinelctl logs stats`.');
 }
 
 async function followLogs(context, query, options) {
   const seen = new Set();
-  const intervalMs = Math.max(2, options.interval) * 1_000;
+  const intervalMs = Math.max(5, options.interval) * 1_000;
   const followQuery = { ...query, range: '15m', from: undefined, to: undefined, limit: query.includeFields ? 50 : 250 };
   let first = true;
   context.err('Following new logs. Press Ctrl+C to stop.');
@@ -123,6 +128,26 @@ async function followLogs(context, query, options) {
   }
 }
 
+
+const statsDimensions = ['source', 'agent', 'level', 'message'];
+
+async function logsStats(context, { options, positionals }) {
+  const criteria = logCriteria(options, positionals);
+  const body = await context.client.get('/api/logs/stats', { ...criteria, by: options.by, top: options.top });
+  const label = { source: 'SOURCE', agent: 'DEVICE', level: 'LEVEL', message: 'MESSAGE PATTERN' }[body.criteria.by];
+  emit(context, context.global.output === 'ndjson' ? body.groups : body, () => renderTable(body.groups, [
+    { header: 'COUNT', value: (group) => String(group.count) },
+    { header: 'SHARE', value: (group) => (body.total ? `${((group.count / body.total) * 100).toFixed(1)}%` : '-') },
+    { header: 'DEVICES', value: (group) => String(group.devices) },
+    ...(body.criteria.by === 'agent' ? [{ header: 'AGENT ID', value: (group) => group.key, max: 36 }] : []),
+    { header: label, value: (group) => (body.criteria.by === 'agent' ? group.displayName ?? group.host ?? group.key : group.key) },
+  ], { width: context.width, wide: options.wide }));
+  context.note(`${body.total} logs from ${body.devices} devices · ${localTime(body.window.start)} → ${localTime(body.window.end)}`);
+  if (body.truncated) context.hint(`Showing the top ${body.groups.length} of ${body.groupCount} groups. Raise --top (max 100) or add filters.`);
+  if (body.approximate) context.hint('Message patterns are approximate on this server (collapse_nums is unavailable); narrow the window or filters for exact counts.');
+  if (!body.total) context.hint(emptyLogHint(criteria));
+}
+
 async function logsContext(context, { options }) {
   if (!options.agent || !options.source || !options.timestamp) {
     throw new UsageError('--agent, --source and --timestamp are all required.',
@@ -237,10 +262,24 @@ async function devicesLookup(context, { positionals }) {
 async function devicesOverview(context, { options, positionals }) {
   const agentId = requireAgentId(positionals);
   const body = await context.client.get(`/api/devices/${encodeURIComponent(agentId)}/overview`, { range: options.range });
-  emit(context, body, () => renderKeyValues([
-    ['Agent ID', body.agentId], ['Name', body.device?.displayName], ['Metrics', body.products?.metrics?.state],
-    ['Logs', body.products?.logs?.state], ['Attention', (body.attentionReasons ?? []).join(', ') || 'none'],
-    ['Related', (body.related ?? []).map((item) => item.agentId ?? item).join(', ')],
+  const summary = Object.fromEntries(['metrics', 'logs'].map((product) => {
+    const history = body.history?.products?.[product]?.summary ?? {};
+    return [product, {
+      state: body.products?.[product]?.state ?? null,
+      outages: history.incidentCount ?? null,
+      delays: history.delayedCount ?? null,
+      missingMinutes: Number.isFinite(history.missingSeconds) ? Math.round(history.missingSeconds / 60) : null,
+      longestOutageMinutes: Number.isFinite(history.longestMissingSeconds) ? Math.round(history.longestMissingSeconds / 60) : null,
+      normalRatio: Number.isFinite(history.normalRatio) ? Math.round(history.normalRatio * 1000) / 10 : null,
+    }];
+  }));
+  const describe = (item) => `${item.state ?? '-'} · ${item.outages ?? '-'} ${item.outages === 1 ? 'outage' : 'outages'}, ${item.missingMinutes ?? '-'} min missing (longest ${item.longestOutageMinutes ?? '-'} min), normal ${item.normalRatio ?? '-'}%`;
+  emit(context, { summary, ...body }, () => renderKeyValues([
+    ['Agent ID', body.agentId], ['Name', body.device?.displayName], ['Window', options.range],
+    ['Metrics', describe(summary.metrics)], ['Logs', describe(summary.logs)],
+    ['Attention', (body.attentionReasons ?? []).join(', ') || 'none'],
+    ['Hypervisor', body.related?.parent ? `${body.related.parent.displayName} (${body.related.parent.agentId})` : body.related?.expectedParent ?? null],
+    ['VMs', (body.related?.children ?? []).map((child) => child.displayName ?? child.agentId).join(', ') || null],
   ]));
 }
 
@@ -514,16 +553,16 @@ const commands = [
   {
     group: 'logs', name: 'search', run: logsSearch, role: 'viewer', mutates: false,
     summary: 'Search logs by window, device, severity, source and text; or follow live',
-    description: 'Newest first. Default 15m window and 100 logs. When fetching several pages, 250 logs are fetched per request.',
+    description: 'Newest first. Default 15m window and 100 logs. When fetching several pages, 250 logs are fetched per request, up to 10,000 in total. To count or rank logs, use `logs stats` instead.',
     args: [{ name: 'text', optional: true, description: 'Same as -q (words are joined with spaces).' }],
     options: {
       ...logFilterOptions,
       limit: { alias: 'n', type: 'integer', choices: [50, 100, 250], description: 'Logs per page. Default 100 (250 when paging).' },
-      pages: { type: 'integer', placeholder: 'N', description: 'Follow the cursor for up to N pages.' },
-      all: { type: 'boolean', description: 'Fetch every page of the window (server cap: 10,000 logs).' },
+      pages: { type: 'integer', placeholder: 'N', description: `Follow the cursor for up to N pages (1-${maxPages}).` },
+      all: { type: 'boolean', description: 'Fetch every page of the window, stopping at 10,000 logs.' },
       fields: { type: 'boolean', description: 'Include raw fields (admin only, audited, 50 logs per page).' },
       follow: { alias: 'f', type: 'boolean', description: 'Keep printing new logs (for humans; never ends, agents should not use it).' },
-      interval: { type: 'integer', default: 5, placeholder: 'seconds', description: 'Polling interval for --follow (min 2).' },
+      interval: { type: 'integer', default: 5, placeholder: 'seconds', description: 'Polling interval for --follow (min 5).' },
       wide: { alias: 'w', type: 'boolean', description: 'Do not truncate messages in table output.' },
     },
     roleFor: (options) => (options.fields ? 'admin' : 'viewer'),
@@ -536,6 +575,25 @@ const commands = [
     ],
     output: 'logs[]: timestamp (UTC ISO), severity, priority, agentId, host, displayName, source, message (+fields). -o json wraps them as {criteria, window, count, hasMore, logs}.',
   },
+  {
+    group: 'logs', name: 'stats', run: logsStats, role: 'viewer', mutates: false,
+    summary: 'Count and rank logs by source, device, severity or message pattern (one server-side query)',
+    description: 'Aggregates in VictoriaLogs instead of downloading logs, so counts are exact over the whole window. message groups by pattern with numbers collapsed to <N>. Cached for 60s on the server.',
+    args: [{ name: 'text', optional: true, description: 'Same as -q.' }],
+    options: {
+      ...logFilterOptions,
+      by: { alias: 'b', type: 'string', choices: statsDimensions, default: 'source', description: 'Group by source, agent (device), level or message pattern.' },
+      top: { type: 'integer', default: 20, placeholder: 'N', description: 'Groups to return (1-100).' },
+      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate long keys in table output.' },
+    },
+    examples: [
+      'sentinelctl logs stats -l error -r 1h --by source',
+      'sentinelctl logs stats -l error -r 24h --by agent --top 10 -o json',
+      'sentinelctl logs stats -a <agent-id> -r 7d --by message',
+      'sentinelctl logs stats "connection refused" -r 24h --by agent',
+    ],
+    output: '{criteria, window, total, devices, groupCount, truncated, approximate, groups[]: {key, count, devices (distinct agents), host?, displayName?}}.',
+  },
   {
     group: 'logs', name: 'context', run: logsContext, role: 'viewer', mutates: false,
     summary: 'Logs just before and after one log, from the same device and source',
@@ -613,11 +671,11 @@ const commands = [
   },
   {
     group: 'devices', name: 'overview', run: devicesOverview, role: 'viewer', mutates: false,
-    summary: 'Metrics and log reception state, outage history and attention reasons',
+    summary: 'Reception state, outage counts and durations, and attention reasons for one device',
     args: [{ name: 'agent-id' }],
     options: { range: { alias: 'r', type: 'string', default: '24h', placeholder: 'window', description: 'History window, e.g. 24h or 7d.' } },
     examples: ['sentinelctl devices overview <agent-id> -r 7d -o json'],
-    output: '{agentId, device, products{metrics, logs}, attentionReasons[], history, related[]}.',
+    output: '{summary{metrics, logs}: {state, outages, delays, missingMinutes, longestOutageMinutes, normalRatio}, agentId, device, products, attentionReasons[], history, related{parent, children[], expectedParent}}.',
   },
   {
     group: 'metadata', name: 'get', run: metadataGet, role: 'viewer', mutates: false,
@@ -754,7 +812,7 @@ const commands = [
 
 export const catalog = commands;
 export const groups = {
-  logs: 'Search logs, context around a log, volume trends, sources',
+  logs: 'Search, count and rank logs; context around a log; volume trends; sources',
   devices: 'Device list, details, lookup, reception overview',
   metadata: 'Device metadata: read, edit (editor), import/export (admin)',
   sessions: 'Your sessions and CLI tokens',

package/src/main.mjs

@@ -137,10 +137,14 @@ const agentGuide = `Using sentinelctl from AI agents and scripts
    - metrics:        devices show <id> -r 24h -o json           (series.cpu etc. are [epochSeconds, value])
    - logs:           logs search -a <id> -l error -r 24h -o ndjson
                      then logs context -a <id> -s <source> -t <timestamp> for surrounding lines
+   - counts/ranking: logs stats -l error -r 24h --by agent|source|message -o json
    - trend:          logs histogram -a <id> -r 7d -o json
 6. Efficiency
-   - Narrow the window and filters (-a, -s, -l, -q) first. Use --pages N to take only what you need
-     (--all fetches up to 10,000 logs).
+   - To answer "how many" or "which devices/sources the most", use logs stats: one server-side
+     aggregation with exact counts. Do not download thousands of logs to count them.
+   - Narrow the window and filters (-a, -s, -l, -q) first. Use --pages N (max 40) to take only what you
+     need; --all stops at 10,000 logs.
+   - Each user can run 2 log queries at a time (web and CLI combined); run commands one after another.
    - Do not use --follow (it never ends). Repeat a -r 15m search instead.
    - The server caches identical log searches for 5s, histograms and sources for 60s.
 7. For commands that change data (metadata set/bulk/rollback/import, admin ...), run with --dry-run