datagrok-tools 6.7.9 → 6.7.10

package/bin/commands/server-observe.js

@@ -6,17 +6,20 @@ Object.defineProperty(exports, "__esModule", {
 exports.OBSERVE_USAGE = void 0;
 exports.fieldRows = fieldRows;
 exports.handleObserve = handleObserve;
+exports.matchFilter = matchFilter;
 exports.parseDuration = parseDuration;
 exports.parseTime = parseTime;
+exports.printRequestLog = printRequestLog;
 exports.setPath = setPath;
 var fs = _interopRequireWildcard(require("fs"));
+var _crypto = require("crypto");
 var _nodeDapi = require("../utils/node-dapi");
 var _serverOutput = require("../utils/server-output");
 var _walker = require("../utils/migrate/walker");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 /// `grok s observe` (alias `grok s o`): problems, problem rules, logger settings, errors, the timeline and cloud logs,
 /// over `/problems`, `/admin/plugins/<key>/settings`, `/alerts/Test_rules`, `/log`, `/admin/metrics`, `/log/timeline`,
-/// `/log/cloud/*`, `/log/archive/*` and `/docker/containers`.
+/// `/log/cloud/*`, `/log/archive/*`, `/log/match`, `/log/activations` and `/docker/containers`.
 
 const OBSERVE_USAGE = exports.OBSERVE_USAGE = `Usage: grok s observe <command> <verb> [args]      (alias: grok s o)
 
@@ -25,6 +28,8 @@ const OBSERVE_USAGE = exports.OBSERVE_USAGE = `Usage: grok s observe <command> <
   problems get <id|kind:key>           One field per line, details by path
   problems history <id|kind:key> [--limit 50]
   problems status <id|kind:key> --data '{"status": "muted", "reason": "...", "until": "<ISO>"}' | --json body.json
+  problems severity <id|kind:key> <info|warning|critical|none> [--reason <text>]
+                                       Pin the severity its raises use; none unpins it
   problems ack <id|kind:key> --reason <text>
   problems resolve <id|kind:key> --reason <text>
   rules get                            The problem rules (Settings > Alerts), as JSON
@@ -64,10 +69,40 @@ const OBSERVE_USAGE = exports.OBSERVE_USAGE = `Usage: grok s observe <command> <
                                        read them with timeline --session <id>
   logs capture stop <login|group>      Remove that expiring entry; one that holds other settings is left
                                        to logger set --remove
+  logs match ['<filter>'] [--level l1,l2] [--user <login>] [--package <p>] [--source <s>] [--type <t>]
+             [--function <f>] [--session <id>] [--grep <regex>] [--space <path>] [--since 1h] [--limit 1000]
+                                       Saved and in-memory records a log filter matches, newest first: the
+                                       filter of a log group (Settings > Logger), quoted as one argument, e.g.
+                                       'level in (error, warning) and not text ~ ResizeObserver'; the flags add
+                                       conditions joined by and; --grep and --space match case-sensitively
+                                       (--space: the space and its subspaces)
+  logs activations [stop <group id> <key>]
+                                       Triggered log groups that are on now; stop ends one
+  logs request <logId>                 What the requests of one command logged (grok s ... --log prints
+                                       its logId), gathered from every instance's memory; once only
+  groups [list]                        Log groups (Settings > Logger): what is recorded and where it goes
+  groups get <name|id>
+  groups add --name <n> [--kind records|alerts|drop] [--levels error,warning] [--flags db,auth]
+             [--filter '<filter>'] [--to db,console,<endpoint name>[:format]] [--who <group ids>]
+             [--until 2h|<ISO> [--reason <text>]] [--when '<filter>' --scope session|user|global --for 15m --before 60s]
+             [--alert-kinds health,storage] [--min-severity warning] [--audit-types t1,t2] [--usage-types t1,t2]
+  groups set <name|id> [same flags] [--enabled false] [--always]
+                                       Only the flags given change
+  groups rm <name|id>
+  groups put --json groups.json        Replace every log group with a JSON array
+  groups reset                         Back to the default log groups
+  endpoints [list] | endpoints rm <name|id>
+                                       Where log groups can send records (OTLP, CloudWatch, Google, ClickHouse)
 
 Durations are 30m (minutes), 24h, 7d, 2w; times are ISO 8601 (UTC without an offset) or
-relative, written with = (--from=-2h).`;
+relative, written with = (--from=-2h).
+
+Any grok s command takes --log [<spec>]: its requests share one logId, every instance keeps what they
+log at <spec> (verbose, standard, levels, debug flags or all, comma-separated) in memory, and the
+command gathers and prints it to stderr at the end, as logs request does; functions run --debug adds
+the debug call's own log.`;
 const UNIT_MS = {
+  s: 1000,
   m: 60000,
   h: 3600000,
   d: 86400000,
@@ -76,8 +111,8 @@ const UNIT_MS = {
 
 /** `30m`, `2h`, `7d`, `1w` in milliseconds; `m` is minutes, unlike `grok s pull --since`, where it is months. */
 function parseDuration(value, flag) {
-  const m = /^(\d+)([mhdw])$/.exec(String(value ?? '').trim());
-  if (!m || Number(m[1]) <= 0) throw new Error(`${flag} expects a duration such as 30m, 2h, 7d or 1w, got '${value}'`);
+  const m = /^(\d+)([smhdw])$/.exec(String(value ?? '').trim());
+  if (!m || Number(m[1]) <= 0) throw new Error(`${flag} expects a duration such as 60s, 30m, 2h, 7d or 1w, got '${value}'`);
   return Number(m[1]) * UNIT_MS[m[2]];
 }
 
@@ -191,6 +226,17 @@ async function handleObserve(dapi, command, verb, rest, argv, output) {
       await needId();
       (0, _serverOutput.printOutput)(await dapi.raw('POST', `${problemPath()}/status`, readBody(argv)), output);
       return true;
+    case 'problems severity':
+      {
+        await needId();
+        const severity = rest[1];
+        if (!['info', 'warning', 'critical', 'none'].includes(severity)) throw new Error('Usage: grok s observe problems severity <id|kind:key> <info|warning|critical|none> [--reason <text>]');
+        (0, _serverOutput.printOutput)(await dapi.raw('POST', `${problemPath()}/severity`, {
+          severity: severity === 'none' ? null : severity,
+          reason: argv.reason
+        }), output);
+        return true;
+      }
     case 'problems ack':
     case 'problems resolve':
       await needId();
@@ -303,14 +349,16 @@ async function handleObserve(dapi, command, verb, rest, argv, output) {
         return true;
       }
   }
+  if (command === 'groups' || command === 'endpoints' || command === 'logs' && verb === 'activations') return logGroups(dapi, command, verb, rest, argv, await settings('logger'), saveLogger, output);
   if (command === 'logs' && verb === 'capture') return capture(dapi, rest, argv, await settings('logger'), saveLogger, output);
   if (command === 'logs') return logs(dapi, verb, rest, argv, output);
   if (command === 'timeline') {
     if (argv.session === undefined) throw new Error('Usage: grok s observe timeline --session <id> [--from <ISO|-15m>] [--to <ISO>] [--limit 500]');
     needFrom(argv);
+    const now = Date.now();
     const window = argv.from === undefined ? {
-      from: iso('-15m', '--from'),
-      to: new Date().toISOString()
+      from: new Date(now - 15 * 60000).toISOString(),
+      to: new Date(now).toISOString()
     } : {
       from: iso(argv.from, '--from'),
       to: iso(argv.to, '--to')
@@ -327,6 +375,234 @@ async function handleObserve(dapi, command, verb, rest, argv, output) {
 const needFrom = argv => {
   if (argv.to !== undefined && argv.from === undefined) throw new Error('--to needs --from');
 };
+const oneOf = (value, flag, choices) => {
+  if (choices && !choices.includes(value)) throw new Error(`${flag} is one of ${choices.join(', ')}, not '${value}'`);
+  return value;
+};
+
+/// The comma list of `--<flag>`, each value one of [choices] when given.
+const list = (argv, flag, choices) => {
+  if (argv[flag] === true) throw new Error(`--${flag} needs a value`);
+  return String(argv[flag]).split(',').map(x => x.trim()).filter(Boolean).map(v => oneOf(v, `--${flag}`, choices));
+};
+const LEVELS = ['error', 'warning', 'info', 'debug', 'audit', 'usage'];
+const DEBUG_FLAGS = ['db', 'socket', 'query', 'hash', 'storage', 'credentials', 'balloon', 'startup', 'srcmaps', 'docker', 'auth', 'ai-indexing', 'email', 'all'];
+
+/// A duration in whole units of [unit] ms; 0 is allowed.
+const durationIn = (value, flag, unit, unitName) => {
+  if (String(value).trim() === '0') return 0;
+  const ms = parseDuration(value, flag);
+  if (ms % unit !== 0) throw new Error(`${flag} expects whole ${unitName}, got '${value}'`);
+  return ms / unit;
+};
+
+/// A log group of the logger settings by id or name.
+function findGroup(groups, ref) {
+  const byId = groups.find(g => g.id === ref);
+  if (byId) return byId;
+  const named = groups.filter(g => g.name === ref);
+  if (named.length !== 1) throw new Error(named.length ? `More than one log group is named '${ref}': use its id` : `No log group '${ref}'`);
+  return named[0];
+}
+
+/// `groups add|set` flags applied to [g]; only the flags given change it.
+function applyGroupFlags(g, argv) {
+  if (argv.name !== undefined) g.name = String(argv.name);
+  if (argv.kind !== undefined) g.kind = oneOf(String(argv.kind), '--kind', ['records', 'alerts', 'drop']);
+  if (argv.enabled !== undefined) g.enabled = argv.enabled === true || argv.enabled === 'true';
+  if (argv.who !== undefined) g.who = list(argv, 'who');
+  if (argv.levels !== undefined) g.levels = list(argv, 'levels', LEVELS);
+  if (argv.flags !== undefined) g.debugFlags = list(argv, 'flags', DEBUG_FLAGS);
+  if (argv['audit-types'] !== undefined) g.auditTypes = list(argv, 'audit-types');
+  if (argv['usage-types'] !== undefined) g.usageTypes = list(argv, 'usage-types');
+  if (argv.filter !== undefined) g.filter = String(argv.filter) || null;
+  if (argv['alert-kinds'] !== undefined) g.alertKinds = list(argv, 'alert-kinds');
+  if (argv['min-severity'] !== undefined) g.alertMinSeverity = oneOf(String(argv['min-severity']), '--min-severity', ['info', 'warning', 'critical']);
+  if (argv.to !== undefined) {
+    const old = g.saveTo ?? [];
+    const to = list(argv, 'to');
+    if (!to.length) throw new Error('--to needs a value');
+    g.saveTo = to.map(t => {
+      const [destination, format] = t.split(':');
+      return {
+        ...(old.find(x => x.destination === destination) ?? {}),
+        destination,
+        ...(format ? {
+          format
+        } : {})
+      };
+    });
+  }
+  if (argv.until !== undefined) {
+    g.activation = 'until';
+    g.until = /^\d+[smhdw]$/.test(String(argv.until)) ? new Date(Date.now() + parseDuration(String(argv.until), '--until')).toISOString() : iso(argv.until, '--until');
+  }
+  if (argv.reason !== undefined) g.reason = String(argv.reason);
+  if (argv.when !== undefined) {
+    g.activation = 'triggered';
+    g.triggerWhen = String(argv.when);
+  }
+  if (argv.scope !== undefined) g.triggerScope = oneOf(String(argv.scope), '--scope', ['session', 'user', 'global']);
+  if (argv.for !== undefined) g.activeMinutes = durationIn(argv.for, '--for', 60000, 'minutes');
+  if (argv.before !== undefined) g.flushBeforeSeconds = durationIn(argv.before, '--before', 1000, 'seconds');
+  if (argv.always) g.activation = 'always';
+  return g;
+}
+
+/// `groups ...`, `endpoints ...` and `logs activations`: the log groups and endpoints of Settings > Logger.
+async function logGroups(dapi, command, verb, rest, argv, current, save, output) {
+  if (command === 'endpoints') {
+    const endpoints = current.exportSettings ?? [];
+    if (verb === 'list' || verb === undefined) {
+      (0, _serverOutput.printOutput)(output === 'table' ? endpoints.map(e => ({
+        name: e.name ?? '',
+        type: e['#type'],
+        enabled: e.isEnabled !== false,
+        target: e.endpoint ?? e.url ?? e.cloudWatchLogGroup ?? e.logName ?? '',
+        id: e.id
+      })) : endpoints, output);
+      return true;
+    }
+    if (verb === 'rm' && rest[0] !== undefined) {
+      const ref = String(rest[0]);
+      const e = endpoints.find(x => x.id === ref || x.name === ref);
+      if (!e) throw new Error(`No endpoint '${ref}'`);
+      current.exportSettings = endpoints.filter(x => x !== e);
+      for (const g of current.logGroups ?? []) g.saveTo = (g.saveTo ?? []).filter(t => t.destination !== e.id && t.destination !== e.name);
+      await save(current);
+      (0, _serverOutput.printOutput)({
+        removed: e.name ?? e.id
+      }, output);
+      return true;
+    }
+    throw new Error('Usage: grok s observe endpoints list | endpoints rm <name|id>   (add one with logger set --set ' + '\'exportSettings=[...]\' or GROK_PARAMETERS settings.logger.exportSettings)');
+  }
+  if (command === 'logs' && verb === 'activations') {
+    if (rest[0] === 'stop') {
+      if (rest[1] === undefined || rest[2] === undefined) throw new Error('Usage: grok s observe logs activations stop <group id> <key>');
+      await dapi.raw('DELETE', `/log/activations${(0, _nodeDapi.buildQuery)({
+        group: rest[1],
+        key: rest[2]
+      })}`);
+      (0, _serverOutput.printOutput)({
+        stopped: `${rest[1]} ${rest[2]}`
+      }, output);
+      return true;
+    }
+    (0, _serverOutput.printOutput)(await dapi.raw('GET', '/log/activations'), output);
+    return true;
+  }
+  const groups = current.logGroups ?? [];
+  // A server older than the effective list answers null until groups are saved; starting from none would drop the defaults.
+  if (['add', 'set', 'rm'].includes(verb) && !Array.isArray(current.logGroups)) throw new Error('The server does not return its default log groups, so they cannot be edited one by one: ' + 'replace them all with groups put --json <file>');
+  const ref = () => {
+    if (rest[0] === undefined) throw new Error(`Usage: grok s observe groups ${verb} <name|id>`);
+    return findGroup(groups, String(rest[0]));
+  };
+  switch (verb) {
+    case undefined:
+    case 'list':
+      (0, _serverOutput.printOutput)(output === 'table' ? groups.map(g => ({
+        name: g.name ?? '',
+        kind: g.kind ?? 'records',
+        enabled: g.enabled !== false,
+        active: g.activation ?? 'always',
+        levels: (g.levels ?? []).join(',') || 'all',
+        filter: g.filter ?? '',
+        to: (g.saveTo ?? []).map(t => t.format ? `${t.destination}:${t.format}` : t.destination).join(','),
+        id: g.id
+      })) : groups, output);
+      return true;
+    case 'get':
+      (0, _serverOutput.printOutput)(ref(), output === 'table' ? 'json' : output);
+      return true;
+    case 'add':
+      {
+        if (argv.name === undefined) throw new Error('Usage: grok s observe groups add --name <name> [--kind records|alerts|drop] [--levels error,warning] ' + '[--flags db] [--filter \'<filter>\'] [--to db,console,<endpoint>[:format]] [--who <group ids>] [--until 2h|<ISO>] ' + '[--when \'<filter>\' --scope session --for 15m --before 60s]');
+        const g = applyGroupFlags({
+          id: (0, _crypto.randomUUID)(),
+          kind: 'records',
+          enabled: true,
+          who: [],
+          levels: [],
+          debugFlags: [],
+          activation: 'always',
+          saveTo: [{
+            destination: 'db'
+          }]
+        }, argv);
+        current.logGroups = [...groups, g];
+        await save(current);
+        (0, _serverOutput.printOutput)(g, output === 'table' ? 'json' : output);
+        return true;
+      }
+    case 'set':
+      {
+        const g = ref();
+        applyGroupFlags(g, argv);
+        current.logGroups = groups;
+        await save(current);
+        (0, _serverOutput.printOutput)(g, output === 'table' ? 'json' : output);
+        return true;
+      }
+    case 'rm':
+      {
+        const g = ref();
+        if (g.protected) throw new Error(`'${g.name ?? g.id}' is the audit group: it can only be switched off (--enabled false), which needs EditAuditLogging`);
+        current.logGroups = groups.filter(x => x !== g);
+        await save(current);
+        (0, _serverOutput.printOutput)({
+          removed: g.name ?? g.id
+        }, output);
+        return true;
+      }
+    case 'reset':
+      current.logGroups = null;
+      await save(current);
+      (0, _serverOutput.printOutput)({
+        reset: 'the default log groups apply'
+      }, output);
+      return true;
+    case 'put':
+      {
+        const replaced = readBody(argv);
+        if (!Array.isArray(replaced)) throw new Error('groups put takes a JSON array of log groups');
+        current.logGroups = replaced.map(g => ({
+          id: (0, _crypto.randomUUID)(),
+          ...g
+        }));
+        await save(current);
+        (0, _serverOutput.printOutput)({
+          groups: current.logGroups.length
+        }, output);
+        return true;
+      }
+  }
+  throw new Error('Usage: grok s observe groups list | get <name|id> | add --name <n> ... | set <name|id> ... | rm <name|id> | put --json <file> | reset');
+}
+
+/// The log filter text of `logs match`: the expression given, and a condition per flag, joined by `and`.
+function matchFilter(rest, argv) {
+  const parts = rest.length ? [rest.join(' ')] : [];
+  const word = v => /^[^\s=<>~!(),"']+$/.test(v) && !/^(and|or|not)$/i.test(v) ? v : `"${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  const values = (flag, split) => {
+    const given = argv[flag] === true ? [] : split ? String(argv[flag]).split(',').map(x => x.trim()).filter(Boolean) : [String(argv[flag])].filter(Boolean);
+    if (!given.length) throw new Error(`--${flag} needs a value`);
+    return given;
+  };
+  for (const field of ['level', 'type', 'user', 'package', 'source', 'function', 'session']) {
+    if (argv[field] === undefined) continue;
+    const given = values(field, true);
+    parts.push(given.length > 1 ? `${field} in (${given.map(word).join(', ')})` : `${field} = ${word(given[0])}`);
+  }
+  if (argv.grep !== undefined) parts.push(`text =~ ${word(values('grep', false)[0])}`);
+  // = is case-sensitive and startsWith is not, so one anchored regex keeps the space and its subspaces alike.
+  if (argv.space !== undefined) {
+    const space = values('space', false)[0].replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    parts.push(`space =~ ${word(`^${space}(:|$)`)}`);
+  }
+  return parts.length > 1 ? parts.map(p => `(${p})`).join(' and ') : parts[0] ?? '';
+}
 async function logs(dapi, verb, rest, argv, output) {
   const connection = argv.connection;
   if (verb === 'cloud') {
@@ -353,6 +629,28 @@ async function logs(dapi, verb, rest, argv, output) {
     return true;
   }
   if (verb === 'container') return containerLogs(dapi, rest[0], argv, output);
+  if (verb === 'match') {
+    const filter = matchFilter(rest, argv);
+    const since = `${Math.round(parseDuration(argv.since ?? '1h', '--since') / 1000)}s`;
+    (0, _serverOutput.printOutput)(await dapi.raw('GET', `/log/match${(0, _nodeDapi.buildQuery)({
+      filter,
+      since,
+      limit: argv.limit,
+      format: 'json'
+    })}`), output);
+    return true;
+  }
+  if (verb === 'request' && rest[0] !== undefined) {
+    const rows = await readRequestLog(dapi, String(rest[0]));
+    (0, _serverOutput.printOutput)(output === 'table' ? rows.map(r => ({
+      time: r.time,
+      level: r.level,
+      flag: r.flag ?? '',
+      source: r.source ?? '',
+      message: r.message
+    })) : rows, output);
+    return true;
+  }
   if (verb === 'archive' && rest[0] === 'list') {
     let objects = (await dapi.raw('GET', `/log/archive/objects${(0, _nodeDapi.buildQuery)({
       connection,
@@ -375,7 +673,37 @@ async function logs(dapi, verb, rest, argv, output) {
     })}`), output);
     return true;
   }
-  throw new Error('Usage: grok s observe logs cloud [--group <g>] ... | logs container [<name|id>] | ' + 'logs archive list [--prefix <p>] | logs archive read <key> | logs capture [<login|group>] | ' + 'logs capture stop <login|group>');
+  throw new Error('Usage: grok s observe logs cloud [--group <g>] ... | logs container [<name|id>] | ' + 'logs match [<filter>] | logs archive list [--prefix <p>] | logs archive read <key> | logs request <logId> | logs capture [<login|group>] | ' + 'logs capture stop <login|group>');
+}
+
+/// `GET /log/requests/<logId>`: what every isolate of every instance kept in memory for the id, as JSON lines,
+/// oldest first. Gathering hands the records over, so a second read returns none.
+async function readRequestLog(dapi, logId) {
+  return (await dapi.raw('GET', `/log/requests/${encodeURIComponent(logId)}`)) ?? [];
+}
+
+/** After a command run with `--log`: its log on stderr, so stdout keeps the result; JSON lines under `--output json`. */
+async function printRequestLog(dapi, logId, output) {
+  let rows;
+  try {
+    rows = await readRequestLog(dapi, logId);
+  } catch (e) {
+    process.stderr.write(`--log: could not read the log of ${logId}: ${e?.message ?? e}\n`);
+    return;
+  }
+  if (output === 'json') {
+    for (const r of rows) process.stderr.write(JSON.stringify({
+      logId,
+      ...r
+    }) + '\n');
+    return;
+  }
+  process.stderr.write(`── log ${logId}: ${rows.length} record${rows.length === 1 ? '' : 's'} (grok s o logs request ${logId})\n`);
+  for (const r of rows) {
+    const tags = [r.flag, r.source].filter(Boolean).join(' ');
+    process.stderr.write(`${String(r.time ?? '').substring(11, 23)} ${String(r.level ?? '').toUpperCase().padEnd(7)} ` + `${tags ? `[${tags}] ` : ''}${r.message ?? ''}\n`);
+    if (r.stackTrace) process.stderr.write(String(r.stackTrace).replace(/^/gm, '    ') + '\n');
+  }
 }
 
 /// `logs container`: the server only cuts a container's log by line count, so the window and --grep apply here.

package/bin/commands/server.js

@@ -10,6 +10,7 @@ exports.resolveManifestSources = resolveManifestSources;
 exports.server = server;
 var fs = _interopRequireWildcard(require("fs"));
 var path = _interopRequireWildcard(require("path"));
+var _crypto = require("crypto");
 var _nodeDapi = require("../utils/node-dapi");
 var _serverClient = require("../utils/server-client");
 var _serverOutput = require("../utils/server-output");
@@ -28,7 +29,7 @@ const ENTITY_TYPES = {
   reports: 'UserReport'
 };
 const ENTITIES = ['users', 'groups', 'functions', 'connections', 'queries', 'scripts', 'packages', 'reports', 'files', 'tables'];
-const COMMANDS = ['shares', 'domains', 'raw', 'batch', 'describe', 'healthcheck', 'sync', 'pull', 'push', 'migrate', 'diff', 'bundle', 'token', 'observe', 'o'];
+const COMMANDS = ['shares', 'domains', 'raw', 'batch', 'describe', 'healthcheck', 'status', 'sync', 'pull', 'push', 'migrate', 'diff', 'bundle', 'token', 'observe', 'o'];
 const VERBS = ['list', 'count', 'get', 'delete'];
 async function server(argv) {
   const args = argv['_'].slice(1);
@@ -51,8 +52,13 @@ async function server(argv) {
     return true;
   }
   let client;
+  const logSpec = (0, _serverClient.logSpecOf)(argv);
+  const logId = logSpec || entity === 'functions' && verb === 'run' && isDebug(argv) ? (0, _crypto.randomUUID)() : undefined;
   try {
-    client = await (0, _serverClient.createClient)(host, !!argv.admin);
+    client = await (0, _serverClient.createClient)(host, !!argv.admin, logId ? {
+      logId,
+      spec: logSpec
+    } : undefined);
   } catch (err) {
     // a bad alias, URL or key is not a usage error: no help dump, just the reason
     (0, _serverOutput.printError)(err);
@@ -76,6 +82,7 @@ async function server(argv) {
     if (entity === 'raw') return await handleRaw(dapi, verb, rest, argv, output);
     if (entity === 'describe') return await handleDescribe(dapi, verb ?? rest[0], output);
     if (entity === 'healthcheck') return await handleHealthcheck(dapi, argv, output);
+    if (entity === 'status') return await handleStatus(dapi, output);
     if (entity === 'sync') return await handleSync(dapi, verb, rest, argv, output);
     if (entity === 'functions' && verb === 'run') return await handleFuncRun(dapi, rest, argv, output);
     if (entity === 'functions' && verb === 'list') return await handleFunctionsList(dapi, argv, limit, offset, filter, output);
@@ -184,8 +191,15 @@ async function server(argv) {
     });
     process.exitCode = 1;
     return true;
+  } finally {
+    if (logId) await (0, _serverObserve.printRequestLog)(dapi, logId, output);
   }
 }
+
+/** `--debug` is not a declared boolean (grok publish reads it too), so it can arrive as a string. */
+function isDebug(argv) {
+  return argv.debug !== undefined && argv.debug !== false && argv.debug !== 'false';
+}
 async function handleFilesPut(dapi, rest, output) {
   const [localPath, remotePath] = rest;
   if (!localPath || !remotePath) {
@@ -598,6 +612,39 @@ async function handleHealthcheck(dapi, argv, output) {
   if (services.length) (0, _serverOutput.printOutput)(services, output);else if (module) throw new Error(`Module '${module}' is not reported by the server`);else if (output !== 'quiet') console.log('(no services reported)');
   return true;
 }
+async function handleStatus(dapi, output) {
+  const [info, extended] = await Promise.all([dapi.serverStatus(), dapi.serverStatus(true)]);
+  if (output === 'json') {
+    (0, _serverOutput.printOutput)({
+      server: info,
+      extended
+    }, output);
+    return true;
+  }
+  if (output === 'quiet') {
+    console.log(info?.Version ?? '');
+    return true;
+  }
+  const http = info?.['Http Server'];
+  const fields = {
+    ...info,
+    'Http Server': undefined
+  };
+  const width = Math.max(...Object.keys(fields).map(k => k.length)) + 2;
+  for (const [k, v] of Object.entries(fields)) if (v !== undefined) console.log(`${(k + ':').padEnd(width)}${v ?? ''}`);
+  if (http) console.log(`${'Http Server:'.padEnd(width)}total ${http.total}, active ${http.active}, idle ${http.idle}, closing ${http.closing}`);
+  // Non-admins get the plain count back; admins get {"METHOD url": inFlight}.
+  const active = extended?.['Http Server']?.active;
+  if (active && typeof active === 'object') {
+    console.log('');
+    const rows = Object.entries(active).map(([request, count]) => ({
+      request,
+      count
+    }));
+    if (rows.length) (0, _serverOutput.printOutput)(rows, output);else console.log('(no requests in flight)');
+  }
+  return true;
+}
 async function handleDescribe(dapi, entityType, output) {
   if (!entityType) {
     (0, _serverOutput.printError)(new Error('Usage: grok s describe <entity|type>   e.g. grok s describe connections, grok s describe Project'));
@@ -617,9 +664,11 @@ async function handleDescribe(dapi, entityType, output) {
   return true;
 }
 async function handleFuncRun(dapi, rest, argv, output) {
-  let funcName = rest[0];
+  // `--debug 'Pkg:f()'` hands the call to --debug.
+  let funcName = rest[0] ?? (typeof argv.debug === 'string' ? argv.debug : undefined);
+  const debug = isDebug(argv);
   if (!funcName) {
-    (0, _serverOutput.printError)(new Error('Usage: grok s functions run <Name:function(args...)> [--json params.json]'));
+    (0, _serverOutput.printError)(new Error('Usage: grok s functions run <Name:function(args...)> [--json params.json] [--debug]'));
     return false;
   }
   let params = {};
@@ -637,7 +686,7 @@ async function handleFuncRun(dapi, rest, argv, output) {
     params = parsed.params;
     if (Object.keys(params).some(k => /^\d+$/.test(k))) params = (0, _nodeDapi.mapPositionalParams)(params, (await dapi.functions.find(funcName))?.parameterInfos, funcName);
   }
-  const result = await dapi.functions.run(funcName, params);
+  const result = await dapi.functions.run(funcName, params, debug);
   (0, _serverOutput.printOutput)(result, output);
   return true;
 }
@@ -953,6 +1002,8 @@ Special commands:
   grok s raw <METHOD> <path> [--json f | --data j]    Any API endpoint; path is API-relative (/users/current), /api prefix optional
   grok s describe <entity|type>                       Fields of an entity type (registry record + a live sample)
   grok s healthcheck [--module <name>]                Check server + per-module health
+  grok s status                                       Server build, uptime, DB pool and HTTP connections
+                                                      (/info/server); admins also see requests in flight
   grok s shares add <entity> <group>[,<group>...] [--access View|Edit]
                                                       Share an entity with one or more groups
   grok s shares list <entity-id-or-name>              List who an entity is shared with
@@ -1057,6 +1108,13 @@ Options:
   --offset <n>          Start offset (default: 0)
   -r, --recursive       Recursive (for files list)
   --verbose             Print the stack of a runtime failure, not just its message
+  --log [<spec>]        Keep what this command's requests log at <spec>, then collect it from
+                        every server instance and print it to stderr: verbose (default),
+                        standard, levels (error, warning, info, debug, audit, usage) and debug
+                        flags (db, storage, credentials, ..., or all), comma-separated. Only
+                        these requests are affected; no permission is needed
+  --debug               functions run: a debug call, as the query debugger runs it; its log (the
+                        query's stages) prints the same way
   --json <file>         Read a JSON body from a file (save, functions run, batch, raw)
   --data '<json>'       Inline JSON body for raw
   -O, --output-file     Write table download to a file instead of stdout
@@ -1087,6 +1145,8 @@ Examples:
   grok s connections test --json conn.json
   grok s functions run 'Chem:smilesToMw("ccc")'
   grok s functions run Chem:test --json params.json
+  grok s functions run 'MyPkg:MyQuery()' --debug                   # the query's own log
+  grok s functions run UsageAnalysis:Groups --log verbose,db       # and every SQL statement it ran
   grok s functions list --type script --language python --limit 20
   grok s functions list --package Chem --type query
   grok s functions list --package PowerPack --type package --filter 'name contains "grid"'