peekinside 1.2.3 → 1.2.5

package/README.md

@@ -5,6 +5,7 @@ Debug Node.js from the inside: every error with the request that set it off, the
 [![npm](https://img.shields.io/npm/v/peekinside?color=18b69b)](https://www.npmjs.com/package/peekinside)
 ![License](https://img.shields.io/badge/license-MIT-18b69b)
 ![Node](https://img.shields.io/badge/node-%3E%3D18-18b69b)
+[![Buy me a coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-FFDD00?logo=buymeacoffee&logoColor=000000)](https://buymeacoffee.com/thejesbin)
 
 ## Install
 
@@ -38,9 +39,16 @@ Everything else is in the docs: **[peekinside.dev/docs](https://peekinside.dev/d
 - [Logs](https://peekinside.dev/docs/logs)
 - [Jobs and schedules](https://peekinside.dev/docs/jobs)
 - [Runtime](https://peekinside.dev/docs/runtime)
+- [Alerts](https://peekinside.dev/docs/alerts)
 - [Configuration](https://peekinside.dev/docs/configuration)
 - [API](https://peekinside.dev/docs/api)
 
+## Support
+
+If PeekInside saves you a debugging session, you can buy me a coffee:
+
+[![Buy me a coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=&slug=thejesbin&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://buymeacoffee.com/thejesbin)
+
 ## License
 
 MIT

package/index.d.ts

@@ -208,6 +208,8 @@ export interface PeekInsideUser {
   id?: string | number;
   email?: string;
   name?: string;
+  /** As your app writes it, such as "+91 98765 43210". */
+  phone?: string | number;
 }
 
 /** Options that can still change after the instance is created (see `attachTo`). */
@@ -315,7 +317,7 @@ declare class PeekInside {
    *
    * @example
    * app.use((req, res, next) => {
-   *   if (req.user) PeekInside.setUser({ id: req.user.id, email: req.user.email });
+   *   if (req.user) PeekInside.setUser({ id: req.user.id, email: req.user.email, name: req.user.name, phone: req.user.phone });
    *   next();
    * });
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peekinside",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Debug Node.js from the inside: errors with the requests, queries, logs and jobs behind them. A free local dashboard, and encrypted monitoring for production",
   "main": "index.js",
   "types": "./index.d.ts",

package/src/PeekInside.js

@@ -42,6 +42,7 @@ import { JobRunner } from './jobs/job-runner.js';
 import { LogCapture } from './logs/log-capture.js';
 import { LoopMonitor } from './runtime/loop-monitor.js';
 import { RuntimeSampler } from './runtime/sampler.js';
+import { RequestCounter } from './runtime/request-counter.js';
 import { UserInfo } from './user.js';
 import { CloudTransport } from './transport/cloud.js';
 import { LocalTransport } from './transport/local.js';
@@ -159,6 +160,8 @@ class PeekInside {
     // Whether this instance uses the event-loop monitor, and its process sampler.
     this._loopMonitor = false;
     this._sampler = null;
+    // The requests this instance serves, counted for its process samples.
+    this._requests = null;
     // Log lines for the Logs page, and job runs.
     this._logs = null;
     this._jobs = null;
@@ -218,9 +221,11 @@ class PeekInside {
       }
       if (this.options.runtime !== false) {
         const transport = this._transport;
+        this._requests = new RequestCounter();
         this._sampler = new RuntimeSampler({
           intervalMs: this._cloud ? 60_000 : 10_000,
           monitor: LoopMonitor.shared,
+          requests: this._requests,
           onSample: (sample) => transport.addSample(sample)
         }).start();
       }
@@ -427,13 +432,14 @@ class PeekInside {
    * customer ran into. In PeekInside Cloud the user is encrypted with the rest of the request.
    * Call it once the user is known, such as in your authentication middleware.
    *
-   * @param {{ id?: string|number, email?: string, name?: string }|string|number|null} user - The
-   *   user, or just their id; null forgets it
+   * @param {{ id?: string|number, email?: string, name?: string, phone?: string|number }|string|number|null} user -
+   *   The user, or just their id; null forgets it. The phone is kept as written (phoneNumber,
+   *   phone_number and mobile work too).
    * @returns {boolean} Whether a request was running to attach it to
    *
    * @example
    * app.use((req, res, next) => {
-   *   if (req.user) PeekInside.setUser({ id: req.user.id, email: req.user.email });
+   *   if (req.user) PeekInside.setUser({ id: req.user.id, email: req.user.email, name: req.user.name, phone: req.user.phone });
    *   next();
    * });
    */
@@ -683,6 +689,7 @@ class PeekInside {
 
   _track(req, res, target, integration) {
     let context = null;
+    const requests = this._requests;
     const recorder = new ExchangeRecorder(req, res, target, {
       maxBodySize: () => this.options.maxBodySize,
       onExchange: (exchange) => {
@@ -698,6 +705,19 @@ class PeekInside {
     });
     context = new RequestContext({ capture: this._exceptions, req, recorder, target, integration });
     recorder.start();
+    if (requests) {
+      // Counted off the response itself, so a request ends once whatever happens to its record.
+      requests.started();
+      let open = true;
+      const end = () => {
+        if (open) {
+          open = false;
+          requests.ended();
+        }
+      };
+      res.once('finish', end);
+      res.once('close', end);
+    }
     if (this._timeline) {
       context.timeline = new Timeline(this._timeline, recorder.perfStart);
     }

package/src/alerts/rule-matcher.js

@@ -0,0 +1,158 @@
+/**
+ * The parts of a project's alert rules that only the app's server can check: conditions on a
+ * request's path, user and response, and on an exception's or a log line's message, which reach
+ * PeekInside Cloud sealed. The matcher fetches them now and then, checks each record before it is
+ * sealed, and the transport sends which records met which rule with the batch: never what they
+ * hold. Everything else about a rule (a status, a duration, an environment) is checked by
+ * PeekInside Cloud itself.
+ */
+
+import { RequestContext } from '../exceptions/request-context.js';
+
+// Fetched again this often, the first time this long after the transport first delivered.
+const REFRESH_MS = 60_000;
+const FIRST_FETCH_MS = 1000;
+// The most of a response body checked for a "contains" condition.
+const MAX_BODY = 64 * 1024;
+const RULE_ID = /^rl[0-9a-z]{12}$/;
+
+/**
+ * @typedef {Object} SealedRule
+ * @property {string} id - The rule's id
+ * @property {'requests'|'exceptions'|'logs'} source
+ * @property {{ field: string, op: 'is'|'is-not'|'contains'|'matches', value: string }[]} conditions
+ */
+
+export class RuleMatcher {
+  /**
+   * @param {Object} options
+   * @param {() => Promise<{ rules: SealedRule[] }>} options.fetchRules - Asks PeekInside Cloud for them
+   * @param {number} [options.refreshMs]
+   */
+  constructor({ fetchRules, refreshMs = REFRESH_MS }) {
+    this.fetchRules = fetchRules;
+    this.refreshMs = refreshMs;
+    /** @type {SealedRule[]} */
+    this.rules = [];
+    this.timer = null;
+    this.first = null;
+  }
+
+  /**
+   * Fetches the rules shortly, then keeps them current. Its timers never keep the process alive:
+   * a script that ends right away never waits for them.
+   *
+   * @returns {void}
+   */
+  start() {
+    if (this.timer || this.first) return;
+    this.first = RequestContext.outside(() =>
+      setTimeout(() => {
+        void this.refresh();
+        this.timer = RequestContext.outside(() => setInterval(() => void this.refresh(), this.refreshMs));
+        if (typeof this.timer.unref === 'function') this.timer.unref();
+      }, FIRST_FETCH_MS)
+    );
+    if (typeof this.first.unref === 'function') this.first.unref();
+  }
+
+  stop() {
+    clearTimeout(this.first);
+    clearInterval(this.timer);
+    this.first = null;
+    this.timer = null;
+  }
+
+  /**
+   * @returns {Promise<void>} Never rejects: without rules, nothing is reported
+   */
+  async refresh() {
+    try {
+      const answer = await RequestContext.outside(() => this.fetchRules());
+      this.rules = Array.isArray(answer && answer.rules) ? answer.rules.filter(valid) : [];
+    } catch (error) {
+      // Kept as they were: PeekInside Cloud may be briefly unreachable.
+    }
+  }
+
+  /**
+   * The rules a record meets on its sealed fields.
+   *
+   * @param {Object} record - A RequestRecord, ExceptionRecord or LogRecord, before it is sealed
+   * @returns {{ rule: string, id: string }[]}
+   */
+  matches(record) {
+    if (!this.rules.length || !record || typeof record.id !== 'string') return [];
+    const source = sourceOf(record);
+    if (!source) return [];
+    const found = [];
+    for (const rule of this.rules) {
+      if (rule.source !== source) continue;
+      if (rule.conditions.every((condition) => meets(condition, valuesOf(record, condition.field)))) found.push({ rule: rule.id, id: record.id });
+    }
+    return found;
+  }
+}
+
+function valid(rule) {
+  return (
+    rule &&
+    RULE_ID.test(rule.id) &&
+    ['requests', 'exceptions', 'logs'].includes(rule.source) &&
+    Array.isArray(rule.conditions) &&
+    rule.conditions.length > 0 &&
+    rule.conditions.every((condition) => condition && typeof condition.field === 'string' && typeof condition.value === 'string')
+  );
+}
+
+function sourceOf(record) {
+  const name = record.constructor && record.constructor.name;
+  if (name === 'RequestRecord') return 'requests';
+  if (name === 'ExceptionRecord') return 'exceptions';
+  if (name === 'LogRecord') return 'logs';
+  return null;
+}
+
+// The values a condition looks at (a user has several: its id, email and phone).
+function valuesOf(record, field) {
+  const summary = record.summary || {};
+  switch (field) {
+    case 'path':
+      return [summary.path];
+    case 'user': {
+      const user = summary.user || {};
+      return [user.id, user.email, user.phone].filter((value) => value !== undefined && value !== null).map(String);
+    }
+    case 'response': {
+      const body = record.detail && record.detail.response ? record.detail.response.body : null;
+      const text = typeof body === 'string' ? body : body && typeof body.text === 'string' ? body.text : '';
+      return [text.slice(0, MAX_BODY)];
+    }
+    case 'name':
+      return [summary.name];
+    case 'message':
+      return [summary.message];
+    default:
+      return [];
+  }
+}
+
+// Text compares without case; "matches" takes * as anything. A condition is met by any of the values.
+function meets(condition, values) {
+  const wanted = String(condition.value).toLowerCase();
+  const pattern = condition.op === 'matches' ? new RegExp(`^${wanted.split('*').map(escape).join('.*')}$`) : null;
+  const met = values.some((value) => {
+    if (typeof value !== 'string') return false;
+    const text = value.toLowerCase();
+    if (condition.op === 'is') return text === wanted;
+    if (condition.op === 'is-not') return text !== wanted;
+    if (condition.op === 'contains') return text.includes(wanted);
+    if (condition.op === 'matches') return pattern.test(text);
+    return false;
+  });
+  return condition.op === 'is-not' ? values.length === 0 || met : met;
+}
+
+function escape(text) {
+  return text.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/crypto.js

@@ -177,13 +177,37 @@ export class ApiKey {
   }
 
   /**
-   * @param {string} apiKey
+   * @param {string} apiKey - Surrounding spaces and quotes are ignored (env files that keep them)
    * @returns {ApiKey|null} The key's parts, or null when it isn't a well-formed v1 key
    */
   static parse(apiKey) {
-    const [version, projectId, secret, publicKey, ...rest] = String(apiKey).trim().split('.');
+    const [version, projectId, secret, publicKey, ...rest] = ApiKey.unquote(apiKey).split('.');
     if (version !== 'pik1' || rest.length) return null;
     if (!PROJECT_ID.test(projectId) || !SECRET.test(secret) || !PUBLIC_KEY.test(publicKey)) return null;
     return new ApiKey({ projectId, secret, publicKey });
   }
+
+  /**
+   * What's wrong with a value that isn't an API key, in words for the app's log. Never repeats the
+   * value: it may hold a secret.
+   *
+   * @param {string} value
+   * @returns {string} A sentence without its final period
+   */
+  static problem(value) {
+    const text = ApiKey.unquote(value);
+    if (PUBLIC_KEY.test(text) && Buffer.from(text, 'base64url')[0] === 4) {
+      return 'PEEKINSIDE_API_KEY holds your project\'s public key, not an API key. API keys start with "pik1.": create one in PeekInside Cloud, on the project\'s Settings page under API keys';
+    }
+    if (!text.startsWith('pik1.')) {
+      return 'PEEKINSIDE_API_KEY is not a PeekInside API key (those start with "pik1."). Create one in PeekInside Cloud, on the project\'s Settings page under API keys';
+    }
+    return 'PEEKINSIDE_API_KEY looks cut off or changed: copy the whole key, from "pik1." to its end';
+  }
+
+  // Without the spaces and one pair of matching quotes around it.
+  static unquote(value) {
+    const text = String(value).trim();
+    return /^(["'`]).*\1$/s.test(text) && text.length > 1 ? text.slice(1, -1).trim() : text;
+  }
 }

package/src/exceptions/exception-record.js

@@ -62,7 +62,9 @@ export class ExceptionRecord {
 
   /**
    * The sealed form, for PeekInside Cloud: the summary and the detail are encrypted, bound to this
-   * exception's id so they can't be swapped with another record's.
+   * exception's id so they can't be swapped with another record's. The fingerprint (a hash of the
+   * error's name and where it was thrown, see fingerprint.js) goes alongside: it tells Cloud a new
+   * error from a known one, for alerts, without saying what either is.
    *
    * @param {import('../crypto.js').Sealer} sealer - Sealer of the batch
    * @returns {Promise<Object>}
@@ -71,6 +73,7 @@ export class ExceptionRecord {
     const { summary, detail, ...meta } = this.toJSON();
     return {
       ...meta,
+      ...this._fingerprint(),
       summary: await sealer.seal(JSON.stringify(summary), ExceptionRecord.summaryAad(this.id)),
       detail: await sealer.seal(JSON.stringify(detail), ExceptionRecord.detailAad(this.id))
     };
@@ -86,11 +89,18 @@ export class ExceptionRecord {
     const { summary, detail, ...meta } = this.toJSON();
     return {
       ...meta,
+      ...this._fingerprint(),
       summary: sealer.seal(JSON.stringify(summary), ExceptionRecord.summaryAad(this.id)),
       detail: sealer.seal(JSON.stringify(detail), ExceptionRecord.detailAad(this.id))
     };
   }
 
+  // The fingerprint field of the sealed form; none when there isn't a valid one.
+  _fingerprint() {
+    const fingerprint = this.summary?.fingerprint;
+    return typeof fingerprint === 'string' && /^[0-9a-f]{16}$/.test(fingerprint) ? { fingerprint } : {};
+  }
+
   /**
    * How the record of the request it happened in lists it, so the request inspector can link to it.
    *

package/src/hub/ingest-payload.js

@@ -40,6 +40,18 @@ const RELEASE = /^[A-Za-z0-9._:@/+-]{1,64}$/;
 const MAX_SAMPLES = 120;
 const SAMPLE_BYTES = ['rss', 'heapUsed', 'heapTotal', 'external'];
 const SAMPLE_DELAYS = ['loopP50', 'loopP99', 'loopMax'];
+// Later additions, each optional (older SDKs don't send them): the field, and its largest value.
+const SAMPLE_EXTRAS = [
+  ['arrayBuffers', 1e13],
+  ['heapLimit', 1e13],
+  ['elu', 100],
+  ['gcCount', 1e7],
+  ['gcMs', 1e7],
+  ['gcMax', 1e7],
+  ['handles', 1e7],
+  ['requests', 1e9],
+  ['inFlight', 1e7]
+];
 
 /**
  * A validated ingest batch: `{ project, instance, requests, exceptions, samples, blocked }`.
@@ -307,6 +319,10 @@ function readSamples(value) {
       const number = sample[key];
       clean[key] = Number.isFinite(number) && number >= 0 && number <= 1e7 ? number : null;
     }
+    for (const [key, max] of SAMPLE_EXTRAS) {
+      const number = sample[key];
+      clean[key] = Number.isFinite(number) && number >= 0 && number <= max ? number : null;
+    }
     return [clean];
   });
 }
@@ -324,8 +340,13 @@ function readLocation(value) {
 // Who a request or exception was for: short strings only, null when it names nobody.
 function readUser(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
-  const user = { id: text(value.id, 128) || null, email: text(value.email, 254) || null, name: text(value.name, 128) || null };
-  return user.id || user.email || user.name ? user : null;
+  const user = {
+    id: text(value.id, 128) || null,
+    email: text(value.email, 254) || null,
+    name: text(value.name, 128) || null,
+    phone: text(value.phone, 32) || null
+  };
+  return user.id || user.email || user.name || user.phone ? user : null;
 }
 
 function readRequestLine(value) {

package/src/hub/server.js

@@ -1,8 +1,8 @@
 /**
  * The local hub's HTTP server, on 127.0.0.1 only.
  *
- *   GET    /                                   Dashboard page (also /p/<project id>,
- *                                              /p/<project id>/exceptions and /p/<project id>/queries)
+ *   GET    /                                   Dashboard page (also /p/<project id>, and its
+ *                                              /exceptions, /routes, /queries, /logs, /jobs and /runtime)
  *   POST   /api/ingest                         Requests and exceptions from the SDK in each app, and
  *                                              counts of server requests it didn't record (free plan)
  *   GET    /api/status                         Hub version and settings
@@ -48,7 +48,7 @@ const MAX_PAGE = 1000;
 // /api/projects/:id, then optionally a collection and an item.
 const PROJECT_ROUTE = /^\/api\/projects\/([^/]+)(?:\/(requests|exceptions|exception-state|runtime|jobs|logs)(?:\/([^/]+))?)?$/;
 // The dashboard page: the project list, a project's requests, its exceptions and its queries.
-const SHELL_ROUTE = /^\/p\/[a-z0-9-]{1,64}(?:\/(?:exceptions|queries|runtime|logs|jobs))?\/?$/;
+const SHELL_ROUTE = /^\/p\/[a-z0-9-]{1,64}(?:\/(?:exceptions|routes|queries|runtime|logs|jobs))?\/?$/;
 
 const BASE_HEADERS = {
   'X-Content-Type-Options': 'nosniff',

package/src/instrumentation/jobs.js

@@ -4,6 +4,9 @@
  * (queue workers, with the queue, the attempt and the job's data, and the schedule of repeatable
  * jobs). Each run goes through JobRunner, exactly as PeekInside.job() would run it.
  *
+ * A schedule is recorded with its time zone: the one given to the library, else the process's
+ * own, which is the one these libraries read a cron expression in without one.
+ *
  * Libraries that ship separate CommonJS and ES module builds (node-cron, BullMQ) are patched in
  * both: the CommonJS one right away, the ES module one as soon as it is imported here, which is
  * before any job can run.
@@ -91,7 +94,8 @@ export class JobInstrumentation {
     proto.callProcessJob = function (job) {
       const args = arguments;
       const repeat = job && job.opts && job.opts.repeat;
-      const schedule = repeat ? repeat.pattern || repeat.cron || (Number.isFinite(repeat.every) ? `@every ${repeat.every}ms` : undefined) : undefined;
+      const pattern = repeat ? repeat.pattern || repeat.cron : undefined;
+      const schedule = repeat ? pattern || (Number.isFinite(repeat.every) ? `@every ${repeat.every}ms` : undefined) : undefined;
       return JobRunner.run(
         job && job.name && job.name !== '__default__' ? job.name : this.name,
         () => original.apply(this, args),
@@ -100,7 +104,7 @@ export class JobInstrumentation {
           attempt: job && Number.isInteger(job.attemptsMade) ? job.attemptsMade + 1 : 1,
           data: job ? job.data : undefined,
           schedule,
-          timezone: repeat && typeof repeat.tz === 'string' ? repeat.tz : undefined,
+          timezone: repeat && typeof repeat.tz === 'string' && repeat.tz ? repeat.tz : pattern ? localTimeZone() : undefined,
           trigger: schedule ? 'cron' : 'queue'
         }
       );
@@ -146,7 +150,11 @@ function wrapCronTask(task) {
   const name = task.name && task.name !== task.id ? task.name : `cron ${expression || 'task'}`;
   const wrapped = function () {
     const args = arguments;
-    return JobRunner.run(name, () => original.apply(this, args), { schedule: expression || undefined, timezone: task.timezone, trigger: 'cron' });
+    return JobRunner.run(name, () => original.apply(this, args), {
+      schedule: expression || undefined,
+      timezone: (typeof task.timezone === 'string' && task.timezone) || localTimeZone(),
+      trigger: 'cron'
+    });
   };
   wrapped[kWrapped] = true;
   runner.onMatch = wrapped;
@@ -159,7 +167,7 @@ function wrapCronJobCallback(job, callback) {
     const args = arguments;
     return JobRunner.run(job.name || `cron ${source || 'job'}`, () => callback.apply(this, args), {
       schedule: source || undefined,
-      timezone: job.cronTime && typeof job.cronTime.timeZone === 'string' ? job.cronTime.timeZone : undefined,
+      timezone: (job.cronTime && typeof job.cronTime.timeZone === 'string' && job.cronTime.timeZone) || localTimeZone(),
       trigger: 'cron'
     });
   };
@@ -167,6 +175,15 @@ function wrapCronJobCallback(job, callback) {
   return wrapped;
 }
 
+// The process's time zone (TZ, else the system's).
+function localTimeZone() {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || undefined;
+  } catch (error) {
+    return undefined;
+  }
+}
+
 // The file an `import` of the package loads, when it differs from what require() loads.
 function esmEntry(packageDir) {
   try {

package/src/runtime/request-counter.js

@@ -0,0 +1,40 @@
+/**
+ * The requests an instance serves, for its process samples: how many are open, and how many
+ * finished since the last sample. Two numbers, no request data.
+ */
+export class RequestCounter {
+  constructor() {
+    this.open = 0;
+    this.finished = 0;
+  }
+
+  /**
+   * A request started.
+   *
+   * @returns {void}
+   */
+  started() {
+    this.open++;
+  }
+
+  /**
+   * A request finished (or its connection closed first).
+   *
+   * @returns {void}
+   */
+  ended() {
+    this.open = Math.max(0, this.open - 1);
+    this.finished++;
+  }
+
+  /**
+   * The requests finished since the last call, and the ones open now.
+   *
+   * @returns {{ finished: number, open: number }}
+   */
+  take() {
+    const finished = this.finished;
+    this.finished = 0;
+    return { finished, open: this.open };
+  }
+}

package/src/runtime/sampler.js

@@ -1,10 +1,12 @@
 /**
- * Samples the process now and then: memory (to spot leaks, as growth over hours), CPU and the
- * event-loop delay. Samples are numbers only, and go to the dashboard with the other records:
- * every 10 seconds to the local dashboard, every minute to PeekInside Cloud.
+ * Samples the process now and then: memory (to spot leaks, as growth over hours, and how close the
+ * heap is to its limit), CPU, the event loop (its delay, and how busy it was), garbage collection,
+ * open handles and the requests it served. Samples are numbers only, and go to the dashboard with
+ * the other records: every 10 seconds to the local dashboard, every minute to PeekInside Cloud.
  */
 
-import { performance } from 'perf_hooks';
+import { PerformanceObserver, performance } from 'perf_hooks';
+import v8 from 'v8';
 import { RequestContext } from '../exceptions/request-context.js';
 
 /**
@@ -18,8 +20,73 @@ import { RequestContext } from '../exceptions/request-context.js';
  * @property {number|null} loopP50 - Event-loop delay since the last sample, ms
  * @property {number|null} loopP99
  * @property {number|null} loopMax
+ * @property {number|null} arrayBuffers - Bytes of ArrayBuffers and Buffers (part of external)
+ * @property {number|null} heapLimit - Bytes the heap may grow to before the process runs out of memory
+ * @property {number|null} elu - Percent of the time since the last sample the event loop was busy
+ * @property {number|null} gcCount - Garbage collections since the last sample
+ * @property {number|null} gcMs - Time they paused the process, ms
+ * @property {number|null} gcMax - The longest of them, ms
+ * @property {number|null} handles - Open handles and requests (sockets, timers, files) now
+ * @property {number|null} requests - Requests this process finished since the last sample
+ * @property {number|null} inFlight - Requests open when the sample was taken
  */
 
+/**
+ * Garbage collections since the last look: how many, and how long they paused the process.
+ */
+class GcWatch {
+  constructor() {
+    this.observer = null;
+    this.reset();
+  }
+
+  /**
+   * @returns {void}
+   */
+  start() {
+    if (this.observer) return;
+    try {
+      this.observer = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          this.count++;
+          this.ms += entry.duration;
+          if (entry.duration > this.max) this.max = entry.duration;
+        }
+      });
+      // Outside any request: collections belong to the process, not to the request that started it.
+      RequestContext.outside(() => this.observer.observe({ entryTypes: ['gc'] }));
+    } catch (error) {
+      this.observer = null;
+    }
+  }
+
+  /**
+   * @returns {void}
+   */
+  stop() {
+    if (this.observer) this.observer.disconnect();
+    this.observer = null;
+  }
+
+  /**
+   * The collections since the last call, or null when they can't be watched.
+   *
+   * @returns {{ count: number, ms: number, max: number }|null}
+   */
+  take() {
+    if (!this.observer) return null;
+    const taken = { count: this.count, ms: round(this.ms), max: round(this.max) };
+    this.reset();
+    return taken;
+  }
+
+  reset() {
+    this.count = 0;
+    this.ms = 0;
+    this.max = 0;
+  }
+}
+
 /**
  * Takes a sample every `intervalMs` and hands it over.
  */
@@ -29,14 +96,18 @@ export class RuntimeSampler {
    * @param {number} options.intervalMs
    * @param {(sample: RuntimeSample) => void} options.onSample
    * @param {import('./loop-monitor.js').LoopMonitor} options.monitor - Measures the delay
+   * @param {import('./request-counter.js').RequestCounter} [options.requests] - Counts the requests served
    */
-  constructor({ intervalMs, onSample, monitor }) {
+  constructor({ intervalMs, onSample, monitor, requests = null }) {
     this.intervalMs = intervalMs;
     this.onSample = onSample;
     this.monitor = monitor;
+    this.requests = requests;
     this.timer = null;
+    this.gc = new GcWatch();
     this.lastAt = performance.now();
     this.lastCpu = process.cpuUsage();
+    this.lastElu = loopUtilization();
   }
 
   /**
@@ -46,6 +117,8 @@ export class RuntimeSampler {
     if (this.timer) return this;
     this.lastAt = performance.now();
     this.lastCpu = process.cpuUsage();
+    this.lastElu = loopUtilization();
+    this.gc.start();
     this.timer = RequestContext.outside(() => setInterval(() => this.take(), this.intervalMs));
     if (typeof this.timer.unref === 'function') this.timer.unref();
     return this;
@@ -57,6 +130,7 @@ export class RuntimeSampler {
   stop() {
     clearInterval(this.timer);
     this.timer = null;
+    this.gc.stop();
   }
 
   /**
@@ -70,9 +144,14 @@ export class RuntimeSampler {
       const elapsed = Math.max(1, now - this.lastAt);
       const cpu = process.cpuUsage(this.lastCpu);
       const delay = this.monitor ? this.monitor.delaySince(this.lastAt) : null;
+      const elu = loopUtilization();
+      const busy = elu && this.lastElu ? performance.eventLoopUtilization(elu, this.lastElu).utilization : null;
       this.lastAt = now;
       this.lastCpu = process.cpuUsage();
+      this.lastElu = elu;
       const memory = process.memoryUsage();
+      const gc = this.gc.take();
+      const traffic = this.requests ? this.requests.take() : null;
       const sample = {
         at: Date.now(),
         rss: memory.rss,
@@ -82,7 +161,16 @@ export class RuntimeSampler {
         cpu: Math.round(((cpu.user + cpu.system) / 1000 / elapsed) * 1000) / 10,
         loopP50: delay ? delay.p50 : null,
         loopP99: delay ? delay.p99 : null,
-        loopMax: delay ? delay.max : null
+        loopMax: delay ? delay.max : null,
+        arrayBuffers: Number.isFinite(memory.arrayBuffers) ? memory.arrayBuffers : null,
+        heapLimit: heapLimit(),
+        elu: Number.isFinite(busy) ? Math.round(busy * 1000) / 10 : null,
+        gcCount: gc ? gc.count : null,
+        gcMs: gc ? gc.ms : null,
+        gcMax: gc ? gc.max : null,
+        handles: openHandles(),
+        requests: traffic ? traffic.finished : null,
+        inFlight: traffic ? traffic.open : null
       };
       this.onSample(sample);
       return sample;
@@ -91,3 +179,29 @@ export class RuntimeSampler {
     }
   }
 }
+
+// How busy the loop has been since the process started (Node.js 14.10 and later).
+function loopUtilization() {
+  return typeof performance.eventLoopUtilization === 'function' ? performance.eventLoopUtilization() : null;
+}
+
+function heapLimit() {
+  try {
+    return v8.getHeapStatistics().heap_size_limit;
+  } catch (error) {
+    return null;
+  }
+}
+
+// Sockets, timers, files and other resources keeping the loop alive (Node.js 17 and later).
+function openHandles() {
+  try {
+    return typeof process.getActiveResourcesInfo === 'function' ? process.getActiveResourcesInfo().length : null;
+  } catch (error) {
+    return null;
+  }
+}
+
+function round(value) {
+  return Math.round(value * 10) / 10;
+}

package/src/transport/cloud.js

@@ -20,6 +20,7 @@ import { JobRunRecord } from '../jobs/job-run-record.js';
 import { LogRecord } from '../logs/log-record.js';
 import { RequestRecord } from '../record.js';
 import { Spool } from '../spool.js';
+import { RuleMatcher } from '../alerts/rule-matcher.js';
 import { BatchTransport } from './batch.js';
 
 const FLUSH_INTERVAL_MS = 1000;
@@ -56,7 +57,16 @@ process.stdin.on('data', (chunk) => { input += chunk; });
 process.stdin.on('end', () => {
   let job;
   try { job = JSON.parse(input); } catch (error) { process.exit(1); }
-  fetch(job.url, { method: 'POST', headers: job.headers, body: job.body, signal: AbortSignal.timeout(${CRASH_SEND_TIMEOUT_MS - 500}) })
+  const signal = AbortSignal.timeout(${CRASH_SEND_TIMEOUT_MS - 500});
+  const post = (url) => fetch(url, { method: 'POST', headers: job.headers, body: job.body, redirect: 'manual', signal });
+  post(job.url)
+    .then((response) => {
+      const location = response.headers.get('location');
+      if ((response.status !== 307 && response.status !== 308) || !location) return response;
+      const target = new URL(location, job.url);
+      const ok = job.follow.hosts.includes(target.hostname) && job.follow.protocols.includes(target.protocol) && target.pathname === job.follow.path && (target.port === '' || target.port === job.follow.port);
+      return ok ? post(target.href) : response;
+    })
     .then((response) => process.exit(response.ok ? ${SENT} : response.status === 400 || response.status === 413 ? ${REFUSED} : 2))
     .catch(() => process.exit(1));
 });
@@ -77,7 +87,7 @@ export class CloudTransport extends BatchTransport {
   constructor({ apiKey, environment, release = null, version }) {
     const key = ApiKey.parse(apiKey);
     if (!key) {
-      throw new Error('PEEKINSIDE_API_KEY is not a valid PeekInside API key');
+      throw new Error(ApiKey.problem(apiKey));
     }
     super({
       environment: RequestRecord.normalizeEnvironment(environment, 'production'),
@@ -112,6 +122,8 @@ export class CloudTransport extends BatchTransport {
 
     this._resendTimer = null;
     this._resending = null;
+    // Alert rules on sealed fields, checked here before records are sealed (started with the first batch).
+    this.rules = new RuleMatcher({ fetchRules: () => this._fetchRules() });
     // Set when records that didn't fit in the last POST wait for the next one.
     this._more = false;
     // Batches spooled by an earlier run that crashed.
@@ -128,6 +140,7 @@ export class CloudTransport extends BatchTransport {
     clearInterval(this.timer);
     clearTimeout(this._resendTimer);
     this._resendTimer = null;
+    this.rules.stop();
     super.stop();
   }
 
@@ -180,6 +193,7 @@ export class CloudTransport extends BatchTransport {
   // even a large one, or it would block the queue.
   async _pack(batch, sealer) {
     const lists = { events: [], exceptions: [], jobs: [], logs: [] };
+    const alerts = [];
     let size = 32;
     let count = 0;
     for (const record of batch) {
@@ -189,8 +203,10 @@ export class CloudTransport extends BatchTransport {
       size += length;
       count++;
       lists[listFor(record)].push(sealed);
+      // Which alert rules it met on what only this server can read: ids, never the content.
+      alerts.push(...this.rules.matches(record));
     }
-    return { ...lists, rest: batch.slice(count) };
+    return { ...lists, alerts, rest: batch.slice(count) };
   }
 
   // Records that didn't fit go back to the front of the queue, in order, and go out right away.
@@ -204,11 +220,12 @@ export class CloudTransport extends BatchTransport {
   async _deliver(batch) {
     // A fresh ephemeral key per batch: one key agreement, a new IV per message.
     const sealer = await Sealer.create(this.apiKey.publicKey, 'event');
-    const { events, exceptions, jobs, logs, rest } = await this._pack(batch, sealer);
+    const { events, exceptions, jobs, logs, alerts, rest } = await this._pack(batch, sealer);
     const body = { events };
     if (exceptions.length) body.exceptions = exceptions;
     if (jobs.length) body.jobs = jobs;
     if (logs.length) body.logs = logs;
+    if (alerts.length) body.alerts = alerts;
     const samples = this.takeSamples();
     if (samples.length) {
       body.instance = { ...this.instance, environment: this.environment, release: this.release };
@@ -225,6 +242,8 @@ export class CloudTransport extends BatchTransport {
     const sent = batch.length - rest.length;
 
     if (response.ok) {
+      // PeekInside Cloud answers: from now on, the alert rules it holds are checked here too.
+      this.rules.start();
       this._requeue(rest);
       return true;
     }
@@ -278,6 +297,15 @@ export class CloudTransport extends BatchTransport {
     console.error(line);
   }
 
+  // The project's alert rules on sealed fields, from beside the ingest endpoint.
+  async _fetchRules() {
+    if (this.exiting) throw new Error('exiting');
+    // Never after a redirect: the API key goes only where batches go (see _post).
+    const response = await fetch(`${this.endpoint}/alert-rules`, { headers: this._headers(), redirect: 'manual', signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return response.json();
+  }
+
   _headers() {
     return {
       'content-type': 'application/json',
@@ -287,13 +315,21 @@ export class CloudTransport extends BatchTransport {
     };
   }
 
-  _post(body) {
-    return fetch(this.endpoint, {
+  // Posts to the endpoint. A redirect to the site's twin (see redirectTarget) is followed here,
+  // with the API key, and remembered; fetch() would follow it but drop the key.
+  async _post(body) {
+    const post = (url) => fetch(url, {
       method: 'POST',
       headers: this._headers(),
       body,
+      redirect: 'manual',
       signal: AbortSignal.timeout(this.exiting ? EXIT_TIMEOUT_MS : REQUEST_TIMEOUT_MS)
     });
+    const response = await post(this.endpoint);
+    const moved = redirectTarget(response, this.endpoint);
+    if (!moved) return response;
+    this.endpoint = moved;
+    return post(moved);
   }
 
   // The newest queued records, sealed, within the crash budget; they leave the queue.
@@ -314,7 +350,7 @@ export class CloudTransport extends BatchTransport {
   // Posts from a child process and waits for it: the only way to send over the network
   // synchronously. The secret travels on stdin, never on the command line.
   _sendNow(body) {
-    const input = JSON.stringify({ url: this.endpoint, headers: this._headers(), body });
+    const input = JSON.stringify({ url: this.endpoint, headers: this._headers(), body, follow: followRule(this.endpoint) });
     const env = process.platform === 'win32' && process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {};
     const result = spawnSync(process.execPath, ['-e', SENDER], {
       input,
@@ -395,3 +431,39 @@ function listFor(record) {
   if (record instanceof LogRecord) return 'logs';
   return 'events';
 }
+
+/**
+ * Where a 307 or 308 answer from PeekInside Cloud moves its endpoint, when the API key may follow
+ * it there, or null. Hosting often sends a site's bare domain to its www name, or back (Vercel
+ * does by default), and fetch() drops the Authorization header on such a redirect, so it is
+ * followed by hand, and only to the same path on the same host or its www twin, never downgrading
+ * https. Anywhere else, the answer stands (and the batch is retried later).
+ *
+ * @param {Response} response
+ * @param {string} from - The URL that answered
+ * @returns {string|null}
+ */
+export function redirectTarget(response, from) {
+  if (response.status !== 307 && response.status !== 308) return null;
+  const location = response.headers.get('location');
+  if (!location) return null;
+  let target;
+  try {
+    target = new URL(location, from);
+  } catch (error) {
+    return null;
+  }
+  const rule = followRule(from);
+  const ok = rule.hosts.includes(target.hostname) && rule.protocols.includes(target.protocol) && target.pathname === rule.path && (target.port === '' || target.port === rule.port);
+  return ok ? target.href : null;
+}
+
+// What redirectTarget accepts, as data, so the crash sender's child process applies the same rule.
+function followRule(from) {
+  const url = new URL(from);
+  const host = url.hostname;
+  const named = host.includes('.') && !host.startsWith('[') && !/^[\d.]+$/.test(host) && host !== 'localhost' && !host.endsWith('.localhost');
+  const hosts = [host];
+  if (named) hosts.push(host.startsWith('www.') ? host.slice(4) : `www.${host}`);
+  return { hosts, protocols: url.protocol === 'http:' ? ['http:', 'https:'] : [url.protocol], path: url.pathname, port: url.port };
+}

package/src/user.js

@@ -9,12 +9,14 @@
 const MAX_ID = 128;
 const MAX_EMAIL = 254;
 const MAX_NAME = 128;
+const MAX_PHONE = 32;
 
 /**
  * @typedef {Object} User
  * @property {string|null} id
  * @property {string|null} email
  * @property {string|null} name
+ * @property {string|null} phone
  */
 
 /**
@@ -22,14 +24,15 @@ const MAX_NAME = 128;
  */
 export class UserInfo {
   /**
-   * Accepts `{ id, email, name }` (also `_id`, `userId` and `username`, as user objects of common
-   * libraries have them), or just an id. Anything else is no user.
+   * Accepts `{ id, email, name, phone }` (also `_id`, `userId`, `username`, `phoneNumber`,
+   * `phone_number` and `mobile`, as user objects of common libraries and apps have them), or just
+   * an id. Anything else is no user.
    *
    * @param {*} user
    * @returns {User|null} null when it names nobody
    *
    * @example
-   * UserInfo.normalize({ id: 42, email: 'ada@example.com' }) // { id: '42', email: 'ada@example.com', name: null }
+   * UserInfo.normalize({ id: 42, phone: '+91 98765 43210' }) // { id: '42', email: null, name: null, phone: '+91 98765 43210' }
    */
   static normalize(user) {
     if (user === null || user === undefined) return null;
@@ -37,25 +40,27 @@ export class UserInfo {
     let id;
     let email;
     let name;
+    let phone;
     try {
       id = firstDefined(user.id, user._id, user.userId);
       email = user.email;
       name = firstDefined(user.name, user.username);
+      phone = firstDefined(user.phone, user.phoneNumber, user.phone_number, user.mobile);
     } catch (error) {
       return null;
     }
-    const clean = { id: identifier(id), email: label(email, MAX_EMAIL), name: label(name, MAX_NAME) };
-    return clean.id || clean.email || clean.name ? clean : null;
+    const clean = { id: identifier(id), email: label(email, MAX_EMAIL), name: label(name, MAX_NAME), phone: phoneNumber(phone) };
+    return clean.id || clean.email || clean.name || clean.phone ? clean : null;
   }
 
   /**
-   * One string that tells users apart: the id, else the email, else the name.
+   * One string that tells users apart: the id, else the email, else the phone, else the name.
    *
    * @param {User|null} user
    * @returns {string|null}
    */
   static key(user) {
-    return user ? user.id || user.email || user.name || null : null;
+    return user ? user.id || user.email || user.phone || user.name || null : null;
   }
 }
 
@@ -76,6 +81,12 @@ function identifier(value) {
   return null;
 }
 
+// As the app wrote it ("+91 98765 43210"); numbers (and bigints) as their digits.
+function phoneNumber(value) {
+  if (typeof value === 'number' || typeof value === 'bigint') return label(String(value), MAX_PHONE);
+  return label(value, MAX_PHONE);
+}
+
 function label(value, max) {
   if (typeof value !== 'string') return null;
   const clean = value.trim().slice(0, max);