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.

[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.