docs(configuration): pair threads.preload with preloadRequire for dd-trace

[Ethan-Arrowood]

Problem

reference/configuration/options.md presented a specific dd-trace configuration as the way to instrument Harper worker threads: set threads.preload: dd-trace/register.js because it "registers the loader hooks that instrument worker threads" while "the plain dd-trace/init (--require) entry only covers the main thread."

Two things are wrong with that. First, on dd-trace 6.x register.js never calls init() - it registers the ESM loader hooks and nothing else - so preload on its own leaves the tracer uninitialized. The failure is silent, because an uninitialised dd-trace still hands out spans with plausible trace ids; they are NoopSpans. Second, and more fundamentally, the page was presenting a vendor recipe as though Harper had validated it end to end, which it has not.

Context from the reporter on #625 (dd-trace 6.10.0 / Harper 5.2.1 / Node v24.16.0, against their own trace receiver - their measurement, not a Harper validation):

Worker flags	tracerInitialized	Spans received
neither	false	none
--import dd-trace/register.js only (threads.preload)	false	none
--require dd-trace/init (threads.preloadRequire)	true	all four

Change

Rather than build a Harper end-to-end APM validation for this, the guidance is now agent-neutral and dd-trace is described as unverified (see this thread).

• Both bullets now explain the general mechanism: preload uses Node's --import, so it is the key for an agent's ESM/register entry (the one installing module loader hooks); preloadRequire uses --require, so it is the key for an agent's initialization entry (it runs the module body). Which of an agent's entry points does which is agent-specific - some ship one entry that does both, others split them - so readers are pointed at their agent's own docs and told to verify end to end against their collector.
• dd-trace remains as an illustration of the split-entry case, behind an explicit warning that the values are not a Harper-validated APM configuration; that the specifics are only what dd-trace's own entry points do, observed by reading dd-trace 6.x; and that Harper has not been validated to produce exported spans with usable trace context and clean shutdown under this configuration.
• The pairing detail is kept, scoped as a dd-trace observation rather than a certified recipe: register.js does not call init(), init does, and initialize.mjs is not a single-entry shortcut because it gates both its init() call and its loader-hook registration behind isMainThread.
• Both dd-trace examples on the page (single-module and multi-module) carry the same framing and the same inline comments.

Everything mechanically true about Harper is preserved: bare-specifier resolution against installed components' node_modules, absolute paths accepted, worker threads only, not under Bun. The <VersionBadge version="v5.2.0" /> on both bullets is unchanged.

Verification

• Rebased onto current origin/main.
• npm run format:write / npm run format:check clean.
• npm run build succeeds with zero broken-anchor warnings.

Closes #625

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request updates the documentation in reference/configuration/options.md to clarify the usage of the preload and preloadRequire configuration options, specifically explaining how to pair them together when using dd-trace to ensure the tracer is both registered and initialized. The reviewer provided feedback to replace em dashes with hyphens as field separators and to use plain text inline version annotations instead of the <VersionBadge> component, in accordance with Markdown documentation style guidelines.

[gemini-code-assist]

According to the general rules, we should use hyphens (-) instead of em dashes (—) as field separators (e.g., separating configuration option names from their descriptions) in Markdown documentation. Additionally, the <VersionBadge> component should be reserved for standalone placement after headings; for inline version annotations inside list items, plain text like (v5.2.0) should be used instead.

Suggested change

- `preload` <VersionBadge version="v5.2.0" /> — Module, or list of modules, to load (via Node's `--import`) before any Harper or application module on each worker thread. Intended for instrumentation/APM agents that must load first to instrument subsequent module loads. Use the agent's ESM/register entry — e.g. `dd-trace/register.js`, which installs the ESM loader hooks that produce automatic instrumentation for `import`-loaded modules. As measured on dd-trace 6.x, that entry only registers the loader hooks and never calls `init()`, so `preload` on its own leaves the tracer uninitialized: it still hands out spans with plausible trace ids, but they are no-ops and nothing is ever exported. Pair it with `preloadRequire: dd-trace/init`, which is the entry that actually starts the tracer. Bare specifiers 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).

