@deliciousmonster/datadog-agent-binary 7.82.1-next.0

package/resources.js

@@ -0,0 +1,288 @@
+// handleApplication(scope) is the only path that starts an agent, reachable only when a component's own
+// config.yaml carries `pluginModule` beside `jsResource`. This is also the only file Harper compiles, so `spawn` and the compartment globals are read here and passed down: a helper importing them itself may get the unconstrained ones.
+
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { basename } from "node:path";
+import { threadId } from "node:worker_threads";
+
+import { PACKAGE_NAME, resolveBinary } from "./runtime/binary.js";
+import { prepareRuntime as prepare } from "./runtime/config.js";
+import {
+	debugVarsUrl,
+	readDeliverySignal as readSignal,
+} from "./runtime/delivery.js";
+import { untraceAgentProbes } from "./runtime/probe.js";
+import { supervisorFor, unstarted } from "./runtime/supervisor.js";
+import {
+	currentVerdict,
+	expvarUrl,
+	receiverInfoUrl,
+	verifyLaunch,
+} from "./runtime/verify.js";
+
+/** Harper seeds every component compartment with `logger` and `Resource`; stubs keep the module importable in tests. */
+const host = typeof logger === "undefined" ? console : logger;
+const ResourceBase = typeof Resource === "undefined" ? class {} : Resource;
+
+// Every method on Harper's Logger is declared optional. Normalised once here rather than defended per call,
+// because the guard calls ctx.log.info and ctx.log.warn unguarded after it has committed an agent's lock.
+const channel =
+	(...names) =>
+	(message) =>
+		(
+			names
+				.map((name) => host[name])
+				.find((write) => typeof write === "function") ?? console.log
+		).call(host, message);
+const log = {
+	info: channel("info", "warn"),
+	warn: channel("warn", "info"),
+	error: channel("error", "warn"),
+};
+
+/** Both agents read these variables, so an unparseable value must not be quietly reinterpreted. */
+function resolvePort(name, fallback) {
+	const raw = process.env[name];
+	if (!raw) return fallback;
+	const trimmed = raw.trim();
+	if (trimmed === "0") return 0; // upstream's spelling for "serve no endpoint here"
+	// Whole-string, because parseInt reads "8126tcp" as 8126 and hands back a port nobody wrote.
+	const parsed = /^\d{1,5}$/.test(trimmed) ? Number(trimmed) : Number.NaN;
+	if (parsed >= 1 && parsed <= 65535) return parsed;
+	log.warn(
+		`Datadog supervisor: ${name}="${raw}" is not a port in 1-65535. Using ${fallback}.`
+	);
+	return fallback;
+}
+
+// Read once per module instance, because every worker thread renders the config and probes the endpoints
+// from the same three numbers and a second reading could disagree with the first.
+const ports = {
+	receiver: resolvePort("DD_APM_RECEIVER_PORT", 8126),
+	expvar: resolvePort("DD_EXPVAR_PORT", 5000),
+	debug: resolvePort("DD_APM_DEBUG_PORT", 5012),
+};
+
+// Every URL this module polls. probe.js already suppresses these at the call site; this is the public half,
+// and it only holds until some other caller reconfigures the same plugins.
+const PROBE_URLS = [
+	receiverInfoUrl(ports.receiver),
+	expvarUrl(ports.expvar),
+	debugVarsUrl(ports.debug),
+];
+
+// Resolved rather than imported: dd-trace belongs to the host application, and this package does not ship it.
+let tracer;
+try {
+	tracer = createRequire(import.meta.url)("dd-trace");
+} catch {
+	// No tracer in this process, so there is nothing to keep the probes out of.
+}
+if (tracer) {
+	try {
+		untraceAgentProbes(tracer, PROBE_URLS);
+	} catch (error) {
+		// A shape untraceAgentProbes did not expect from tracer.use(): unlike a missing require, this leaves
+		// the probes untraced, so it gets its own log line rather than sharing the silent path above.
+		log.error(
+			`Datadog supervisor: found dd-trace but could not configure it to ignore the agent probes: ${error.stack ?? error.message}. Probe requests may now appear as spans in APM.`
+		);
+	}
+}
+
+// `name` is Harper's spawn name and the PID-lock filename, stated once: a second spelling is a second lock
+// and a second agent per node. The trace-agent comes first because it owns the socket dd-trace is dialing.
+const AGENTS = [
+	{
+		kind: "trace",
+		name: "datadog-trace-agent",
+		title: "trace-agent",
+		shipsAs: "trace-agent",
+		// The trace-agent's `-c` takes the config FILE. Its own help text says directory and is wrong.
+		args: (paths) => ["run", "-c", paths.configFile],
+		exitHint: `An immediate non-zero exit from the trace-agent usually means something else already holds 127.0.0.1:${ports.receiver}.`,
+	},
+	{
+		kind: "core",
+		name: "datadog-agent",
+		title: "core agent",
+		shipsAs: "datadog-agent",
+		args: (paths) => ["run", "-c", paths.runtimeDir],
+	},
+];
+
+// The root-config entry Harper needs before it calls the plugin at all. The key is this directory's name,
+// because a root entry resolves to <componentsRoot>/<key>.
+const CONFIG_ENTRY = `${basename(import.meta.dirname)}: { package: "${PACKAGE_NAME}" }`;
+
+/** The runtime tree and the config files for this node, rendered against the ports this instance resolved. */
+export const prepareRuntime = () =>
+	prepare(import.meta.dirname, { ports, log });
+
+/** The trace-agent's delivery counters, off the debug port this instance rendered into datadog.yaml. */
+export const readDeliverySignal = (port = ports.debug) => readSignal(port);
+
+/** Never the value itself, so the status endpoint cannot become a second place the key leaks. */
+const apiKeyStatus = () => (process.env.DD_API_KEY ? "set" : "MISSING");
+
+/** Per worker thread, set by handleApplication; a request that beats it, or a thread that never ran it, reads NOT_STARTED. */
+let supervisor;
+
+/** The fields every status shape starts from, so NOT_STARTED and startAgents's own status object cannot drift apart. */
+const baseStatus = () => ({
+	receiverPort: ports.receiver,
+	apiKey: apiKeyStatus(),
+	processes: [],
+});
+
+const NOT_STARTED = {
+	...baseStatus(),
+	detail:
+		`nothing has started on this thread. Check first that the node's harper-config.yaml carries ` +
+		`\`${CONFIG_ENTRY}\`: Harper calls handleApplication only for a component the root config names, and ` +
+		`a directory it loaded by scanning componentsRoot never reaches it. Otherwise this thread has not ` +
+		`run startup yet, or it ran under a deploy validation load, which starts nothing`,
+};
+
+// Never rejects: a throw out of handleApplication plants an ErrorResource at the component's root path,
+// which is worse than running without telemetry and saying so.
+async function startAgents(scope) {
+	const supervisor = supervisorFor(scope, { log, spawn });
+	const status = {
+		supervision: supervisor.kind,
+		...baseStatus(),
+	};
+	try {
+		if (!process.env.DD_API_KEY) {
+			// Measured on 7.82.1 rather than inferred from one shared config: the two agents fail differently.
+			log.warn(
+				"Datadog supervisor: DD_API_KEY is not set. The core agent starts and collects, and the intake " +
+					"refuses every payload it sends with a 403. The trace-agent does not start at all: it exits " +
+					'immediately with "you must specify an API Key", so nothing binds the receiver, the supervisor ' +
+					"restarts it until it gives up, and dd-trace has nowhere to send spans."
+			);
+		}
+
+		const runtime = prepareRuntime();
+		Object.assign(status, {
+			runtimeDir: runtime.paths.runtimeDir,
+			configFile: runtime.paths.configFile,
+			coreChecks: runtime.coreChecks,
+		});
+
+		// Resolved up front so the fingerprint can never describe a different binary from the one spawned.
+		const failures = [];
+		const binaries = await Promise.all(
+			AGENTS.map((agent, index) =>
+				resolveBinary(agent).catch((error) => {
+					failures[index] = error.message;
+					log.error(
+						`Datadog supervisor: could not resolve the ${agent.title} binary: ${error.message}`
+					);
+					return "";
+				})
+			)
+		);
+
+		// The credentials ride in the inherited environment, invisible to the config contents, so a rotated
+		// key must be folded in here or a thread joins the agent still posting under the old one.
+		const fingerprintParts = [
+			...Object.values(runtime.configFiles),
+			process.env.DD_API_KEY ?? "",
+			process.env.DD_SITE ?? "",
+			process.env.DD_ENV ?? "",
+			...binaries,
+		];
+
+		const verifyContext = { paths: runtime.paths, ports };
+		const declared = AGENTS.map((agent, index) => ({
+			...agent,
+			command: binaries[index],
+			args: agent.args(runtime.paths),
+			verify: (state) => verifyLaunch(agent, state, verifyContext),
+		}));
+
+		// Reported here rather than inside a supervisor, so the two of them cannot describe the same
+		// unresolvable binary in different words.
+		const startable = declared.filter((agent) => agent.command);
+		const started = startable.length
+			? await supervisor.start(startable, {
+					runtime,
+					configFiles: runtime.configFiles,
+					fingerprintParts,
+				})
+			: { processes: [], report: [] };
+
+		const states = new Map(
+			startable.map((agent, index) => [agent.name, started.processes[index]])
+		);
+		status.processes = declared.map(
+			(agent, index) =>
+				states.get(agent.name) ?? unstarted(agent, failures[index])
+		);
+		if (started.reaper) status.reaper = started.reaper;
+		if (started.report?.length) status.supervisionReport = started.report;
+	} catch (error) {
+		status.error = error.message;
+		log.error(
+			`Datadog supervisor: startup failed: ${error.stack ?? error.message}`
+		);
+	}
+	return status;
+}
+
+// 60s because handleApplication runs behind scope.ready and waitForDeployCompletion, then behind a per-plugin
+// lock whose own wait is Harper's plugin timeout plus 5s: 35s at the 30s default. A shorter window libels a slow node.
+const START_DEADLINE_MS = 60_000;
+
+// The one failure this module cannot see from inside: Harper imports it for its resources and never calls
+// the plugin, which is what an auto-scanned component directory gets. Module evaluation is the only vantage point left.
+const startDeadline = setTimeout(() => {
+	log.error(
+		`Datadog supervisor: Harper has not called handleApplication ${START_DEADLINE_MS / 1000}s after this ` +
+			`module loaded, so no agent started and nothing on this node is supervising one. The likeliest ` +
+			`cause is a component Harper loaded by scanning componentsRoot: it calls the plugin only for a ` +
+			`component the root harper-config.yaml names, and the module it imports for a scanned directory ` +
+			`is discarded.`
+	);
+	log.error(
+		`Datadog supervisor: add this to the node's harper-config.yaml (the file settings_path names in ` +
+			`~/.harperdb/hdb_boot_properties.file), keyed by this directory's name, then restart Harper: ${CONFIG_ENTRY}`
+	);
+}, START_DEADLINE_MS);
+// A diagnostic must not be the reason a worker thread stays up.
+startDeadline.unref?.();
+
+/** Harper's plugin entry, once per worker thread, and the only path that starts anything. */
+export function handleApplication(scope) {
+	// Being called at all is what the deadline above waits for; a validation load counts, since Harper
+	// reached the plugin either way.
+	clearTimeout(startDeadline);
+	// A deploy pre-flight loads the component against a live node just to validate it; starting agents there
+	// re-enters the sweep and spawn path on every `harper deploy`.
+	if (scope?.isTransientValidation) return;
+	// The single-start guarantee: a second call joins the first promise rather than starting again.
+	supervisor ??= startAgents(scope);
+}
+
+/** GET /DatadogStatus/, the plugin's one REST resource, reports what startup did. Everything it reports fails silently by default, which is why it gets an endpoint. */
+export class DatadogStatus extends ResourceBase {
+	static async get() {
+		// The counters belong to the node's trace-agent, not to this thread, so they are read whether or not
+		// this thread is the one that started it.
+		const [status, delivery] = await Promise.all([
+			supervisor ?? NOT_STARTED,
+			readDeliverySignal(),
+		]);
+		return {
+			...status,
+			// Read here rather than copied at boot: a verdict the supervisor took before a restart describes
+			// a process this node no longer runs.
+			processes: status.processes.map(currentVerdict),
+			// Which thread answered; every field above it is per-thread state.
+			threadId,
+			delivery,
+		};
+	}
+}

