@procedures/mongo 0.43.0 → 0.44.0

package/src/storage/database-changes.ts

@@ -0,0 +1,357 @@
+/**
+ * One change watcher for a whole database (roadmap CLI-88). `watchDatabaseChanges()` opens the
+ * change stream of the database, and gives each raw change event to `onChange`. After an error, it
+ * opens the stream again from the resume token of the last change that `onChange` took.
+ *
+ * - The event goes to `onChange` as the driver gives it: `fullDocument`, `fullDocumentBeforeChange`
+ *   (the image before the change), `ns`, `clusterTime`, `wallTime` and each other field. Set
+ *   `fullDocumentBeforeChange` to get the image. A collection gives it only with
+ *   `changeStreamPreAndPostImages` (MongoDB 6 or later).
+ * - The events go one at a time, in the order of the stream. The watcher reads the next event
+ *   after `onChange` resolves.
+ * - The resume token is the `_id` of the last event, after its `onChange` resolved. A batch without
+ *   events gives the token of the batch (the post-batch resume token). `resumeToken` of the handle
+ *   gives the token at this time.
+ * - After an error of the stream, the watcher waits for the backoff. Then it opens the stream again
+ *   with `startAfter` and the token. Thus it loses no change and gives no change twice.
+ * - An error of `onChange` has the same backoff. The token stays at the change before, so the same
+ *   change comes again.
+ * - The backoff starts at `initialDelay` and grows by `backoffMultiplier` to at most `maxDelay`,
+ *   with `jitter`. A change or a batch without events sets it back to `initialDelay`.
+ * - Some errors do not go away. The watcher then stops, and the error goes to `onError` and to the
+ *   logger:
+ *   - An `invalidate` event (for example after `dropDatabase`). `resumeToken` is then the token of
+ *     that event: a new watcher with `startAfter` starts after it.
+ *   - A token that the server does not know any more (codes 260, 280 and 286, for example
+ *     `ChangeStreamHistoryLost`).
+ *   - Before the first open: a refused access, a single server (code 40573), a wrong option.
+ * - `stop()` or an abort of `signal` stops the watcher. It closes the stream and cancels the timer
+ *   of the backoff. An `onChange` that runs finishes, and no change comes after it.
+ * - Change streams need a replica set or a sharded cluster. The watcher asks the server (`hello`)
+ *   before the first open: on a single server, it stops with the code 40573.
+ */
+import type { ChangeStream, ChangeStreamDocument, ChangeStreamOptions, Db, Document, ResumeToken, Timestamp } from "mongodb";
+import { realClock, writeLog, type Cancel, type Clock, type LogFields, type Logger, type ResubscribeBackoff } from "@procedures/client";
+import { COMMAND_NOT_FOUND, LOST_TOKEN_CODES, backoffOf, codeOf, isPermanent, messageOf } from "./storage-hints.js";
+
+/** The options of `watchDatabaseChanges()`. */
+export interface WatchDatabaseChangesOptions<TChange extends Document = ChangeStreamDocument> {
+  /**
+   * The function that gets each raw change event, one at a time. The watcher keeps the token of
+   * the event after the function resolves. When it fails, the same event comes again after the backoff.
+   */
+  onChange: (change: TChange) => void | Promise<void>;
+  /**
+   * The function that gets the error that stops the watcher. The error is an `invalidate` event, a
+   * lost resume token, or an error of the first open that does not go away. An `invalidate` event
+   * gives an `Error` with the event in its field `change`.
+   */
+  onError?: ((error: unknown) => void) | undefined;
+  /** The resume token after which the first stream starts. Give only one of `resumeAfter`, `startAfter` and `startAtOperationTime`. */
+  resumeAfter?: ResumeToken | undefined;
+  /** The resume token after which the first stream starts, also the token of an `invalidate` event. */
+  startAfter?: ResumeToken | undefined;
+  /** The time of the cluster at which the first stream starts. */
+  startAtOperationTime?: Timestamp | undefined;
+  /** The `fullDocument` option of the stream: `updateLookup`, `whenAvailable` or `required`. */
+  fullDocument?: "updateLookup" | "whenAvailable" | "required" | undefined;
+  /** The `fullDocumentBeforeChange` option of the stream: `whenAvailable`, `required` or `off`. */
+  fullDocumentBeforeChange?: "whenAvailable" | "required" | "off" | undefined;
+  /** The pipeline of the stream, for example a `$match` of the collections. @default [] */
+  pipeline?: Document[] | undefined;
+  /** More options of the stream, for example `maxAwaitTimeMS`, `batchSize` or `showExpandedEvents`. */
+  streamOptions?: Omit<ChangeStreamOptions, "resumeAfter" | "startAfter" | "startAtOperationTime" | "fullDocument" | "fullDocumentBeforeChange"> | undefined;
+  /**
+   * The backoff before the stream opens again after an error.
+   * @default { initialDelay: ms(250), maxDelay: seconds(30), backoffMultiplier: 2, jitter: 1 }
+   */
+  backoff?: ResubscribeBackoff | undefined;
+  /**
+   * The logger of the watcher. The fields of each line hold its context: `database`, `collection`,
+   * `operationType`, `resumeToken` (true when the watcher has a token), `error`, `attempt` and `delayMs`.
+   * @default the console, with the prefix `[database-changes]`
+   */
+  logger?: Logger | undefined;
+  /** The signal that stops the watcher. */
+  signal?: AbortSignal | undefined;
+  /** The clock of the timers (default the clock of the platform). The timers do not keep a process alive. */
+  clock?: Clock | undefined;
+}
+
+/** The handle of `watchDatabaseChanges()`. */
+export interface DatabaseChangesWatch {
+  /**
+   * It resolves when the first stream is open (each later change reaches `onChange`), or when the
+   * watcher stops. It rejects when the watcher stops on an error before the first open.
+   */
+  readonly ready: Promise<void>;
+  /** The resume token of the last change that `onChange` took, or of the last batch without events. It is undefined before the first open without a start token. */
+  readonly resumeToken: ResumeToken | undefined;
+  /** True after `stop()`, an abort of `signal`, or an error that stops the watcher. */
+  readonly stopped: boolean;
+  /** This method stops the watcher: it closes the stream and cancels the timer of a backoff. */
+  stop(): Promise<void>;
+}
+
+/** An error of `onChange`: the watcher waits, and gives the same change again. */
+class HandlerError extends Error {
+  constructor(
+    readonly error: unknown,
+    readonly change: Document
+  ) {
+    super(`onChange failed: ${messageOf(error)}`);
+  }
+}
+
+/** The collection of a change event, from its `ns`. */
+function collectionOf(change: Document): unknown {
+  const ns: unknown = change["ns"];
+  return typeof ns === "object" && ns !== null ? (ns as Document)["coll"] : undefined;
+}
+
+/**
+ * This function watches the change stream of a whole database, and gives each raw change event to
+ * `onChange` (roadmap CLI-88). After an error, it opens the stream again from the resume token,
+ * after a bounded backoff. Refer to the module comment for the rules.
+ *
+ * @param db - The database, or a function that gives it
+ * @param options - The handlers, the start of the stream, its options, the backoff, the logger and the signal
+ * @returns The handle: `ready`, `resumeToken`, `stopped` and `stop()`
+ *
+ * @example
+ * ```typescript
+ * const watch = watchDatabaseChanges(db, {
+ *   fullDocument: "updateLookup",
+ *   fullDocumentBeforeChange: "whenAvailable",
+ *   resumeAfter: savedToken,
+ *   onChange: async (change) => {
+ *     await apply(change);
+ *     savedToken = change._id;
+ *   },
+ *   onError: (error) => console.error("the watcher stopped", error),
+ *   logger,
+ * });
+ * await watch.ready;
+ * // ...
+ * await watch.stop();
+ * ```
+ */
+export function watchDatabaseChanges<TChange extends Document = ChangeStreamDocument>(
+  db: Db | (() => Db | Promise<Db>),
+  options: WatchDatabaseChangesOptions<TChange>
+): DatabaseChangesWatch {
+  if (typeof options?.onChange !== "function") throw new TypeError("onChange must be a function");
+  const starts = [options.resumeAfter, options.startAfter, options.startAtOperationTime].filter((value) => value !== undefined);
+  if (starts.length > 1) throw new TypeError("give only one of resumeAfter, startAfter and startAtOperationTime");
+  const delayOf = backoffOf(options.backoff);
+  const clock = options.clock ?? realClock;
+  const logger = options.logger;
+  const dbOf = typeof db === "function" ? db : (): Db => db;
+
+  let stopped = false;
+  /** The token of the last change that `onChange` took, or of the last batch without events. */
+  let token: ResumeToken | undefined = options.startAfter ?? options.resumeAfter;
+  /** True after a stream was open. */
+  let opened = false;
+  /** True after the server said that it has change streams. */
+  let checked = false;
+  /** The tries since the last success. The backoff gives the delay of the next try from it. */
+  let attempt = 0;
+  let database: string | undefined;
+  let stream: ChangeStream<Document, TChange> | undefined;
+  /** The timer of a backoff, and the end of its wait. */
+  let timer: Cancel | undefined;
+  let wake: (() => void) | undefined;
+  let markReady: () => void = () => undefined;
+  let failReady: (error: unknown) => void = () => undefined;
+  const ready = new Promise<void>((resolve, reject) => {
+    markReady = resolve;
+    failReady = reject;
+  });
+  // A caller that does not wait for `ready` gets no unhandled rejection: the logger tells the error
+  ready.catch(() => undefined);
+
+  const log = (level: "info" | "warn" | "error", message: string, fields: LogFields): void => {
+    const all = { component: "database-changes", database, resumeToken: token !== undefined, ...fields };
+    writeLog(logger, level, message, all, `[database-changes] ${message}`, all);
+  };
+
+  /** The end of the watcher after an error that does not go away. */
+  const fail = (error: unknown, fields: LogFields): void => {
+    if (stopped) return;
+    log("error", "The change stream stopped: the error does not go away", { error, ...fields });
+    halt();
+    failReady(error);
+    try {
+      options.onError?.(error);
+    } catch (thrown) {
+      log("error", "onError failed", { error: thrown });
+    }
+  };
+
+  /** The wait of the backoff. `stop()` ends it. */
+  const backoff = (message: string, fields: LogFields): Promise<void> => {
+    const delay = delayOf(attempt);
+    attempt++;
+    log("warn", message, { ...fields, attempt, delayMs: Math.round(delay) });
+    return new Promise<void>((resolve) => {
+      wake = resolve;
+      timer = clock.after(delay, () => {
+        timer = undefined;
+        wake = undefined;
+        resolve();
+      });
+      timer.unref?.();
+    });
+  };
+
+  /** The start of the next stream: after the token, else the start of the options. */
+  const start = (): Pick<ChangeStreamOptions, "resumeAfter" | "startAfter" | "startAtOperationTime"> => {
+    if (!opened && options.resumeAfter !== undefined) return { resumeAfter: options.resumeAfter };
+    if (token !== undefined) return { startAfter: token };
+    return options.startAtOperationTime !== undefined ? { startAtOperationTime: options.startAtOperationTime } : {};
+  };
+
+  /** The stream is open: the next change reaches `onChange`. */
+  const markOpen = (): void => {
+    if (opened || stopped) return;
+    opened = true;
+    markReady();
+  };
+
+  /** A success: a batch without events, or a change that `onChange` took. The backoff starts again. */
+  const succeeded = (): void => {
+    if (attempt > 0) log("info", "The change stream opened again", { attempts: attempt });
+    attempt = 0;
+  };
+
+  /** One stream: it reads the events until an error, an `invalidate` event or the stop. */
+  const read = async (next: ChangeStream<Document, TChange>): Promise<void> => {
+    for (;;) {
+      const change = await next.tryNext();
+      if (stopped) return;
+      markOpen();
+      if (change === null) {
+        // A batch without events: its token is after each event that `onChange` took
+        const batchToken = next.resumeToken;
+        if (batchToken !== undefined && batchToken !== null) token = batchToken;
+        succeeded();
+        continue;
+      }
+      if (change["operationType"] === "invalidate") {
+        token = change["_id"];
+        return fail(Object.assign(new Error(`the change stream of the database ${database ?? ""} was invalidated`), { change }), { operationType: "invalidate" });
+      }
+      try {
+        await options.onChange(change);
+      } catch (error) {
+        throw new HandlerError(error, change);
+      }
+      token = change["_id"];
+      succeeded();
+    }
+  };
+
+  const run = async (): Promise<void> => {
+    while (!stopped) {
+      let handle: Db;
+      try {
+        handle = await dbOf();
+        database = handle.databaseName;
+        if (!checked) {
+          // On a single server, the driver can wait without an error: the watcher asks the server first
+          let hello: Document | undefined;
+          try {
+            hello = await handle.command({ hello: 1 });
+          } catch (error) {
+            // An old server without hello: the stream tells the error
+            if (codeOf(error) !== COMMAND_NOT_FOUND) throw error;
+          }
+          if (hello && typeof hello["setName"] !== "string" && hello["msg"] !== "isdbgrid") {
+            const single = Object.assign(new Error("change streams need a replica set or a sharded cluster, and the server is a single server"), { code: 40573 });
+            return fail(single, { code: 40573 });
+          }
+          checked = true;
+        }
+      } catch (error) {
+        if (stopped) return;
+        if (!opened && isPermanent(error)) return fail(error, { code: codeOf(error) });
+        await backoff("The database is not available: the change stream opens again after a backoff", { error, code: codeOf(error) });
+        continue;
+      }
+      if (stopped) return;
+      if (token === undefined && opened) log("warn", "The change stream opens again without a resume token: it can miss changes", {});
+      try {
+        const next = handle.watch<Document, TChange>(options.pipeline ?? [], {
+          ...options.streamOptions,
+          ...(options.fullDocument !== undefined && { fullDocument: options.fullDocument }),
+          ...(options.fullDocumentBeforeChange !== undefined && { fullDocumentBeforeChange: options.fullDocumentBeforeChange }),
+          ...start(),
+        });
+        stream = next;
+        // The first token of the stream comes with the answer of the server: the stream is open, before the first getMore
+        next.on("resumeTokenChanged", markOpen);
+        try {
+          await read(next);
+        } finally {
+          if (stream === next) stream = undefined;
+          await next.close().catch(() => undefined);
+        }
+      } catch (error) {
+        if (stopped) return;
+        if (error instanceof HandlerError) {
+          await backoff("onChange failed: the same change comes again after a backoff", {
+            error: error.error,
+            collection: collectionOf(error.change),
+            operationType: error.change["operationType"],
+          });
+          continue;
+        }
+        const code = codeOf(error);
+        if (code !== undefined && LOST_TOKEN_CODES.has(code)) return fail(error, { code });
+        if (!opened && isPermanent(error)) return fail(error, { code });
+        await backoff("The change stream failed: it opens again after a backoff", { error, code });
+      }
+    }
+  };
+
+  /** The end of the watcher: no new stream, no timer. */
+  const halt = (): void => {
+    stopped = true;
+    timer?.();
+    timer = undefined;
+    wake?.();
+    wake = undefined;
+    options.signal?.removeEventListener("abort", onAbort);
+  };
+
+  const stop = async (): Promise<void> => {
+    if (stopped) return;
+    halt();
+    markReady();
+    const current = stream;
+    stream = undefined;
+    await current?.close().catch(() => undefined);
+  };
+
+  const onAbort = (): void => void stop();
+
+  if (options.signal?.aborted) {
+    stopped = true;
+    markReady();
+  } else {
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    void run().catch((error: unknown) => fail(error, {}));
+  }
+
+  return {
+    ready,
+    get resumeToken(): ResumeToken | undefined {
+      return token;
+    },
+    get stopped(): boolean {
+      return stopped;
+    },
+    stop,
+  };
+}