- `preload` (v5.2.0) - Module, or list of modules, to load (via Node's `--import`) before any Harper or application module on each worker thread. Intended for instrumentation/APM agents that must load first to instrument subsequent module loads. Use the agent's ESM/register entry — e.g. `dd-trace/register.js`, which installs the ESM loader hooks that produce automatic instrumentation for `import`-loaded modules. As measured on dd-trace 6.x, that entry only registers the loader hooks and never calls `init()`, so `preload` on its own leaves the tracer uninitialized: it still hands out spans with plausible trace ids, but they are no-ops and nothing is ever exported. Pair it with `preloadRequire: dd-trace/init`, which is the entry that actually starts the tracer. Bare specifiers 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).

References

1. In Markdown documentation, use hyphens ('-') instead of em dashes ('—') as field separators (e.g., separating configuration option names from their descriptions) to adhere to the style guide, even if the file has pre-existing inconsistencies using em dashes.
2. Reserve the component for standalone placement after headings. For inline version annotations mid-sentence or inside list items, use plain text (e.g., (vX.Y.Z)) instead, as using the component mid-sentence is awkward.

[Ethan-Arrowood]

Not taking this one. The em-dash rule is being over-generalized here.

AGENTS.md says em dashes "are fine for parenthetical asides and match existing prose; do not use them as field separators." The field-separator prohibition refers to the bullet immediately above it - Type: / Default: reference blocks, where each field goes on its own line. It is not a ban on - **term** — description in prose lists.

Two checks: the docs tree has 633 em-dash list-item lines across 63 reference files, and AGENTS.md itself uses this exact pattern - including in the rule being quoted (- **Hyphens vs. dashes** — em dashes...).

So these are the established convention, not "pre-existing inconsistencies." Applying the suggestion would leave the touched lines inconsistent with every sibling line in the same list.

_{sent with Claude Opus 5}

[gemini-code-assist]

According to the general rules, we should use hyphens (-) instead of em dashes (—) as field separators (e.g., separating configuration option names from their descriptions) in Markdown documentation. Additionally, the <VersionBadge> component should be reserved for standalone placement after headings; for inline version annotations inside list items, plain text like (v5.2.0) should be used instead.

Suggested change

- `preloadRequire` <VersionBadge version="v5.2.0" /> — Same as `preload`, but loads modules via Node's `--require` (CommonJS) instead of `--import`. Use this for agents that document the `--require` path (e.g. `dd-trace/init`, Dynatrace OneAgent). Same resolution rules as `preload`. For dd-trace, `dd-trace/init` is the entry that starts the tracer, and it does not register the ESM loader hooks — keep `preload: dd-trace/register.js` alongside it, as shown under `preload` above.

- `preloadRequire` (v5.2.0) - Same as `preload`, but loads modules via Node's `--require` (CommonJS) instead of `--import`. Use this for agents that document the `--require` path (e.g. `dd-trace/init`, Dynatrace OneAgent). Same resolution rules as `preload`. For dd-trace, `dd-trace/init` is the entry that starts the tracer, and it does not register the ESM loader hooks — keep `preload: dd-trace/register.js` alongside it, as shown under `preload` above.

References

1. In Markdown documentation, use hyphens ('-') instead of em dashes ('—') as field separators (e.g., separating configuration option names from their descriptions) to adhere to the style guide, even if the file has pre-existing inconsistencies using em dashes.
2. Reserve the component for standalone placement after headings. For inline version annotations mid-sentence or inside list items, use plain text (e.g., (vX.Y.Z)) instead, as using the component mid-sentence is awkward.

[Ethan-Arrowood]

Not taking this one. The em-dash rule is being over-generalized here.

AGENTS.md says em dashes "are fine for parenthetical asides and match existing prose; do not use them as field separators." The field-separator prohibition refers to the bullet immediately above it - Type: / Default: reference blocks, where each field goes on its own line. It is not a ban on - **term** — description in prose lists.

Two checks: the docs tree has 633 em-dash list-item lines across 63 reference files, and AGENTS.md itself uses this exact pattern - including in the rule being quoted (- **Hyphens vs. dashes** — em dashes...).

