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

[Ethan-Arrowood]

Problem

reference/configuration/options.md told readers to set threads.preload: dd-trace/register.js on the grounds that it "registers the loader hooks that instrument worker threads" while "the plain dd-trace/init (--require) entry only covers the main thread." Following that produces zero telemetry, with no error anywhere.

Measured by the reporter on dd-trace 6.10.0 / Harper 5.2.1 / Node v24.16.0 against a live trace receiver:

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

I confirmed the mechanism directly against the published dd-trace 6.10.0 sources: register.js is 65 lines that register('./loader-hook.mjs', ...) (or the sync equivalent) and never require dd-trace or call init(); init.js is module.exports = guard(function () { return require('.').init() }). The two entries do different jobs and neither substitutes for the other. The failure is silent because an uninitialised dd-trace still returns spans with plausible trace ids - they are NoopSpans.

Change

• preload bullet: register.js installs the ESM loader hooks for automatic instrumentation; as measured on dd-trace 6.x it never calls init(), so preload alone leaves the tracer uninitialized and inert. Points at preloadRequire: dd-trace/init as the entry that starts the tracer. Scoped to 6.x rather than stated as a timeless fact, since a future dd-trace major could change register.js.
• dd-trace example now shows both keys with inline comments.
• preloadRequire bullet cross-references back to preload, so a reader landing on either sees the pairing. Dropped "and do not need ESM loader hooks", which implied dd-trace/init is sufficient on its own.

Everything the bullets already got right is preserved: bare-specifier resolution against component node_modules, absolute paths accepted, worker threads only, not under Bun.

Verification

• npm run format:write / npm run format:check clean.
• npm run build succeeds. The two broken-anchor warnings it prints (/reference/v5/backups/overview and /release-notes/v5-lincoln/5.1) are pre-existing and unrelated.

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.