From 8232c9a044c8a5830d97d77bb6ef25791239b794 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Thu, 2 Jul 2026 07:19:56 -0600 Subject: [PATCH 1/2] Document threads.preload config option MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds threads.preload to the configuration reference — preloads modules (e.g. dd-trace) via --require on worker threads before any Harper or app module, for APM/instrumentation agents. Ships in harper v5.2.0. Co-Authored-By: Claude Opus 4.8 --- reference/configuration/options.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/reference/configuration/options.md b/reference/configuration/options.md index 99d318e5..5cbb6c89 100644 --- a/reference/configuration/options.md +++ b/reference/configuration/options.md @@ -65,6 +65,16 @@ threads: - `maxHeapMemory` — Heap limit per thread (MB) - `heapSnapshotNearLimit` — Write a `.heapsnapshot` file when a thread nears its heap limit (loadable in Chrome DevTools Memory tab); _Default_: `false`. See [Worker Thread Debugging](./debugging.md#heap-snapshots-near-the-limit) - `debug` — Enable Node.js inspector; sub-options: `port`, `startingPort`, `host`, `waitForDebugger`. See [Worker Thread Debugging](./debugging.md) +- `preload` — Module, or list of modules, to load (via Node's `--require`) before any Harper or application module on each worker thread. Intended for instrumentation/APM agents (e.g. `dd-trace`) that must load first to instrument subsequent module loads. Bare specifiers (e.g. `dd-trace/init`) resolve against the `node_modules` of your installed [components](../components/overview.md) — so the agent can be shipped as a dependency of a deployed component — and absolute paths are also accepted. Applies to worker threads only (not under Bun). + +```yaml +threads: + preload: dd-trace/init + # or several: + # preload: + # - dd-trace/init + # - /opt/instrumentation/agent.js +``` --- From 6df4f08975535762915db35a60111c850fca81c1 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Thu, 2 Jul 2026 08:22:08 -0600 Subject: [PATCH 2/2] Split threads.preload YAML into single- and multi-module examples Avoids a duplicate 'preload' key in one block (would be invalid YAML if the commented lines were uncommented). Addresses docs review. Co-Authored-By: Claude Opus 4.8 --- reference/configuration/options.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/reference/configuration/options.md b/reference/configuration/options.md index 5cbb6c89..bb6d6552 100644 --- a/reference/configuration/options.md +++ b/reference/configuration/options.md @@ -70,10 +70,15 @@ threads: ```yaml threads: preload: dd-trace/init - # or several: - # preload: - # - dd-trace/init - # - /opt/instrumentation/agent.js +``` + +Or several modules: + +```yaml +threads: + preload: + - dd-trace/init + - /opt/instrumentation/agent.js ``` ---