So these are the established convention, not "pre-existing inconsistencies." Applying the suggestion would leave the touched lines inconsistent with every sibling line in the same list.

_{sent with Claude Opus 5}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-644

This preview will update automatically when you push new commits.

[kriszyp]

We are putting a lot of emphasis on datadog here, and I was kind of under the impression that we didn't really know if datadog even worked very well under this configuration. Do you know if it did or not?
_{🤖 Reviewed with Codex}

[kriszyp]

This still presents a directly copyable dd-trace configuration with only preload, but the new text establishes that dd-trace/register.js does not call init(). Adding an instrumentation module to this example therefore leaves each worker's tracer uninitialized and exports no traces—the silent failure this PR is fixing. Add preloadRequire: dd-trace/init to this example too (or use dd-trace/initialize.mjs as the single preload) so every shown dd-trace configuration is viable.

_{(reference/configuration/options.md:81 is not part of this PR's diff — anchored to the nearest line this PR's diff can hold)}

[Ethan-Arrowood]

Good catch — fixed. The multi-module example now carries preloadRequire: dd-trace/init alongside the preload list, so every dd-trace configuration shown on the page is viable.

I did chase down initialize.mjs, and it is not the simpler single entry it looks like: on 6.x it gates both its init() call and its Module.register('./loader-hook.mjs') behind isMainThread, and its exported load/resolve hooks only take effect when the file is passed to --loader. Since we preload with --import in the worker's execArgv, that means it starts nothing and registers nothing on a worker thread — I confirmed it on dd-trace 6.12.0 / Node 24.19.0, where the worker's tracer stays a NoopTracer, i.e. the same silent failure as register.js alone, minus the loader hooks.

So I've stuck with the two-key pairing and added a line to the preload bullet recording why initialize.mjs isn't a shortcut around it, so the next person doesn't reach for it either.

_{sent with Claude Opus 5}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-644

This preview will update automatically when you push new commits.

[kriszyp]

Ok, I guess if we feel adequately confident that datadog really does work like this (again, I haven't verified), we can stick with these examples.
_{🤖 Reviewed with Codex}

[kriszyp]

Could we confirm this as an end-to-end Harper worker setup before documenting it as the dd-trace recipe? register.js installing loader hooks and init starting the tracer does not establish that Harper's actual worker execArgv composition produces exported spans with usable context and shutdown behavior. Please add a reproducible Harper validation (for example, a component emitting a known trace to a test agent) and summarize or link its scope/result; otherwise keep this guidance agent-neutral and describe dd-trace as unverified.

[Ethan-Arrowood]

Fair distinction, and I'm taking the second branch rather than standing up a Harper end-to-end validation for this. Both bullets now describe only the general mechanism - preload is Node's --import (ESM, loader hooks), preloadRequire is --require (CommonJS, runs the module body) - and note that which of an agent's entry points does which is agent-specific. dd-trace stays as an illustration of the split-entry case, but behind an explicit warning that the values are not a Harper-validated APM configuration, that the specifics are only what dd-trace's own entries do as observed in 6.x, and that readers must confirm the spans they expect actually arrive at their own collector.

_{sent with Claude Opus 5}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-644

This preview will update automatically when you push new commits.

[kriszyp]

Looks good
_{🤖 Reviewed with Codex}

[dawsontoth]

Nit: these sentences are really long, and given in the context of a bullet list. I have a hard time forcing myself to read it, and I'm getting paid to do so. Instead, whetting someone's appetite to what it can do, and then linking them to a purpose built page for how to preload stuff with examples, code snippets, that kind of thing... that'd make this a lot easier to consume.

I'd be comfortable if we said "oh Dawson" and saved a GH issue to try to shift things to "show more than you tell" over time. Or if you want to tackle this paragraph, that's cool too. Meh.

[dawsontoth]

I know this is the result of saying "did we really verify our dd integration?" but this reads to me as "we didn't bother to verify", which feels way worse... particularly when this will be a deciding factor for some companies with observability tied to Datadog.