@velaro/cli 1.4.102 → 1.4.104

package/lib/commands/logs-insights.js

@@ -0,0 +1,342 @@
+// `velaro logs insights <groups|new|regression|trace|anomalies|sites|mutes|mute|unmute|sensitive|brief>`
+//
+// CLI parity for the Velaro Logger Insights UI (client/src/pages/Admin/VelaroLoggerInsights/).
+// All routes live on the MESSAGING api (superadmin/logs/insights/*), so every call goes through the
+// messaging helper, never the admin get/post/del helpers (guarded by messaging-routes.test.js).
+// Staff only: the server enforces it; requireStaff() just fails fast with a clear message.
+
+import { getCredentials, messagingRequest } from '../api.js';
+
+const RESET = '\x1b[0m';
+const DIM   = '\x1b[2m';
+const RED   = '\x1b[31m';
+const YEL   = '\x1b[33m';
+const CYN   = '\x1b[36m';
+const BOLD  = '\x1b[1m';
+
+export const INSIGHTS_BASE = 'superadmin/logs/insights';
+export const INSIGHTS_META = 'superadmin/logs/meta/insights';
+
+// ── pure helpers (unit-tested in logs-insights.test.js) ───────────────────────────────────────
+
+export function parseWindowMs(s, fallbackMs = 24 * 3600 * 1000) {
+  // Missing -> fallback. Present but malformed -> throw: silently widening a typo like "6hrs" to the
+  // default window would return data for the wrong period.
+  if (s === undefined || s === null || String(s).trim() === '') return fallbackMs;
+  const m = /^(\d+)\s*(m|h|d)$/i.exec(String(s).trim());
+  if (!m) throw new Error(`Invalid duration ${JSON.stringify(s)}: use a number plus m, h or d (e.g. 30m, 6h).`);
+  const n = parseInt(m[1], 10);
+  const unit = m[2].toLowerCase();
+  return n * (unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000);
+}
+
+/** Accepts an ISO timestamp or a relative "2h" / "30m" / "1d" (meaning that long ago). Returns a Date or null. */
+export function parseWhen(s, now = new Date()) {
+  if (!s) return null;
+  const rel = /^(\d+)\s*(m|h|d)$/i.exec(String(s).trim());
+  if (rel) return new Date(now.getTime() - parseWindowMs(s));
+  const d = new Date(String(s));
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/** Query string from a plain object, skipping undefined/null/empty. */
+export function qs(params) {
+  const sp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v === undefined || v === null || v === '') continue;
+    sp.set(k, String(v));
+  }
+  const s = sp.toString();
+  return s ? `?${s}` : '';
+}
+
+/** Params shared by every insights call, from yargs argv. */
+export function commonParams(argv) {
+  return {
+    level:       argv.level ? String(argv.level).toUpperCase() : undefined,
+    platform:    argv.platform,
+    environment: argv.environment,
+    siteId:      argv.site,
+  };
+}
+
+export function windowParams(argv, defaultWindow = '24h', now = new Date()) {
+  const to = now;
+  const from = new Date(to.getTime() - parseWindowMs(argv.last, parseWindowMs(defaultWindow)));
+  return { from: from.toISOString(), to: to.toISOString() };
+}
+
+/** "mute --expires" -> ISO or undefined (never). Throws on junk so the CLI never silently mutes forever. */
+export function parseExpiry(s, now = new Date()) {
+  if (s === undefined || s === null || s === '' || String(s).toLowerCase() === 'never') return undefined;
+  const d = parseWhen(s, now);
+  if (!d) throw new Error(`--expires must be "never", a duration like 7d / 12h, or an ISO date (got ${JSON.stringify(s)}).`);
+  // parseWhen treats durations as "ago"; for expiry we want "from now".
+  if (/^(\d+)\s*(m|h|d)$/i.test(String(s).trim())) return new Date(now.getTime() + parseWindowMs(s)).toISOString();
+  return d.toISOString();
+}
+
+export function ptTime(iso) {
+  if (!iso) return '-';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '-';
+  return `${d.toLocaleString('en-US', { timeZone: 'America/Los_Angeles', dateStyle: 'short', timeStyle: 'short' })} PT`;
+}
+
+export function trendText(pct) {
+  if (pct === null || pct === undefined || Number.isNaN(pct)) return 'n/a';
+  const r = Math.round(pct * 10) / 10;
+  if (Math.abs(r) < 1) return 'flat';
+  return r > 0 ? `up ${r}%` : `down ${Math.abs(r)}%`;
+}
+
+const BLOCKS = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+export function sparkline(values) {
+  if (!Array.isArray(values) || values.length === 0) return '';
+  const max = Math.max(...values, 1);
+  return values.map(v => BLOCKS[Math.min(BLOCKS.length - 1, Math.floor((Math.max(v, 0) / max) * (BLOCKS.length - 1)))]).join('');
+}
+
+// Strips control characters so log content can never inject terminal escape sequences.
+export function clean(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s ?? '').replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
+}
+
+function trunc(s, n) {
+  const t = clean(s).replace(/\s+/g, ' ');
+  return t.length > n ? `${t.slice(0, n - 1)}…` : t;
+}
+
+export function formatGroups(resp) {
+  const lines = [];
+  if (resp.servedFrom) lines.push(`${DIM}Showing ${resp.servedFrom} logs (served via ${String(resp.servedFrom).toLowerCase()} logger)${RESET}`);
+  if (resp.truncated) lines.push(`${YEL}Results capped${resp.scanned ? ` after scanning ${resp.scanned} rows` : ''}; narrow the window for complete numbers.${RESET}`);
+  const groups = resp.groups ?? [];
+  if (!groups.length) { lines.push('No error groups.'); return lines.join('\n'); }
+  for (const g of groups) {
+    const flags = `${g.isNew ? ` ${CYN}[new]${RESET}` : ''}${g.muted ? ` ${DIM}[muted]${RESET}` : ''}`;
+    lines.push(`${BOLD}${String(g.count).padStart(6)}${RESET} ${sparkline(g.sparkline)}${flags}  ${trunc(g.sampleMessage, 110)}`);
+    lines.push(`${DIM}       ${g.fingerprint}  ${trunc(g.logger ?? '-', 50)}  sites:${g.sitesCount}  ${ptTime(g.firstSeen)} -> ${ptTime(g.lastSeen)}${RESET}`);
+  }
+  return lines.join('\n');
+}
+
+export function formatRegression(r) {
+  const lines = [
+    `${BOLD}Before${RESET}: ${r.before?.total ?? 0} events, ${r.before?.errors ?? 0} errors    ${BOLD}After${RESET}: ${r.after?.total ?? 0} events, ${r.after?.errors ?? 0} errors`,
+  ];
+  if (r.truncated) lines.push(`${YEL}Results capped.${RESET}`);
+  lines.push(`\n${BOLD}New (${(r.newGroups ?? []).length})${RESET}`);
+  for (const g of r.newGroups ?? []) lines.push(`  ${String(g.count).padStart(5)}  ${trunc(g.sampleMessage, 110)}  ${DIM}${g.fingerprint}${RESET}`);
+  lines.push(`\n${BOLD}Increased (${(r.increased ?? []).length})${RESET}`);
+  for (const g of r.increased ?? []) lines.push(`  ${g.before} -> ${g.after} (${g.ratio == null ? 'from zero' : `${Number(g.ratio).toFixed(1)}x`})  ${trunc(g.sampleMessage, 100)}`);
+  lines.push(`\n${BOLD}Gone (${(r.gone ?? []).length})${RESET}`);
+  for (const g of r.gone ?? []) lines.push(`  ${g.before} -> 0  ${trunc(g.sampleMessage, 100)}`);
+  return lines.join('\n');
+}
+
+export function formatTrace(t) {
+  const lines = [`${BOLD}${(t.events ?? []).length} events${RESET} across ${(t.platformsSeen ?? []).join(', ') || 'no platforms'} over ${t.durationMs ?? 0} ms, ${t.errorCount ?? 0} error(s)`];
+  if (t.servedFrom) lines.push(`${DIM}Served via ${String(t.servedFrom).toLowerCase()} logger${RESET}`);
+  for (const e of t.events ?? []) {
+    const isErr = /^(ERROR|FATAL|CRITICAL)$/i.test(e.level ?? '');
+    const colour = isErr ? RED : RESET;
+    const lane = String(e.lane ?? e.platform ?? '?').padEnd(7);
+    lines.push(`${DIM}+${String(e.deltaMs ?? 0).padStart(6)}ms${RESET} ${lane} ${colour}${String(e.level ?? '?').padEnd(5)}${RESET} ${trunc(e.message, 120)}`);
+  }
+  return lines.join('\n');
+}
+
+export function formatAnomalies(a) {
+  const lines = [];
+  const buckets = a.buckets ?? [];
+  if (!buckets.length) return 'No hourly data.';
+  const max = Math.max(...buckets.map(b => b.count), 1);
+  for (const b of buckets) {
+    const bar = '█'.repeat(Math.round((b.count / max) * 30));
+    const flag = b.isAnomaly ? ` ${RED}ANOMALY z=${Number(b.z).toFixed(1)}${RESET}` : '';
+    const low = b.lowConfidence ? ` ${DIM}(low confidence)${RESET}` : '';
+    lines.push(`${ptTime(b.hourUtc).padEnd(20)} ${String(b.count).padStart(6)} ${bar}${flag}${low}`);
+  }
+  lines.push(`\n${(a.anomalies ?? []).length} anomalous hour(s).`);
+  return lines.join('\n');
+}
+
+export function formatSites(s) {
+  const sites = s.sites ?? [];
+  if (!sites.length) return 'No site-attributed events.';
+  const lines = [`${BOLD}${'SITE'.padEnd(8)}${'EVENTS'.padStart(8)}${'ERRORS'.padStart(8)}${'RATE'.padStart(8)}  TREND${RESET}`];
+  for (const x of sites) {
+    lines.push(`${String(x.siteId).padEnd(8)}${String(x.total).padStart(8)}${String(x.errors).padStart(8)}${`${(x.errorRate * 100).toFixed(1)}%`.padStart(8)}  ${trendText(x.trendPct)}`);
+    for (const g of (x.topGroups ?? []).slice(0, 2)) lines.push(`${DIM}         ${g.count}x ${trunc(g.sampleMessage, 100)}${RESET}`);
+  }
+  if (s.unattributed) lines.push(`\n${DIM}${s.unattributed} events had no site id.${RESET}`);
+  return lines.join('\n');
+}
+
+export function formatMutes(m) {
+  const mutes = m.mutes ?? [];
+  if (!mutes.length) return 'No active mutes.';
+  return mutes.map(x => `${x.fingerprint}  ${x.expiresAt ? `until ${ptTime(x.expiresAt)}` : 'never expires'}  ${trunc(x.reason, 80)}  ${DIM}${x.createdBy ?? ''}${RESET}`).join('\n');
+}
+
+export function formatSensitive(r) {
+  const f = r.findings ?? [];
+  if (!f.length) return 'No sensitive data found.';
+  const lines = f.map(x => `${String(x.count).padStart(6)}  ${String(x.type).padEnd(10)} ${trunc(x.sampleRedacted, 90)}  ${DIM}${trunc(x.logger ?? '-', 40)}${RESET}`);
+  if (r.truncated) lines.push(`${YEL}Results capped.${RESET}`);
+  return lines.join('\n');
+}
+
+// ── handlers ───────────────────────────────────────────────────────────────────────────────
+
+// Scans can be slow: 90s for reads/writes, 120s for the AI brief (the server may call a model).
+export const CALL_TIMEOUT_MS = 90_000;
+export const BRIEF_TIMEOUT_MS = 120_000;
+/** Server cap for from/to windows (meta.maxWindowHours today). Anomalies use --hours instead. */
+export const MAX_WINDOW_MS = 24 * 3_600_000;
+
+async function requireStaff(argv) {
+  const creds = await getCredentials(argv.env);
+  if (creds.siteId !== 1032) {
+    console.error('velaro logs insights is only available to Velaro staff (site 1032).');
+    process.exit(1);
+  }
+}
+
+/** Runs a call, prints JSON or the formatted view, and exits non-zero with the real status+body on failure. */
+async function run(argv, call, format) {
+  try {
+    await requireStaff(argv);
+    const data = await call();
+    if (argv.json) console.log(JSON.stringify(data, null, 2));
+    else console.log(`\n${format(data)}\n`);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+
+const call = (argv, method, path, body, timeoutMs = CALL_TIMEOUT_MS) =>
+  messagingRequest(method, `${INSIGHTS_BASE}/${path}`, body, argv.env, {}, { timeoutMs });
+
+const get = (argv, path, params = {}) => call(argv, 'GET', `${path}${qs(params)}`);
+
+/** Which of the shared filters an endpoint actually accepts. new / anomalies / regression take no site. */
+const NO_SITE = { site: false };
+const NO_SITE_NO_LEVEL = { site: false, level: false };
+
+export function scoped(argv, { site = true, level = true } = {}) {
+  const p = commonParams(argv);
+  if (!site) delete p.siteId;
+  if (!level) delete p.level;
+  return p;
+}
+
+/** Anomalies bucket by hour and only support ERROR or WARN. */
+export function anomalyLevel(level) {
+  const l = String(level ?? 'ERROR').toUpperCase();
+  if (l !== 'ERROR' && l !== 'WARN') throw new Error(`--level for anomalies must be ERROR or WARN (got ${JSON.stringify(level)}).`);
+  return l;
+}
+
+export const handlers = {
+  groups: argv => run(argv,
+    () => get(argv, 'groups', { ...windowParams(argv), ...scoped(argv), logger: argv.logger, take: argv.take, includeMuted: argv['include-muted'] ? 'true' : undefined }),
+    formatGroups),
+  new: argv => run(argv,
+    () => get(argv, 'new', { ...windowParams(argv), baselineDays: argv['baseline-days'], ...scoped(argv, NO_SITE) }),
+    formatGroups),
+  regression: argv => run(argv, () => {
+    const at = parseWhen(argv.at);
+    if (!at) throw new Error('--at is required: an ISO time or how long ago, e.g. --at 2h');
+    return get(argv, 'regression', { at: at.toISOString(), windowMinutes: argv.window, ...scoped(argv, NO_SITE_NO_LEVEL) });
+  }, formatRegression),
+  trace: argv => run(argv, () => {
+    const scope = { environment: argv.environment, platform: argv.platform };
+    if (argv.correlationId) return get(argv, 'trace', { correlationId: argv.correlationId, ...scope });
+    if (!argv.site) throw new Error('Give a correlation id, or --site with --last (window must be 1h or less).');
+    if (parseWindowMs(argv.last, 3_600_000) > 3_600_000) throw new Error('Trace by site needs --last of 1h or less.');
+    return get(argv, 'trace', { siteId: argv.site, ...windowParams(argv, '30m'), ...scope });
+  }, formatTrace),
+  anomalies: argv => run(argv,
+    () => get(argv, 'anomalies', { hours: argv.hours, ...scoped(argv, NO_SITE), level: anomalyLevel(argv.level) }),
+    formatAnomalies),
+  sites: argv => run(argv,
+    () => get(argv, 'sites/scorecard', { ...windowParams(argv), take: argv.take, ...scoped(argv, NO_SITE_NO_LEVEL) }),
+    formatSites),
+  mutes: argv => run(argv, () => get(argv, 'mutes', { environment: argv.environment }), formatMutes),
+  mute: argv => run(argv, () => {
+    if (!argv.reason || !String(argv.reason).trim()) throw new Error('--reason is required when muting a group.');
+    return call(argv, 'POST', 'mutes', {
+      fingerprint: argv.fingerprint,
+      reason: String(argv.reason).trim(),
+      expiresAt: parseExpiry(argv.expires),
+      environment: argv.environment,
+    });
+  }, r => `Muted ${r?.fingerprint ?? ''}${r?.environment ? ` (${r.environment})` : ''}`.trim()),
+  unmute: argv => run(argv,
+    async () => { await call(argv, 'DELETE', `mutes/${encodeURIComponent(argv.fingerprint)}${qs({ environment: argv.environment })}`); return { unmuted: argv.fingerprint }; },
+    r => `Unmuted ${r.unmuted}`),
+  sensitive: argv => run(argv,
+    () => get(argv, 'sensitive', { ...windowParams(argv), ...scoped(argv, NO_SITE_NO_LEVEL) }),
+    formatSensitive),
+  brief: argv => run(argv, () => {
+    // The server needs a time window in BOTH modes (a fingerprint alone has no time scope), capped at
+    // the server's from/to maximum. siteId is sent whenever --site is given.
+    const requested = parseWindowMs(argv.last, MAX_WINDOW_MS);
+    const win = windowParams({ last: `${Math.max(1, Math.floor(Math.min(requested, MAX_WINDOW_MS) / 60_000))}m` });
+    const body = { ...win, platform: argv.platform, environment: argv.environment, siteId: argv.site };
+    if (argv.fingerprint) body.fingerprint = argv.fingerprint;
+    return call(argv, 'POST', 'brief', body, BRIEF_TIMEOUT_MS);
+  }, r => `${r.markdown}\n\n${DIM}${r.groupsUsed} group(s) used${r.model ? `, ${r.model}` : ''}${typeof r.costUsd === 'number' ? `, $${r.costUsd.toFixed(4)}` : ''}${RESET}`),
+};
+
+// ── yargs command ──────────────────────────────────────────────────────────────────────────
+
+const common = y => y
+  .option('last',        { describe: 'Time window: 30m, 6h, 24h (server maximum is 24h; anomalies use --hours)', default: '24h', type: 'string' })
+  .option('platform',    { describe: 'v10, v20 or admin', type: 'string' })
+  .option('environment', { describe: 'Production or Staging (server may federate to the other logger; mutes are per environment)', type: 'string' })
+  .option('env',         { describe: 'CLI login to use: staging or prod', type: 'string' })
+  .option('json',        { describe: 'Print the raw JSON response', type: 'boolean', default: false });
+
+const withSite = y => y.option('site', { describe: 'Filter by site ID', type: 'number' });
+
+export const logsInsightsCommand = {
+  command:  'insights <subcommand>',
+  describe: 'Error groups, regressions, anomalies, traces and more (Velaro staff only)',
+  builder: yargs => yargs
+    .command({ command: 'groups', describe: 'Top error groups (grouped by fingerprint)',
+      builder: y => withSite(common(y)).option('level', { default: 'ERROR', type: 'string' }).option('logger', { type: 'string' }).option('take', { default: 50, type: 'number' }).option('include-muted', { type: 'boolean', default: false }),
+      handler: handlers.groups })
+    .command({ command: 'new', describe: 'Error groups first seen in the window (not in the baseline); no site filter',
+      builder: y => common(y).option('level', { default: 'ERROR', type: 'string' }).option('baseline-days', { default: 7, type: 'number' }),
+      handler: handlers.new })
+    .command({ command: 'regression', describe: 'Compare the window before vs after a deploy time (all levels, no site filter)',
+      builder: y => common(y).option('at', { describe: 'Deploy time: ISO or how long ago (2h)', type: 'string', demandOption: true }).option('window', { describe: 'Minutes before/after', default: 60, type: 'number' }),
+      handler: handlers.regression })
+    .command({ command: 'trace [correlationId]', describe: 'Cross-platform timeline for a correlation id (or --site with a --last of 1h or less)',
+      builder: y => withSite(common(y)).positional('correlationId', { type: 'string' }),
+      handler: handlers.trace })
+    .command({ command: 'anomalies', describe: 'Hourly counts vs baseline, flags anomalous hours (ERROR or WARN; no site filter)',
+      builder: y => common(y).option('hours', { describe: 'Hours of history (server maximum: meta.maxAnomalyHours, 168 today)', default: 24, type: 'number' }).option('level', { describe: 'ERROR or WARN', default: 'ERROR', type: 'string' }),
+      handler: handlers.anomalies })
+    .command({ command: 'sites', describe: 'Per-site error scorecard',
+      builder: y => common(y).option('take', { default: 25, type: 'number' }),
+      handler: handlers.sites })
+    .command({ command: 'mutes', describe: 'List active mutes for --environment', builder: y => common(y), handler: handlers.mutes })
+    .command({ command: 'mute <fingerprint>', describe: 'Mute an error group in --environment (reason required)',
+      builder: y => common(y).positional('fingerprint', { type: 'string' }).option('reason', { type: 'string', demandOption: true }).option('expires', { describe: 'never, 7d, 12h, or an ISO date', default: '7d', type: 'string' }),
+      handler: handlers.mute })
+    .command({ command: 'unmute <fingerprint>', describe: 'Remove a mute from --environment',
+      builder: y => common(y).positional('fingerprint', { type: 'string' }),
+      handler: handlers.unmute })
+    .command({ command: 'sensitive', describe: 'Scan logs for emails, tokens, card numbers and similar',
+      builder: y => common(y), handler: handlers.sensitive })
+    .command({ command: 'brief [fingerprint]', describe: 'AI brief for one error group, or the whole window (always scoped to --last, max 24h)',
+      builder: y => withSite(common(y)).positional('fingerprint', { type: 'string' }),
+      handler: handlers.brief })
+    .demandCommand(1, 'Specify a subcommand: groups, new, regression, trace, anomalies, sites, mutes, mute, unmute, sensitive, or brief'),
+};