envio 3.12.1 → 3.13.0-alpha.0

package/src/CrossChainState.res

@@ -17,6 +17,11 @@ type t = {
   mutable isCaughtUp: bool,
   // Indexer-wide fetch buffer pool (item count), shared across all chains.
   targetBufferSize: int,
+  // Set on a process driving part of a split run: the chains it drives may be
+  // at the head while chains in another process are still backfilling, and an
+  // indexer switches to realtime as a whole or not at all. Cleared by the
+  // supervisor once every chain in the run has arrived.
+  mutable holdRealtime: bool,
 }
 
 // The whole-indexer fetch buffer pool, independent of chain count.
@@ -26,16 +31,50 @@ let calculateTargetBufferSize = () =>
   | None => 100_000
   }
 
-let make = (~chainStates, ~isRealtime, ~targetBufferSize=calculateTargetBufferSize()): t => {
+let make = (
+  ~chainStates,
+  ~isRealtime,
+  ~targetBufferSize=calculateTargetBufferSize(),
+  ~holdRealtime=false,
+): t => {
   {
     chainStates,
     chainIds: chainStates->Dict.valuesToArray->Array.map(cs => (cs->ChainState.chainConfig).id),
     isRealtime,
     isCaughtUp: isRealtime,
     targetBufferSize,
+    holdRealtime,
   }
 }
 
+// The supervisor's go-ahead: every chain in the run has reached the head, so
+// this process may make the transitions it has been holding back.
+let releaseRealtime = (crossChainState: t) => crossChainState.holdRealtime = false
+
+let isHoldingRealtime = (crossChainState: t) => crossChainState.holdRealtime
+
+// Whether this process has got as far as it can without the run's leave. What a
+// supervisor reads to decide that a split run may go realtime as one.
+//
+// Three ways to have arrived, because a chain can be as far along as it can get
+// in three different states. Its chains have caught up; or it resumed already
+// realtime; or every chain is waiting to enter the reorg threshold, which is as
+// far as one can fetch while the pre-threshold lag holds it at the safe block —
+// entering the threshold is what lifts that lag, so a run held until its chains
+// reached the head would be holding back the transition that gets them there.
+//
+// The process's own conclusion rather than a reading a supervisor reassembles:
+// a chain committed at what was the head and resumed once the head had moved on
+// has arrived, and no live reading of it can say so — which is the same reason
+// `markCaughtUpOnResume` decides before any source request.
+let hasArrivedAtHead = (crossChainState: t) =>
+  crossChainState.isCaughtUp ||
+  crossChainState.isRealtime || {
+      let chainStates = crossChainState.chainStates->Dict.valuesToArray
+      chainStates->Utils.Array.notEmpty &&
+        chainStates->Array.every(ChainState.isReadyToEnterReorgThreshold)
+    }
+
 // Resolve a chain's state by id. The id always comes from `chainIds`, which is
 // derived from `chainStates`, so the entry is guaranteed present.
 let getChainState = (crossChainState: t, chainId) =>
@@ -122,6 +161,16 @@ let createBatch = (
 
 // Enter the reorg threshold: shrink each chain's buffer by its configured
 // blockLag and flip the flag.
+// Whether every chain this process drives has buffered close enough to the head
+// to enter the threshold together — and, in a split run, whether the rest of the
+// run has too. Chains enter it as one indexer, so one chain still backfilling
+// holds the others back whatever process it runs in.
+let isReadyToEnterReorgThreshold = (crossChainState: t, ~batch) =>
+  !crossChainState.holdRealtime &&
+    crossChainState.chainStates
+    ->Dict.valuesToArray
+    ->Array.every(cs => cs->ChainState.isReadyToEnterReorgThresholdAfterBatch(~batch))
+
 let enterReorgThreshold = (crossChainState: t) => {
   Logging.info("Reorg threshold reached")
 
@@ -150,7 +199,10 @@ let applyBatchProgress = (crossChainState: t, ~batch: Batch.t, ~blockTimestampNa
   }
 
   crossChainState.isCaughtUp =
-    crossChainState.isCaughtUp || (crossChainState->nextItemIsNone && everyChainCaughtUp.contents)
+    crossChainState.isCaughtUp ||
+      (!crossChainState.holdRealtime &&
+      crossChainState->nextItemIsNone &&
+      everyChainCaughtUp.contents)
 }
 
 // Every chain has buffered up to its head (or endblock) with nothing
@@ -174,8 +226,13 @@ let isSettledAtHead = (crossChainState: t) => {
 }
 
 // Enter the FinalizingIndexes phase without a batch, for the resume above.
+// Not while the run holds this process back: the hold keeps the pre-threshold
+// lag in place, and a chain that has fetched to a lagged head it was never
+// going to get past reads as settled without having indexed anything. What a
+// held process may conclude about where it stands, it concludes from what was
+// persisted — see `markCaughtUpOnResume`, which the hold leaves alone.
 let markCaughtUpIfSettled = (crossChainState: t) =>
-  if crossChainState->isSettledAtHead {
+  if !crossChainState.holdRealtime && crossChainState->isSettledAtHead {
     crossChainState.isCaughtUp = true
   }
 

package/src/CrossChainState.res.mjs

@@ -20,19 +20,41 @@ function calculateTargetBufferSize() {
   }
 }
 
-function make(chainStates, isRealtime, targetBufferSizeOpt) {
+function make(chainStates, isRealtime, targetBufferSizeOpt, holdRealtimeOpt) {
   let targetBufferSize = targetBufferSizeOpt !== undefined ? targetBufferSizeOpt : (
       Env.targetBufferSize !== undefined ? Env.targetBufferSize : 100000
     );
+  let holdRealtime = holdRealtimeOpt !== undefined ? holdRealtimeOpt : false;
   return {
     chainStates: chainStates,
     chainIds: Object.values(chainStates).map(cs => ChainState.chainConfig(cs).id),
     isRealtime: isRealtime,
     isCaughtUp: isRealtime,
-    targetBufferSize: targetBufferSize
+    targetBufferSize: targetBufferSize,
+    holdRealtime: holdRealtime
   };
 }
 
+function releaseRealtime(crossChainState) {
+  crossChainState.holdRealtime = false;
+}
+
+function isHoldingRealtime(crossChainState) {
+  return crossChainState.holdRealtime;
+}
+
+function hasArrivedAtHead(crossChainState) {
+  if (crossChainState.isCaughtUp || crossChainState.isRealtime) {
+    return true;
+  }
+  let chainStates = Object.values(crossChainState.chainStates);
+  if (Utils.$$Array.notEmpty(chainStates)) {
+    return chainStates.every(ChainState.isReadyToEnterReorgThreshold);
+  } else {
+    return false;
+  }
+}
+
 function chainStates(crossChainState) {
   return crossChainState.chainStates;
 }
@@ -94,6 +116,14 @@ function createBatch(crossChainState, config, frontier, batchSizeTarget) {
   return Batch.make(config.checkpointSequence, frontier, Utils.Dict.mapValues(crossChainState.chainStates, none => ChainState.toChainBeforeBatch(none, crossChainState.isRealtime)), batchSizeTarget, HistoryPolicy.decide(config, shouldSaveHistory(crossChainState)));
 }
 
+function isReadyToEnterReorgThreshold(crossChainState, batch) {
+  if (crossChainState.holdRealtime) {
+    return false;
+  } else {
+    return Object.values(crossChainState.chainStates).every(cs => ChainState.isReadyToEnterReorgThresholdAfterBatch(cs, batch));
+  }
+}
+
 function enterReorgThreshold(crossChainState) {
   Logging.info("Reorg threshold reached");
   for (let i = 0, i_finish = crossChainState.chainIds.length; i < i_finish; ++i) {
@@ -111,7 +141,7 @@ function applyBatchProgress(crossChainState, batch, blockTimestampName) {
       everyChainCaughtUp = false;
     }
   }
-  crossChainState.isCaughtUp = crossChainState.isCaughtUp || nextItemIsNone(crossChainState) && everyChainCaughtUp;
+  crossChainState.isCaughtUp = crossChainState.isCaughtUp || !crossChainState.holdRealtime && nextItemIsNone(crossChainState) && everyChainCaughtUp;
 }
 
 function isSettledAtHead(crossChainState) {
@@ -125,7 +155,7 @@ function isSettledAtHead(crossChainState) {
 }
 
 function markCaughtUpIfSettled(crossChainState) {
-  if (isSettledAtHead(crossChainState)) {
+  if (!crossChainState.holdRealtime && isSettledAtHead(crossChainState)) {
     crossChainState.isCaughtUp = true;
     return;
   }
@@ -256,6 +286,10 @@ export {
   shouldSaveHistory,
   nextItemIsNone,
   getSafeCheckpointIdByChain,
+  releaseRealtime,
+  isHoldingRealtime,
+  hasArrivedAtHead,
+  isReadyToEnterReorgThreshold,
   createBatch,
   enterReorgThreshold,
   applyBatchProgress,

package/src/CrossChainState.resi

@@ -5,7 +5,12 @@ type t
 
 let calculateTargetBufferSize: unit => int
 
-let make: (~chainStates: dict<ChainState.t>, ~isRealtime: bool, ~targetBufferSize: int=?) => t
+let make: (
+  ~chainStates: dict<ChainState.t>,
+  ~isRealtime: bool,
+  ~targetBufferSize: int=?,
+  ~holdRealtime: bool=?,
+) => t
 
 // Accessors.
 let chainStates: t => dict<ChainState.t>
@@ -25,6 +30,10 @@ let getSafeCheckpointIdByChain: (
 ) => array<(ChainId.t, option<Internal.checkpointId>)>
 
 // Cross-chain transitions.
+let releaseRealtime: t => unit
+let isHoldingRealtime: t => bool
+let hasArrivedAtHead: t => bool
+let isReadyToEnterReorgThreshold: (t, ~batch: Batch.t) => bool
 let createBatch: (t, ~config: Config.t, ~frontier: Frontier.t, ~batchSizeTarget: int) => Batch.t
 let enterReorgThreshold: t => unit
 let applyBatchProgress: (t, ~batch: Batch.t, ~blockTimestampName: string) => unit

package/src/Env.res

@@ -127,6 +127,10 @@ module Db = {
     //the SSL modes should be provided as string otherwise as 'require' | 'allow' | 'prefer' | 'verify-full'
     ~devFallback=Bool(false),
   )
+  // The budget for the whole run, not for one process: a run that splits across
+  // workers divides it among them, and each caps its own pool to its share.
+  // The default buys a single worker, so a run splits only once the operator
+  // raises the budget it may spend.
   let maxConnections = envSafe->EnvSafe.get("ENVIO_PG_MAX_CONNECTIONS", S.int, ~fallback=2)
 }
 

package/src/IndexerLoop.res

@@ -45,6 +45,8 @@ let start = (state: IndexerState.t) => {
     launch(state, () => FinalizeBackfill.repairSchemaIndexes(state))
   }
 
+  state->IndexerState.bindScheduleProcessing(scheduleProcessing)
+
   scheduleFetch()
   scheduleProcessing()
 }

package/src/IndexerLoop.res.mjs

@@ -42,6 +42,7 @@ function start(state) {
       work();
     }
   }
+  IndexerState.bindScheduleProcessing(state, scheduleProcessing);
   scheduleFetch();
   scheduleProcessing();
 }

package/src/IndexerState.res

@@ -115,6 +115,10 @@ type t = {
   // waitForNewBlock waiter is bound to the old, pre-realtime source). A fetch
   // response or waiter carrying an older epoch than this is discarded.
   mutable epoch: int,
+  // The loop's one door in from outside it: IndexerLoop owns scheduling and
+  // wires this when it starts, so an event the loop can't see for itself can
+  // still make it re-evaluate. A no-op before then.
+  mutable scheduleProcessing: unit => unit,
   // None off the simulate path.
   simulateDeadInputTracker: option<SimulateDeadInputTracker.t>,
   // --- Metric counters, rendered by Metrics at scrape time. ---
@@ -141,6 +145,7 @@ let make = (
   ~chainStates: dict<ChainState.t>,
   ~isRealtime: bool,
   ~targetBufferSize=CrossChainState.calculateTargetBufferSize(),
+  ~holdRealtime=false,
   ~committedFrontier=Frontier.empty(),
   ~isDevelopmentMode=false,
   ~shouldUseTui=false,
@@ -180,11 +185,17 @@ let make = (
     chainMetaDirty: false,
     chainMetaThrottler,
     isProcessing: false,
-    crossChainState: CrossChainState.make(~chainStates, ~isRealtime, ~targetBufferSize),
+    crossChainState: CrossChainState.make(
+      ~chainStates,
+      ~isRealtime,
+      ~targetBufferSize,
+      ~holdRealtime,
+    ),
     indexerStartTime: Date.make(),
     indexerStartTimeRef: Performance.now(),
     rollbackState: NoRollback,
     lastPrunedAtMillis: Dict.make(),
+    scheduleProcessing: () => (),
     loadManager: LoadManager.make(),
     keepProcessAlive: isDevelopmentMode || shouldUseTui,
     exitAfterFirstEventBlock,
@@ -227,6 +238,9 @@ let makeFromDbState = (
   ~exitAfterFirstEventBlock=false,
   ~reducedPollingInterval=?,
   ~targetBufferSize=CrossChainState.calculateTargetBufferSize(),
+  // A process driving part of a split run waits for its supervisor before
+  // entering the reorg threshold or switching to realtime.
+  ~holdRealtime=false,
   ~onError,
   ~onExit=?,
 ) => {
@@ -274,6 +288,7 @@ let makeFromDbState = (
     ~chainStates,
     ~isRealtime,
     ~targetBufferSize,
+    ~holdRealtime,
     ~committedFrontier=initialState.checkpointFrontier,
     ~isDevelopmentMode,
     ~shouldUseTui,
@@ -500,9 +515,33 @@ let isFinalizingIndexes = (state: t) =>
   state.crossChainState->CrossChainState.isCaughtUp &&
     !(state.crossChainState->CrossChainState.isRealtime)
 
+// The FinalizingIndexes phase is the transition a held process waits on: it
+// ends with `ready_at` committed and the indexer realtime.
+let shouldFinalizeIndexes = (state: t) =>
+  state->isFinalizingIndexes && !(state.crossChainState->CrossChainState.isHoldingRealtime)
+
 let markCaughtUpIfSettled = (state: t) =>
   state.crossChainState->CrossChainState.markCaughtUpIfSettled
 
+let isReadyToEnterReorgThreshold = (state: t, ~batch) =>
+  state.crossChainState->CrossChainState.isReadyToEnterReorgThreshold(~batch)
+
+let bindScheduleProcessing = (state: t, scheduleProcessing) =>
+  state.scheduleProcessing = scheduleProcessing
+
+// A process still waiting on its supervisor owes the schema the indexes its
+// chains deferred, so reaching every end block doesn't make it done.
+let isHoldingRealtime = (state: t) => state.crossChainState->CrossChainState.isHoldingRealtime
+
+let hasArrivedAtHead = (state: t) => state.crossChainState->CrossChainState.hasArrivedAtHead
+
+let releaseRealtime = (state: t) => {
+  state.crossChainState->CrossChainState.releaseRealtime
+  // Every chain is parked at the head with no batch coming, so nothing would
+  // notice the hold is gone without a pass through processing.
+  state.scheduleProcessing()
+}
+
 let markReady = (state: t, ~readyAt) => state.crossChainState->CrossChainState.markReady(~readyAt)
 
 let rollbackState = (state: t) => state.rollbackState
@@ -572,6 +611,7 @@ let toMetrics = (state: t): Metrics.t => {
     elapsedSeconds: state.indexerStartTimeRef->Performance.secondsSince,
     targetBufferSize: state.crossChainState->CrossChainState.targetBufferSize,
     isInReorgThreshold: state.crossChainState->CrossChainState.isInReorgThreshold,
+    hasArrivedAtHead: state.crossChainState->CrossChainState.hasArrivedAtHead,
     rollbackEnabled: state.config.shouldRollbackOnReorg,
     maxBatchSize: state.config.batchSize,
     preloadSeconds: state.preloadSeconds,

package/src/IndexerState.res.mjs

@@ -24,8 +24,9 @@ import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js
 import * as CheckpointSequence from "./db/CheckpointSequence.res.mjs";
 import * as SimulateDeadInputTracker from "./SimulateDeadInputTracker.res.mjs";
 
-function make(config, persistence, chainStates, isRealtime, targetBufferSizeOpt, committedFrontierOpt, isDevelopmentModeOpt, shouldUseTuiOpt, exitAfterFirstEventBlockOpt, onError, onExit) {
+function make(config, persistence, chainStates, isRealtime, targetBufferSizeOpt, holdRealtimeOpt, committedFrontierOpt, isDevelopmentModeOpt, shouldUseTuiOpt, exitAfterFirstEventBlockOpt, onError, onExit) {
   let targetBufferSize = targetBufferSizeOpt !== undefined ? targetBufferSizeOpt : CrossChainState.calculateTargetBufferSize();
+  let holdRealtime = holdRealtimeOpt !== undefined ? holdRealtimeOpt : false;
   let committedFrontier = committedFrontierOpt !== undefined ? committedFrontierOpt : Frontier.empty();
   let isDevelopmentMode = isDevelopmentModeOpt !== undefined ? isDevelopmentModeOpt : false;
   let shouldUseTui = shouldUseTuiOpt !== undefined ? shouldUseTuiOpt : false;
@@ -54,7 +55,7 @@ function make(config, persistence, chainStates, isRealtime, targetBufferSizeOpt,
     chainMetaDirty: false,
     chainMetaThrottler: chainMetaThrottler,
     isProcessing: false,
-    crossChainState: CrossChainState.make(chainStates, isRealtime, targetBufferSize),
+    crossChainState: CrossChainState.make(chainStates, isRealtime, targetBufferSize, holdRealtime),
     rollbackState: "NoRollback",
     indexerStartTime: new Date(),
     indexerStartTimeRef: Performance.now(),
@@ -66,6 +67,7 @@ function make(config, persistence, chainStates, isRealtime, targetBufferSizeOpt,
     onExit: onExit,
     isStopped: false,
     epoch: 0,
+    scheduleProcessing: () => {},
     simulateDeadInputTracker: SimulateDeadInputTracker.makeFromConfig(config),
     preloadSeconds: 0,
     processingSeconds: 0,
@@ -82,11 +84,12 @@ function make(config, persistence, chainStates, isRealtime, targetBufferSizeOpt,
   };
 }
 
-function makeFromDbState(config, persistence, initialState, registrationsByChainId, isDevelopmentModeOpt, shouldUseTuiOpt, exitAfterFirstEventBlockOpt, reducedPollingInterval, targetBufferSizeOpt, onError, onExit) {
+function makeFromDbState(config, persistence, initialState, registrationsByChainId, isDevelopmentModeOpt, shouldUseTuiOpt, exitAfterFirstEventBlockOpt, reducedPollingInterval, targetBufferSizeOpt, holdRealtimeOpt, onError, onExit) {
   let isDevelopmentMode = isDevelopmentModeOpt !== undefined ? isDevelopmentModeOpt : false;
   let shouldUseTui = shouldUseTuiOpt !== undefined ? shouldUseTuiOpt : false;
   let exitAfterFirstEventBlock = exitAfterFirstEventBlockOpt !== undefined ? exitAfterFirstEventBlockOpt : false;
   let targetBufferSize = targetBufferSizeOpt !== undefined ? targetBufferSizeOpt : CrossChainState.calculateTargetBufferSize();
+  let holdRealtime = holdRealtimeOpt !== undefined ? holdRealtimeOpt : false;
   let isInReorgThreshold = initialState.cleanRun ? false : initialState.chains.some(resumedChainState => {
       let progressBlockNumber = resumedChainState.progressBlockNumber;
       let sourceBlockNumber = resumedChainState.sourceBlockNumber;
@@ -104,7 +107,7 @@ function makeFromDbState(config, persistence, initialState, registrationsByChain
     let chainConfig = ChainMap.get(config.chainMap, chainId);
     chainStates[resumedChainState.id] = ChainState.makeFromDbState(chainConfig, resumedChainState, initialState.reorgCheckpoints, isInReorgThreshold, isRealtime, config, initialState.contractMapping, registrationsByChainId, reducedPollingInterval);
   });
-  let state = make(config, persistence, chainStates, isRealtime, targetBufferSize, initialState.checkpointFrontier, isDevelopmentMode, shouldUseTui, exitAfterFirstEventBlock, onError, onExit);
+  let state = make(config, persistence, chainStates, isRealtime, targetBufferSize, holdRealtime, initialState.checkpointFrontier, isDevelopmentMode, shouldUseTui, exitAfterFirstEventBlock, onError, onExit);
   CrossChainState.markCaughtUpOnResume(state.crossChainState);
   Utils.Dict.forEach(initialState.cache, param => {
     let count = param.count;
@@ -350,10 +353,39 @@ function isFinalizingIndexes(state) {
   }
 }
 
+function shouldFinalizeIndexes(state) {
+  if (isFinalizingIndexes(state)) {
+    return !CrossChainState.isHoldingRealtime(state.crossChainState);
+  } else {
+    return false;
+  }
+}
+
 function markCaughtUpIfSettled(state) {
   CrossChainState.markCaughtUpIfSettled(state.crossChainState);
 }
 
+function isReadyToEnterReorgThreshold(state, batch) {
+  return CrossChainState.isReadyToEnterReorgThreshold(state.crossChainState, batch);
+}
+
+function bindScheduleProcessing(state, scheduleProcessing) {
+  state.scheduleProcessing = scheduleProcessing;
+}
+
+function isHoldingRealtime(state) {
+  return CrossChainState.isHoldingRealtime(state.crossChainState);
+}
+
+function hasArrivedAtHead(state) {
+  return CrossChainState.hasArrivedAtHead(state.crossChainState);
+}
+
+function releaseRealtime(state) {
+  CrossChainState.releaseRealtime(state.crossChainState);
+  state.scheduleProcessing();
+}
+
 function markReady(state, readyAt) {
   CrossChainState.markReady(state.crossChainState, readyAt);
 }
@@ -447,6 +479,7 @@ function toMetrics(state) {
     elapsedSeconds: Performance.secondsSince(state.indexerStartTimeRef),
     targetBufferSize: CrossChainState.targetBufferSize(state.crossChainState),
     isInReorgThreshold: CrossChainState.isInReorgThreshold(state.crossChainState),
+    hasArrivedAtHead: CrossChainState.hasArrivedAtHead(state.crossChainState),
     rollbackEnabled: state.config.shouldRollbackOnReorg,
     maxBatchSize: state.config.batchSize,
     preloadSeconds: state.preloadSeconds,
@@ -844,6 +877,12 @@ export {
   isRealtime,
   isFinalizingIndexes,
   markCaughtUpIfSettled,
+  isReadyToEnterReorgThreshold,
+  shouldFinalizeIndexes,
+  bindScheduleProcessing,
+  isHoldingRealtime,
+  hasArrivedAtHead,
+  releaseRealtime,
   markReady,
   rollbackState,
   indexerStartTime,

package/src/IndexerState.resi

@@ -16,6 +16,7 @@ let make: (
   ~chainStates: dict<ChainState.t>,
   ~isRealtime: bool,
   ~targetBufferSize: int=?,
+  ~holdRealtime: bool=?,
   ~committedFrontier: Frontier.t=?,
   ~isDevelopmentMode: bool=?,
   ~shouldUseTui: bool=?,
@@ -34,6 +35,7 @@ let makeFromDbState: (
   ~exitAfterFirstEventBlock: bool=?,
   ~reducedPollingInterval: int=?,
   ~targetBufferSize: int=?,
+  ~holdRealtime: bool=?,
   ~onError: ErrorHandling.t => unit,
   ~onExit: unit => unit=?,
 ) => t
@@ -93,6 +95,14 @@ let shouldSaveHistory: t => dict<bool>
 let isRealtime: t => bool
 let isFinalizingIndexes: t => bool
 let markCaughtUpIfSettled: t => unit
+let isReadyToEnterReorgThreshold: (t, ~batch: Batch.t) => bool
+let shouldFinalizeIndexes: t => bool
+// Wires the loop's way back in. IndexerLoop calls this as it starts.
+let bindScheduleProcessing: (t, unit => unit) => unit
+let isHoldingRealtime: t => bool
+let hasArrivedAtHead: t => bool
+// The supervisor's go-ahead for a process driving part of a split run.
+let releaseRealtime: t => unit
 let markReady: (t, ~readyAt: Date.t) => unit
 let rollbackState: t => rollbackState
 let indexerStartTime: t => Date.t

package/src/Logging.res

@@ -26,6 +26,30 @@ let logLevels = [
 
 %%private(let logger = ref(None))
 
+// Fields every line this process logs carries. Merged into each line rather
+// than bound to a child logger: pino writes a child's bindings and the line's
+// own fields side by side, so a line that names the same key would carry it
+// twice. A fresh object per line, since pino merges the line's fields into
+// whatever this returns.
+%%private(let context: ref<dict<JSON.t>> = ref(Dict.make()))
+%%private(let mixin = () => JSON.Object(context.contents->Dict.copy))
+
+// A child logger that binds a field the process already carries would have pino
+// write it twice: a child's bindings and the context are concatenated into the
+// line, not merged. The context is the one place a line names it, which it can
+// be because a process only takes one when its every line is about that chain.
+%%private(
+  let withoutContext = (params: 'a) =>
+    switch context.contents->Dict.keysToArray {
+    | [] => params
+    | keys => {
+        let narrowed = params->(Utils.magic: 'a => dict<JSON.t>)->Dict.copy
+        keys->Array.forEach(key => narrowed->Dict.delete(key))
+        narrowed->(Utils.magic: dict<JSON.t> => 'a)
+      }
+    }
+)
+
 let makeLogger = (~logStrategy, ~logFilePath, ~defaultFileLogLevel, ~userLogLevel) => {
   // Currently unused - useful if using multiple transports.
   // let pinoRaw = {"target": "pino/file", "level": Config.userLogLevel}
@@ -56,17 +80,19 @@ let makeLogger = (~logStrategy, ~logFilePath, ~defaultFileLogLevel, ~userLogLeve
         ...Pino.ECS.make(),
         customLevels: logLevels,
         base,
+        mixin,
       },
       Transport.make(pinoFile),
     )
   | EcsConsoleMultistream =>
-    makeMultiStreamLogger(~logFile=None, ~options=Some({...Pino.ECS.make(), base}))
+    makeMultiStreamLogger(~logFile=None, ~options=Some({...Pino.ECS.make(), base, mixin}))
   | EcsConsole =>
     make({
       ...Pino.ECS.make(),
       level: userLogLevel,
       customLevels: logLevels,
       base,
+      mixin,
     })
   | FileOnly =>
     makeWithOptionsAndTransport(
@@ -74,12 +100,13 @@ let makeLogger = (~logStrategy, ~logFilePath, ~defaultFileLogLevel, ~userLogLeve
         customLevels: logLevels,
         level: defaultFileLogLevel,
         base,
+        mixin,
       },
       Transport.make(pinoFile),
     )
-  | ConsoleRaw => makeMultiStreamLogger(~logFile=None, ~options=Some({base: base}))
-  | ConsolePretty => makeMultiStreamLogger(~logFile=None, ~options=Some({base: base}))
-  | Both => makeMultiStreamLogger(~logFile=Some(logFilePath), ~options=Some({base: base}))
+  | ConsoleRaw => makeMultiStreamLogger(~logFile=None, ~options=Some({base, mixin}))
+  | ConsolePretty => makeMultiStreamLogger(~logFile=None, ~options=Some({base, mixin}))
+  | Both => makeMultiStreamLogger(~logFile=Some(logFilePath), ~options=Some({base, mixin}))
   }
 }
 
@@ -149,10 +176,15 @@ let childFatal = (logger, params: 'a) => {
 }
 
 let createChild = (~params: 'a) => {
-  getLogger()->child(params->createChildParams)
+  getLogger()->child(params->withoutContext->createChildParams)
 }
+
+// What belongs on every line is the run's to decide; the logger only carries
+// what it is handed. A line that names one of these fields itself wins.
+let setContext = (fields: dict<JSON.t>) => context := fields
+
 let createChildFrom = (~logger: t, ~params: 'a) => {
-  logger->child(params->createChildParams)
+  logger->child(params->withoutContext->createChildParams)
 }
 
 @inline

package/src/Logging.res.mjs

@@ -3,6 +3,7 @@
 import * as Pino from "./bindings/Pino.res.mjs";
 import * as Pino$1 from "pino";
 import * as Utils from "./Utils.res.mjs";
+import * as Stdlib_Dict from "@rescript/runtime/lib/es6/Stdlib_Dict.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 
@@ -53,6 +54,24 @@ let logger = {
   contents: undefined
 };
 
+let context = {
+  contents: {}
+};
+
+function mixin() {
+  return Object.assign({}, context.contents);
+}
+
+function withoutContext(params) {
+  let keys = Object.keys(context.contents);
+  if (keys.length === 0) {
+    return params;
+  }
+  let narrowed = Object.assign({}, params);
+  keys.forEach(key => Stdlib_Dict.$$delete(narrowed, key));
+  return narrowed;
+}
+
 function makeLogger(logStrategy, logFilePath, defaultFileLogLevel, userLogLevel) {
   let pinoFile_target = "pino/file";
   let pinoFile_options = Primitive_option.some(Pino.Transport.makeTransportOptions({
@@ -71,17 +90,18 @@ function makeLogger(logStrategy, logFilePath, defaultFileLogLevel, userLogLevel)
   switch (logStrategy) {
     case "ecs-file" :
       let newrecord = {...Pino.ECS.make()};
-      return Pino$1.pino((newrecord.base = base, newrecord.customLevels = logLevels, newrecord), Pino$1.transport(pinoFile));
+      return Pino$1.pino((newrecord.base = base, newrecord.mixin = mixin, newrecord.customLevels = logLevels, newrecord), Pino$1.transport(pinoFile));
     case "ecs-console" :
       let newrecord$1 = {...Pino.ECS.make()};
-      return Pino$1.pino((newrecord$1.base = base, newrecord$1.customLevels = logLevels, newrecord$1.level = userLogLevel, newrecord$1));
+      return Pino$1.pino((newrecord$1.base = base, newrecord$1.mixin = mixin, newrecord$1.customLevels = logLevels, newrecord$1.level = userLogLevel, newrecord$1));
     case "ecs-console-multistream" :
       let newrecord$2 = {...Pino.ECS.make()};
-      return makeMultiStreamLogger(undefined, (newrecord$2.base = base, newrecord$2));
+      return makeMultiStreamLogger(undefined, (newrecord$2.base = base, newrecord$2.mixin = mixin, newrecord$2));
     case "file-only" :
       return Pino$1.pino({
         level: defaultFileLogLevel,
         customLevels: logLevels,
+        mixin: mixin,
         base: base
       }, Pino$1.transport(pinoFile));
     case "console-raw" :
@@ -89,10 +109,12 @@ function makeLogger(logStrategy, logFilePath, defaultFileLogLevel, userLogLevel)
       break;
     case "both-prettyconsole" :
       return makeMultiStreamLogger(logFilePath, {
+        mixin: mixin,
         base: base
       });
   }
   return makeMultiStreamLogger(undefined, {
+    mixin: mixin,
     base: base
   });
 }
@@ -171,11 +193,15 @@ function childFatal(logger, params) {
 }
 
 function createChild(params) {
-  return getLogger().child(Pino.createChildParams(params));
+  return getLogger().child(Pino.createChildParams(withoutContext(params)));
+}
+
+function setContext(fields) {
+  context.contents = fields;
 }
 
 function createChildFrom(logger, params) {
-  return logger.child(Pino.createChildParams(params));
+  return logger.child(Pino.createChildParams(withoutContext(params)));
 }
 
 function logAtLevel(logger, level, message, params) {
@@ -246,6 +272,7 @@ export {
   childErrorWithExn,
   childFatal,
   createChild,
+  setContext,
   createChildFrom,
   logAtLevel,
   noopLogger,