package/src/storage/index.ts

@@ -18,6 +18,9 @@ export type { MongoDocumentStorageOptions, SelectorPrefilterOptions, StoredForm,
 // The change hints of a storage collection from its change stream (roadmap CLI-77)
 export { watchStorageChanges, storageChangeOf } from "./storage-hints.js";
 export type { StorageChange, StorageChangeHint, StorageChangesWatch, StorageHintPublisher, WatchStorageChangesOptions } from "./storage-hints.js";
+// One change watcher for a whole database, with resume and backoff (roadmap CLI-88)
+export { watchDatabaseChanges } from "./database-changes.js";
+export type { DatabaseChangesWatch, WatchDatabaseChangesOptions } from "./database-changes.js";
 export {
   BLOCKED_PIPELINE_OPERATORS,
   ALLOWED_PIPELINE_STAGES,

package/src/storage/materializer.ts

@@ -56,7 +56,7 @@
 import { createHash } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { BSON, ObjectId, type AnyBulkWriteOperation, type ChangeStream, type ClientSession, type Collection, type Db, type Document } from "mongodb";
-import { collectionChangeTopic, ms, optionalMs, realClock, type Cancel, type Clock, type CollectionChangeEvent, type Duration } from "@procedures/client";
+import { collectionChangeTopic, ms, optionalMs, realClock, writeLog, type Cancel, type Clock, type CollectionChangeEvent, type Duration, type LogFields, type Logger } from "@procedures/client";
 import { DEFAULT_STORED_FORM, DOCUMENT_STORAGE_FIELDS, MongoDocumentStorage, TOMBSTONE_FIELD, storageWriteTarget, type StorageWriteTarget, type StoredForm } from "./document-storage.js";
 import { scopePipeline } from "./pipeline-scope.js";
 import type { StorageHintPublisher } from "./storage-hints.js";
@@ -126,7 +126,16 @@ export interface ViewMaterializerOptions {
   maxTime?: Duration | undefined;
   /** The most rows of the result of a view (default 100000). A larger result is an error of the view. */
   maxRows?: number | undefined;
-  /** The log (default `console`, with the prefix `[materializer]`). */
+  /**
+   * The logger of the materializer (CLI-88). The fields of each line hold its context: the view, the
+   * partition, the collection, the error and the delay. When both are set, `logger` wins over `log`.
+   * @default the console, with the prefix `[materializer]`
+   */
+  logger?: Logger | undefined;
+  /**
+   * The log function of each line, with the context in the text.
+   * @deprecated Use `logger`. Without a `logger`, the materializer still uses `log`.
+   */
   log?: ((level: "info" | "warn" | "error", message: string) => void) | undefined;
   /** The clock of the timers (default the clock of the platform). A test gives a fake clock. The timers do not keep a process alive. */
   clock?: Clock | undefined;
@@ -554,9 +563,11 @@ export class ViewMaterializer {
     return entry === undefined || entry === null ? undefined : this.storageTargetOf(collection, entry);
   }
 
-  private log(level: "info" | "warn" | "error", message: string): void {
-    if (this.options.log) this.options.log(level, message);
-    else console[level === "info" ? "log" : level](`[materializer] ${message}`);
+  /** This method writes one line: to `logger` with the fields, else to the old `log` with the text, else to the console with the text. */
+  private log(level: "info" | "warn" | "error", message: string, fields: LogFields, text: string): void {
+    const { logger, log } = this.options;
+    if (!logger && log) log(level, text);
+    else writeLog(logger, level, message, { component: "materializer", ...fields }, `[materializer] ${text}`);
   }
 
   /**
@@ -600,7 +611,7 @@ export class ViewMaterializer {
     // The stream of the views opens before the read of the views: a change between the two reaches both (roadmap O63)
     await this.watchViews();
     const count = await this.resync();
-    this.log("info", `started: ${count} view(s)`);
+    this.log("info", "Started", { views: count }, `started: ${count} view(s)`);
   }
 
   /** This method stops the passes of new changes: a change starts no pass, and a waiting pass does not start. */
@@ -713,7 +724,7 @@ export class ViewMaterializer {
     try {
       stream = this.db.collection(this.viewsName).watch([], { fullDocument: "updateLookup" });
     } catch (error) {
-      this.log("error", `cannot watch ${this.viewsName}: ${String((error as Error)?.message ?? error)}`);
+      this.log("error", "Cannot watch the views", { collection: this.viewsName, error }, `cannot watch ${this.viewsName}: ${String((error as Error)?.message ?? error)}`);
       this.later(() => void this.watchViews());
       return Promise.resolve();
     }
@@ -725,11 +736,11 @@ export class ViewMaterializer {
     const rewatch = (reason: string): void => {
       if (again || this.stopped || this.viewsStream !== stream) return;
       again = true;
-      this.log("warn", `the stream of ${this.viewsName} ${reason}: it opens again in ${this.rewatchMs} ms`);
+      this.log("warn", "The stream of the views ended: it opens again", { collection: this.viewsName, reason, delayMs: this.rewatchMs }, `the stream of ${this.viewsName} ${reason}: it opens again in ${this.rewatchMs} ms`);
       stream.close().catch(() => undefined);
       this.later(() => {
         // The changes while the stream was closed are lost: a resync catches up, after the new stream is open
-        void this.track(this.watchViews().then(() => this.resync())).catch((error: unknown) => this.log("error", `the resync failed: ${String((error as Error)?.message ?? error)}`));
+        void this.track(this.watchViews().then(() => this.resync())).catch((error: unknown) => this.log("error", "The resync failed", { collection: this.viewsName, error }, `the resync failed: ${String((error as Error)?.message ?? error)}`));
       });
     };
 
@@ -742,7 +753,7 @@ export class ViewMaterializer {
         // A write of the status only is ours: it does not open the view again
         if (touched.length > 0 && touched.every((path) => path === this.statusField || path.startsWith(`${this.statusField}.`))) return;
       }
-      void this.track(this.onViewChange(change)).catch((error: unknown) => this.log("error", `a change of a view failed: ${String((error as Error)?.message ?? error)}`));
+      void this.track(this.onViewChange(change)).catch((error: unknown) => this.log("error", "A change of a view failed", { collection: this.viewsName, operationType: change["operationType"], error }, `a change of a view failed: ${String((error as Error)?.message ?? error)}`));
     });
     stream.on("error", (error: Error) => rewatch(`failed: ${error.message}`));
     stream.on("close", () => rewatch("closed"));
@@ -781,11 +792,11 @@ export class ViewMaterializer {
   private register(view: MaterializedView): boolean {
     const partition = this.partitionOf(view);
     if (partition === undefined) {
-      this.log("warn", `the view ${String(view._id)} has no ${this.partitionField}: it does not run`);
+      this.log("warn", "The view has no partition: it does not run", { view: view._id, partitionField: this.partitionField }, `the view ${String(view._id)} has no ${this.partitionField}: it does not run`);
       return false;
     }
     if (!Array.isArray(view.collections) || view.collections.length === 0 || typeof view.targetCollection !== "string" || !Array.isArray(view.pipeline)) {
-      this.log("warn", `the view ${view._id} needs collections, a pipeline and a targetCollection: it does not run`);
+      this.log("warn", "The view needs collections, a pipeline and a targetCollection: it does not run", { view: view._id, partition }, `the view ${view._id} needs collections, a pipeline and a targetCollection: it does not run`);
       return false;
     }
     this.running.set(this.keyOf(partition, view._id), { view, partition, state: "active", streams: [] });
@@ -799,19 +810,19 @@ export class ViewMaterializer {
     await this.db!
       .collection(view.targetCollection)
       .createIndex({ [this.partitionField]: 1, [VIEW_GENERATION_FIELD]: 1 })
-      .catch((error: unknown) => this.log("error", `the index of ${view.targetCollection} failed: ${String((error as Error)?.message ?? error)}`));
+      .catch((error: unknown) => this.log("error", "The index of the target failed", { view: view._id, collection: view.targetCollection, error }, `the index of ${view.targetCollection} failed: ${String((error as Error)?.message ?? error)}`));
     // A target in a stored form also has the indexes of the storage: the change reads, the order and the tombstones
     let storageTarget: StorageTargetEntry | undefined;
     try {
       storageTarget = this.storageTargetFor(view.targetCollection);
     } catch (error) {
       // The run of the view gives the error to its status
-      this.log("error", `the storage target ${view.targetCollection}: ${String((error as Error)?.message ?? error)}`);
+      this.log("error", "The storage target is not valid", { view: view._id, collection: view.targetCollection, error }, `the storage target ${view.targetCollection}: ${String((error as Error)?.message ?? error)}`);
     }
     if (storageTarget) {
       await storageWriteTarget(storageTarget.storage)
         .ready()
-        .catch((error: unknown) => this.log("error", `the indexes of the storage ${view.targetCollection} failed: ${String((error as Error)?.message ?? error)}`));
+        .catch((error: unknown) => this.log("error", "The indexes of the storage target failed", { view: view._id, collection: view.targetCollection, error }, `the indexes of the storage ${view.targetCollection} failed: ${String((error as Error)?.message ?? error)}`));
     }
     await this.rebalance(partition);
   }
@@ -914,7 +925,7 @@ export class ViewMaterializer {
         .collection(source)
         .watch([this.sourceMatch(running.partition)], { fullDocument: "updateLookup", fullDocumentBeforeChange: "whenAvailable" });
     } catch (error) {
-      this.log("error", `cannot watch ${source} for the view ${running.view._id}: ${String((error as Error)?.message ?? error)}`);
+      this.log("error", "Cannot watch a source of the view", { view: running.view._id, partition: running.partition, collection: source, error }, `cannot watch ${source} for the view ${running.view._id}: ${String((error as Error)?.message ?? error)}`);
       this.later(() => {
         if (this.isCurrent(running) && running.state === "active") void this.watchSource(running, source);
       });
@@ -930,7 +941,7 @@ export class ViewMaterializer {
       // A close of a teardown also ends the stream: open again only a stream of a current active view
       if (index === -1 || !this.isCurrent(running) || running.state !== "active") return;
       running.streams.splice(index, 1);
-      this.log("warn", `the stream of ${source} for the view ${running.view._id} ${reason}: it opens again in ${this.rewatchMs} ms`);
+      this.log("warn", "The stream of a source ended: it opens again", { view: running.view._id, partition: running.partition, collection: source, reason, delayMs: this.rewatchMs }, `the stream of ${source} for the view ${running.view._id} ${reason}: it opens again in ${this.rewatchMs} ms`);
       this.later(() => {
         if (!this.isCurrent(running) || running.state !== "active") return;
         // The changes while the stream was closed are lost: a pass catches up, after the new stream is open
@@ -969,7 +980,7 @@ export class ViewMaterializer {
       this.timers.delete(partition);
       if (!this.intake) return;
       void this.serial(partition, () => this.pass(partition)).catch((error: unknown) =>
-        this.log("error", `the pass of ${partition} failed: ${String((error as Error)?.message ?? error)}`)
+        this.log("error", "The pass failed", { partition, error }, `the pass of ${partition} failed: ${String((error as Error)?.message ?? error)}`)
       );
     });
     cancel.unref?.();
@@ -1054,12 +1065,12 @@ export class ViewMaterializer {
     } catch (error) {
       if (error instanceof PassSuperseded) {
         // Not an error of the view: another process builds it now. A pass comes back after `rewatch`
-        this.log("info", `${view._id}: ${error.message}: the view runs again later`);
+        this.log("info", "The pass gave way: the view runs again later", { view: view._id, partition, reason: error.message }, `${view._id}: ${error.message}: the view runs again later`);
         this.later(() => this.schedule(partition, view.collections[0]!));
         return { changed: false };
       }
       const message = String((error as Error)?.message ?? error);
-      this.log("error", `${view._id}: ${message}`);
+      this.log("error", "The view failed", { view: view._id, partition, error }, `${view._id}: ${message}`);
       await this.writeStatus(view, partition, { state: "errored", lastError: message, at: Date.now() });
       return { changed: false };
     }
@@ -1101,7 +1112,7 @@ export class ViewMaterializer {
             }
             throw new PassSuperseded(`another process wrote the view at the same time (${String((error as Error)?.message ?? error)})`);
           }
-          this.log("warn", `${view._id}: the transaction failed (${String((error as Error)?.message ?? error)}): the pass writes ${storage ? "in groups" : "a new generation in groups"}`);
+          this.log("warn", "The transaction failed: the pass writes in groups", { view: view._id, partition, error }, `${view._id}: the transaction failed (${String((error as Error)?.message ?? error)}): the pass writes ${storage ? "in groups" : "a new generation in groups"}`);
           break;
         }
       }
@@ -1369,7 +1380,7 @@ export class ViewMaterializer {
   private publishHint(view: MaterializedView, partition: string, ids: { changed: readonly unknown[]; deleted: readonly unknown[] } | undefined): void {
     const publish = this.options.publish;
     if (!publish) return;
-    const fail = (error: unknown): void => this.log("error", `the hint of ${view._id} failed: ${String((error as Error)?.message ?? error)}`);
+    const fail = (error: unknown): void => this.log("error", "The hint of the view failed", { view: view._id, partition, error }, `the hint of ${view._id} failed: ${String((error as Error)?.message ?? error)}`);
     try {
       const topic = this.options.hintTopic ? this.options.hintTopic(view, partition) : collectionChangeTopic(view._id);
       if (topic === undefined) return;
@@ -1431,7 +1442,7 @@ export class ViewMaterializer {
       void this.serial(partition, async () => {
         const { status, now } = await this.statusOf(view, partition);
         await this.dropOldGenerations(target, partition, status, now);
-      }).catch((error: unknown) => this.log("error", `${view._id}: ${String((error as Error)?.message ?? error)}`));
+      }).catch((error: unknown) => this.log("error", "The drop of the old generations failed", { view: view._id, partition, error }, `${view._id}: ${String((error as Error)?.message ?? error)}`));
     });
     cancel.unref?.();
     this.retries.add(cancel);
@@ -1628,7 +1639,7 @@ export class ViewMaterializer {
       await this.releaseLease(view, partition, owner).catch(() => undefined);
       throw error;
     } finally {
-      if (removed) await storage.writer.prune(db).catch((error: unknown) => this.log("error", `${view._id}: the prune of the tombstones failed: ${String((error as Error)?.message ?? error)}`));
+      if (removed) await storage.writer.prune(db).catch((error: unknown) => this.log("error", "The prune of the tombstones failed", { view: view._id, partition, error }, `${view._id}: the prune of the tombstones failed: ${String((error as Error)?.message ?? error)}`));
     }
     return changed;
   }
@@ -1700,7 +1711,7 @@ export class ViewMaterializer {
     try {
       await this.db!.collection(this.viewsName).updateOne({ _id: view._id, [this.partitionField]: partition } as Document, update);
     } catch (error) {
-      this.log("error", `the status of ${view._id} failed: ${String((error as Error)?.message ?? error)}`);
+      this.log("error", "The status of the view failed", { view: view._id, partition, error }, `the status of ${view._id} failed: ${String((error as Error)?.message ?? error)}`);
     }
   }
 }