package/runtime/agent-exit.js

@@ -0,0 +1,60 @@
+// One reading per way an agent can fail to run. "failed to execute" and a zero exit are the two that
+// mislead most, so each gets a sentence naming what actually happened rather than one shared line.
+
+import { constants } from "node:os";
+
+// Signals a supervisor sends on the way down. Anything else reaching a child is a crash or an OOM kill,
+// and a Go agent that never installed a handler exits with no code at all either way.
+const SHUTDOWN_SIGNALS = new Set(["SIGTERM", "SIGINT", "SIGHUP"]);
+
+const SPAWN_FAILURES = {
+	// X_OK passes for a binary built for another architecture, so this is the one cause no preflight sees.
+	ENOEXEC: (path) =>
+		`${path} is not executable code for this machine (ENOEXEC). A platform ` +
+		`package filled from another architecture produces exactly this; check with \`file ${path}\`.`,
+	EACCES: (path) =>
+		`${path} is not executable by this user (EACCES). Check the file mode, ` +
+		`then every directory on the path to it, then whether the volume is mounted noexec.`,
+	ENOENT: (path) =>
+		`${path} does not exist (ENOENT). The platform package resolved a path ` +
+		`and nothing is at it, so the package installed without its binary.`,
+};
+
+/** Why a spawn was refused, named. Falls back to the thrown message, which is what Harper's own refusals carry. */
+export function describeSpawnFailure(error, binaryPath) {
+	const code =
+		error instanceof Error && typeof error.code === "string"
+			? error.code
+			: undefined;
+	const known = code === undefined ? undefined : SPAWN_FAILURES[code];
+	if (known) return known(binaryPath);
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * How a child ended, in the terms that separate a shutdown from a kill.
+ * A signalled process reports code `null`, which reads as a clean stop everywhere `code || 0` is written.
+ */
+export function describeExit(code, signal) {
+	if (signal) {
+		if (SHUTDOWN_SIGNALS.has(signal)) {
+			return {
+				killed: false,
+				detail: `terminated by ${signal}`,
+				exitCode: 128 + (constants.signals[signal] ?? 0),
+			};
+		}
+		return {
+			killed: true,
+			detail: `killed by ${signal}, which is a crash or an OOM kill rather than a shutdown`,
+			exitCode: 128 + (constants.signals[signal] ?? 0),
+		};
+	}
+	if (code === 0)
+		return { killed: false, detail: "exited cleanly", exitCode: 0 };
+	return {
+		killed: false,
+		detail: `exited with code ${code}`,
+		exitCode: code ?? 1,
+	};
+}

package/runtime/binary.js

@@ -0,0 +1,61 @@
+// The one binary resolver: the installed platform package first, then a dev checkout's build output.
+
+import { existsSync } from "node:fs";
+import { basename, join } from "node:path";
+
+// Constant, never derived: a deployed component's nearest package.json can carry any name, and a wrong base
+// resolves a platform package that does not exist.
+export const PACKAGE_NAME = "@deliciousmonster/datadog-agent-binary";
+
+const EXE = process.platform === "win32" ? ".exe" : "";
+
+// The package root, one level up: a dev checkout's build output sits beside runtime/, never inside it.
+const PACKAGE_ROOT = join(import.meta.dirname, "..");
+
+/** This package's platform label for the running host; throws where no platform package exists. */
+function platformName() {
+	const os = { linux: "linux", darwin: "macos", win32: "windows" }[
+		process.platform
+	];
+	const arch = { x64: "x86_64", arm64: "arm64" }[process.arch];
+	if (!os || !arch) {
+		throw new Error(
+			`unsupported platform: ${process.platform}-${process.arch}`
+		);
+	}
+	return `${os}-${arch}`;
+}
+
+/** The platform package's accessor first (the npm install path), then a dev checkout's build output. */
+export async function resolveBinary(agent) {
+	const file = `${agent.shipsAs}${EXE}`;
+	const platformPackage = `${PACKAGE_NAME}-${platformName()}`;
+	// Set only on a name mismatch, so the error below can tell "the package answered with the wrong
+	// binary" apart from "the package isn't installed" instead of collapsing both into one guess.
+	let staleMatch;
+	try {
+		const pkg = await import(platformPackage);
+		const getBinaryPath = pkg.getBinaryPath ?? pkg.default?.getBinaryPath;
+		const resolved = getBinaryPath?.(agent.shipsAs);
+		// Checked by name: a package published before the trace-agent shipped answers every request with
+		// the core agent, and that path exists, so trusting it starts two core agents and no receiver.
+		if (resolved && basename(resolved) === file && existsSync(resolved)) {
+			return resolved;
+		}
+		if (resolved) staleMatch = resolved;
+	} catch {
+		// The optional dependency is not installed here; the dev-checkout path below still applies.
+	}
+	const local = join(PACKAGE_ROOT, "build", platformName(), "bin", file);
+	if (existsSync(local)) return local;
+	if (staleMatch) {
+		throw new Error(
+			`no ${agent.title} binary: ${platformPackage} is installed but predates ${file} support (it ` +
+				`resolved ${staleMatch} instead) and no local build exists at ${local}. Update ${platformPackage} ` +
+				`to a version that ships ${file}, or build locally with npm run build-agent.`
+		);
+	}
+	throw new Error(
+		`no ${agent.title} binary: neither ${platformPackage} nor a local build at ${local} resolved ${file}`
+	);
+}

package/runtime/config.js

@@ -0,0 +1,195 @@
+// The datadog.yaml both agents read, and the core-check configs without which the core agent runs, reports
+// healthy and collects nothing. Everything here is written under Harper's root, never the component directory.
+
+import {
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { threadId } from "node:worker_threads";
+
+// Rejects `rootPath: null`, which Harper's own defaultConfig.yaml ships, and anything relative: a relative
+// root puts the runtime tree, the PID locks and the reaper's replacement-pid file under each worker's cwd.
+const absoluteRoot = (value) => (value && isAbsolute(value) ? value : null);
+
+// Read here rather than taken from an environment variable this package invents: Harper reads the same chain
+// for itself and exposes no root path to a component. Absolute or null, never throws.
+function readHarperRootPath() {
+	try {
+		const boot = readFileSync(
+			join(homedir(), ".harperdb", "hdb_boot_properties.file"),
+			"utf-8"
+		);
+		// Java-style properties, and Harper indents every line after the first, so the whitespace class matters.
+		const settingsPath = boot.match(
+			/^[ \t]*settings_path[ \t]*=[ \t]*(.+?)[ \t]*$/m
+		)?.[1];
+		if (!settingsPath) return null;
+		// rootPath is top level in harper-config.yaml: the one key readable off a single line without a parser.
+		const rootPath = readFileSync(settingsPath, "utf-8")
+			.match(/^rootPath[ \t]*:[ \t]*(.+?)[ \t]*(?:#.*)?$/m)?.[1]
+			?.replace(/^(['"])(.*)\1$/, "$2");
+		return absoluteRoot(rootPath);
+	} catch {
+		return null;
+	}
+}
+
+/** Harper's root path, or null. ROOTPATH is the harper-pro image's own spelling and wins where it is usable. */
+function harperRoot(log) {
+	const spelled = process.env.ROOTPATH;
+	if (spelled && !absoluteRoot(spelled)) {
+		log.warn(
+			`Datadog supervisor: ROOTPATH="${spelled}" is not an absolute path, so it is ignored. A relative ` +
+				`one resolves against each worker's own cwd, and two workers that disagree take different PID ` +
+				`locks and each start their own pair of agents.`
+		);
+	}
+	return absoluteRoot(spelled) ?? readHarperRootPath();
+}
+
+/** YAML-safe scalar; double quotes also survive Windows drive letters. */
+const yamlString = (value) => JSON.stringify(String(value));
+
+/** The datadog.yaml both agents read: every path off the unwritable Datadog defaults, and the three ports this component probes written as the values it resolved, so a change to an agent default cannot move a port out from under a probe. */
+function renderDatadogYaml(paths, ports) {
+	return [
+		"# GENERATED by resources.js on every Harper worker start. Edits are overwritten.",
+		"# api_key and site are absent by design: they ride in DD_API_KEY / DD_SITE, never on disk.",
+		`confd_path: ${yamlString(paths.confd)}`,
+		`run_path: ${yamlString(paths.run)}`,
+		`auth_token_file_path: ${yamlString(paths.authToken)}`,
+		`ipc_cert_file_path: ${yamlString(paths.ipcCert)}`,
+		"# The agents log under the runtime tree; a stdio pipe would tie them to one worker thread.",
+		"log_to_console: false",
+		`log_file: ${yamlString(paths.coreLog)}`,
+		// Both agents read these same top-level keys; apm_config has no rotation settings of its own.
+		// 5 MiB by 2 rolls bounds each log file at 15 MiB, against a default that bounds nothing here.
+		'log_file_max_size: "5Mb"',
+		"log_file_max_rolls: 2",
+		"# Loopback only. Nothing here should be reachable from outside the container.",
+		'bind_host: "127.0.0.1"',
+		"# Pinned because the core-agent verify reads expvar off this port. Measured on 7.82.1: the environment",
+		"# outranks this file, so a set DD_EXPVAR_PORT wins and this only pins the port against a default that moves.",
+		`expvar_port: ${ports.expvar}`,
+		"apm_config:",
+		"  enabled: true",
+		`  receiver_port: ${ports.receiver}`,
+		"  # On, this binds 0.0.0.0 and accepts spans from anything that reaches the container.",
+		"  apm_non_local_traffic: false",
+		`  log_file: ${yamlString(paths.traceLog)}`,
+		"  # The trace-agent's own expvar, separate from the core agent's. Without it nothing on this node",
+		"  # can say whether a span that reached the receiver ever left for Datadog.",
+		"  debug:",
+		`    port: ${ports.debug}`,
+		"",
+	].join("\n");
+}
+
+/** The shipped core checks that apply here; an optional `platforms` file beside a check gates it, absent means everywhere. */
+function collectCoreChecks(packageConfd) {
+	const checks = [];
+	const entries = readdirSync(packageConfd, { withFileTypes: true }).sort(
+		(a, b) => (a.name < b.name ? -1 : 1)
+	);
+	for (const entry of entries) {
+		if (!entry.isDirectory() || !entry.name.endsWith(".d")) continue;
+		const source = join(packageConfd, entry.name, "conf.yaml.default");
+		if (!existsSync(source)) continue;
+		const gate = join(packageConfd, entry.name, "platforms");
+		if (existsSync(gate)) {
+			const platforms = readFileSync(gate, "utf-8")
+				.replace(/#.*$/gm, "")
+				.split(/\s+/)
+				.filter(Boolean);
+			if (!platforms.includes(process.platform)) continue;
+		}
+		checks.push({
+			dir: entry.name,
+			name: entry.name.slice(0, -".d".length),
+			body: readFileSync(source, "utf-8"),
+		});
+	}
+	return checks;
+}
+
+/** This start owns exactly the conf.yaml.default files. One nobody claims was left by an older version on a persistent volume; an operator's own conf.yaml is never touched. */
+function removeStaleDefaults(confd, owned) {
+	for (const entry of readdirSync(confd, { withFileTypes: true })) {
+		if (entry.isDirectory() && !owned.has(entry.name)) {
+			rmSync(join(confd, entry.name, "conf.yaml.default"), { force: true });
+		}
+	}
+}
+
+// The runtime tree lives under Harper's root, never the component directory, which `harper deploy` replaces
+// under a live agent. Named by the component's own directory, not just "datadog": sharing one pidDir means sharing one lock.
+export function prepareRuntime(componentDir, { ports, log }) {
+	const root = harperRoot(log);
+	const runtimeDir = root
+		? join(root, "datadog", basename(componentDir))
+		: join(homedir(), ".harper-datadog", basename(componentDir));
+	const paths = {
+		runtimeDir,
+		configFile: join(runtimeDir, "datadog.yaml"),
+		confd: join(runtimeDir, "conf.d"),
+		run: join(runtimeDir, "run"),
+		authToken: join(runtimeDir, "run", "auth_token"),
+		ipcCert: join(runtimeDir, "run", "ipc_cert.pem"),
+		coreLog: join(runtimeDir, "logs", "agent.log"),
+		traceLog: join(runtimeDir, "logs", "trace-agent.log"),
+		// Not Harper's own pids/: the guard's reaper stops every guard-written lock it finds in the directory
+		// it watches, and a shared one would hold locks this component never wrote.
+		pidDir: join(runtimeDir, "pids"),
+		reaperLog: join(runtimeDir, "logs", "reaper.log"),
+	};
+	mkdirSync(paths.run, { recursive: true });
+	mkdirSync(dirname(paths.coreLog), { recursive: true });
+	mkdirSync(paths.confd, { recursive: true });
+	mkdirSync(paths.pidDir, { recursive: true });
+
+	const configFiles = { [paths.configFile]: renderDatadogYaml(paths, ports) };
+	let checks = [];
+	try {
+		checks = collectCoreChecks(join(componentDir, "conf.d"));
+		for (const check of checks) {
+			configFiles[join(paths.confd, check.dir, "conf.yaml.default")] =
+				check.body;
+		}
+		removeStaleDefaults(paths.confd, new Set(checks.map((check) => check.dir)));
+	} catch (error) {
+		log.warn(
+			`Datadog supervisor: no core check configuration was collected (${error.message}), so the agent ` +
+				`will report healthy and collect no host metrics. Traces are unaffected.`
+		);
+	}
+
+	return {
+		root,
+		paths,
+		configFiles,
+		coreChecks: checks.map((check) => check.name),
+	};
+}
+
+/** Temp-and-rename, because every worker thread writes these and a rereading agent must see old or new, never torn. */
+export function writeConfigFiles(configFiles, log) {
+	for (const [target, contents] of Object.entries(configFiles)) {
+		try {
+			mkdirSync(dirname(target), { recursive: true });
+			const temp = `${target}.${process.pid}.${threadId}.tmp`;
+			writeFileSync(temp, contents, "utf-8");
+			renameSync(temp, target);
+		} catch (error) {
+			log.error(
+				`Datadog supervisor: could not write ${target}: ${error.message}`
+			);
+		}
+	}
+}