@netlify/build 28.0.0-beta → 28.0.0

package/lib/steps/run_step.js

@@ -0,0 +1,188 @@
+import { addMutableConstants } from '../core/constants.js';
+import { logStepStart } from '../log/messages/steps.js';
+import { runsAlsoOnBuildFailure, runsOnlyOnBuildFailure } from '../plugins/events.js';
+import { measureDuration, normalizeTimerName } from '../time/main.js';
+import { fireCoreStep } from './core_step.js';
+import { firePluginStep } from './plugin.js';
+import { getStepReturn } from './return.js';
+// Run a step (core, build command or plugin)
+export const runStep = async function ({ event, childProcess, packageName, coreStep, coreStepId, coreStepName, coreStepDescription, pluginPackageJson, loadedFrom, origin, condition, configPath, buildDir, repositoryRoot, nodePath, index, childEnv, context, branch, envChanges, constants, steps, buildbotServerSocket, events, mode, api, errorMonitor, deployId, errorParams, error, failedPlugins, configOpts, netlifyConfig, configMutations, headersPath, redirectsPath, logs, debug, systemLog, verbose, saveConfig, timers, testOpts, featureFlags, }) {
+    const constantsA = await addMutableConstants({ constants, buildDir, netlifyConfig });
+    if (!(await shouldRunStep({
+        event,
+        packageName,
+        error,
+        failedPlugins,
+        netlifyConfig,
+        condition,
+        constants: constantsA,
+        buildbotServerSocket,
+        buildDir,
+    }))) {
+        return {};
+    }
+    logStepStart({ logs, event, packageName, coreStepDescription, index, error, netlifyConfig });
+    const fireStep = getFireStep(packageName, coreStepId, event);
+    const { newEnvChanges, netlifyConfig: netlifyConfigA = netlifyConfig, configMutations: configMutationsA = configMutations, headersPath: headersPathA = headersPath, redirectsPath: redirectsPathA = redirectsPath, newError, newStatus, timers: timersA, durationNs, } = await fireStep({
+        event,
+        childProcess,
+        packageName,
+        pluginPackageJson,
+        loadedFrom,
+        origin,
+        coreStep,
+        coreStepName,
+        configPath,
+        buildDir,
+        repositoryRoot,
+        nodePath,
+        childEnv,
+        context,
+        branch,
+        envChanges,
+        constants: constantsA,
+        steps,
+        buildbotServerSocket,
+        events,
+        error,
+        logs,
+        debug,
+        systemLog,
+        verbose,
+        saveConfig,
+        timers,
+        errorParams,
+        configOpts,
+        netlifyConfig,
+        configMutations,
+        headersPath,
+        redirectsPath,
+        featureFlags,
+    });
+    const newValues = await getStepReturn({
+        event,
+        packageName,
+        newError,
+        newEnvChanges,
+        newStatus,
+        coreStep,
+        coreStepName,
+        childEnv,
+        mode,
+        api,
+        errorMonitor,
+        deployId,
+        netlifyConfig: netlifyConfigA,
+        configMutations: configMutationsA,
+        headersPath: headersPathA,
+        redirectsPath: redirectsPathA,
+        logs,
+        debug,
+        systemLog,
+        timers: timersA,
+        durationNs,
+        testOpts,
+    });
+    return { ...newValues, newIndex: index + 1 };
+};
+// A plugin fails _without making the build fail_ when either:
+//   - using `utils.build.failPlugin()`
+//   - the failure happens after deploy. This means: inside any `onError`,
+//     `onSuccess` or `onEnd` event handler.
+//
+// When that happens, no other events for that specific plugin is run.
+// Not even `onError` and `onEnd`.
+// Plugins should use `try`/`catch`/`finally` blocks to handle exceptions,
+// not `onError` nor `onEnd`.
+//
+// Otherwise, most failures will make the build fail. This includes:
+//   - the build command failed
+//   - Functions or Edge Functions bundling failed
+//   - the deploy failed (deploying files to our CDN)
+//   - a plugin `onPreBuild`, `onBuild` or `onPostBuild` event handler failed.
+//     This includes uncaught exceptions and using `utils.build.failBuild()`
+//     or `utils.build.cancelBuild()`.
+//
+// `onError` is triggered when the build failed.
+// It means "on build failure" not "on plugin failure".
+// `onSuccess` is the opposite. It is triggered after the build succeeded.
+// `onEnd` is triggered after the build either failed or succeeded.
+// It is useful for resources cleanup.
+//
+// Finally, some plugins (only core plugins for the moment) might be enabled or
+// not depending on whether a specific action is happening during the build,
+// such as creating a file. For example, the Functions and Edge Functions core
+// plugins are disabled if no Functions or Edge Functions directory is specified
+// or available. However, one might be created by a build plugin, in which case,
+// those core plugins should be triggered. We use a dynamic `condition()` to
+// model this behavior.
+const shouldRunStep = async function ({ event, packageName, error, failedPlugins, netlifyConfig, condition, constants, buildbotServerSocket, buildDir, }) {
+    if (failedPlugins.includes(packageName) ||
+        (condition !== undefined && !(await condition({ buildDir, constants, buildbotServerSocket, netlifyConfig })))) {
+        return false;
+    }
+    if (error !== undefined) {
+        return runsAlsoOnBuildFailure(event);
+    }
+    return !runsOnlyOnBuildFailure(event);
+};
+// Wrap step function to measure its time
+const getFireStep = function (packageName, coreStepId, event) {
+    if (coreStepId !== undefined) {
+        return measureDuration(tFireStep, coreStepId);
+    }
+    const parentTag = normalizeTimerName(packageName);
+    return measureDuration(tFireStep, event, { parentTag, category: 'pluginEvent' });
+};
+const tFireStep = function ({ event, childProcess, packageName, pluginPackageJson, loadedFrom, origin, coreStep, coreStepName, configPath, buildDir, repositoryRoot, nodePath, childEnv, context, branch, envChanges, constants, steps, buildbotServerSocket, events, error, logs, debug, systemLog, verbose, saveConfig, errorParams, configOpts, netlifyConfig, configMutations, headersPath, redirectsPath, featureFlags, }) {
+    if (coreStep !== undefined) {
+        return fireCoreStep({
+            coreStep,
+            coreStepName,
+            configPath,
+            buildDir,
+            repositoryRoot,
+            constants,
+            buildbotServerSocket,
+            events,
+            logs,
+            nodePath,
+            childEnv,
+            context,
+            branch,
+            envChanges,
+            errorParams,
+            configOpts,
+            netlifyConfig,
+            configMutations,
+            headersPath,
+            redirectsPath,
+            featureFlags,
+            debug,
+            systemLog,
+            saveConfig,
+        });
+    }
+    return firePluginStep({
+        event,
+        childProcess,
+        packageName,
+        pluginPackageJson,
+        loadedFrom,
+        origin,
+        envChanges,
+        errorParams,
+        configOpts,
+        netlifyConfig,
+        configMutations,
+        headersPath,
+        redirectsPath,
+        constants,
+        steps,
+        error,
+        logs,
+        debug,
+        systemLog,
+        verbose,
+    });
+};

package/lib/steps/run_steps.js

@@ -0,0 +1,96 @@
+import pReduce from 'p-reduce';
+import { addErrorInfo } from '../error/info.js';
+import { addStatus } from '../status/add.js';
+import { runStep } from './run_step.js';
+// Run all steps.
+// Each step can change some state: last `error`, environment variables changes,
+// list of `failedPlugins` (that ran `utils.build.failPlugin()`).
+// If an error arises, runs `onError` events.
+// Runs `onEnd` events at the end, whether an error was thrown or not.
+export const runSteps = async function ({ steps, buildbotServerSocket, events, configPath, headersPath, redirectsPath, buildDir, repositoryRoot, nodePath, childEnv, context, branch, constants, mode, api, errorMonitor, deployId, errorParams, netlifyConfig, configOpts, logs, debug, systemLog, verbose, saveConfig, timers, testOpts, featureFlags, }) {
+    const { index: stepsCount, error: errorA, netlifyConfig: netlifyConfigC, statuses: statusesB, failedPlugins: failedPluginsA, timers: timersC, configMutations: configMutationsB, } = await pReduce(steps, async ({ index, error, failedPlugins, envChanges, netlifyConfig: netlifyConfigA, configMutations, headersPath: headersPathA, redirectsPath: redirectsPathA, statuses, timers: timersA, }, { event, childProcess, packageName, coreStep, coreStepId, coreStepName, coreStepDescription, pluginPackageJson, loadedFrom, origin, condition, }) => {
+        const { newIndex = index, newError = error, failedPlugin = [], newEnvChanges = {}, netlifyConfig: netlifyConfigB = netlifyConfigA, configMutations: configMutationsA = configMutations, headersPath: headersPathB = headersPathA, redirectsPath: redirectsPathB = redirectsPathA, newStatus, timers: timersB = timersA, } = await runStep({
+            event,
+            childProcess,
+            packageName,
+            coreStep,
+            coreStepId,
+            coreStepName,
+            coreStepDescription,
+            pluginPackageJson,
+            loadedFrom,
+            origin,
+            condition,
+            configPath,
+            buildDir,
+            repositoryRoot,
+            nodePath,
+            index,
+            childEnv,
+            context,
+            branch,
+            envChanges,
+            constants,
+            steps,
+            buildbotServerSocket,
+            events,
+            mode,
+            api,
+            errorMonitor,
+            deployId,
+            errorParams,
+            error,
+            failedPlugins,
+            configOpts,
+            netlifyConfig: netlifyConfigA,
+            configMutations,
+            headersPath: headersPathA,
+            redirectsPath: redirectsPathA,
+            logs,
+            debug,
+            systemLog,
+            verbose,
+            saveConfig,
+            timers: timersA,
+            testOpts,
+            featureFlags,
+        });
+        const statusesA = addStatus({ newStatus, statuses, event, packageName, pluginPackageJson });
+        return {
+            index: newIndex,
+            error: newError,
+            failedPlugins: [...failedPlugins, ...failedPlugin],
+            envChanges: { ...envChanges, ...newEnvChanges },
+            netlifyConfig: netlifyConfigB,
+            configMutations: configMutationsA,
+            headersPath: headersPathB,
+            redirectsPath: redirectsPathB,
+            statuses: statusesA,
+            timers: timersB,
+        };
+    }, {
+        index: 0,
+        failedPlugins: [],
+        envChanges: {},
+        netlifyConfig,
+        configMutations: [],
+        headersPath,
+        redirectsPath,
+        statuses: [],
+        timers,
+    });
+    // Instead of throwing any build failure right away, we wait for `onError`,
+    // etc. to complete. This is why we are throwing only now.
+    if (errorA !== undefined) {
+        addErrorInfo(errorA, { statuses: statusesB });
+        throw errorA;
+    }
+    return {
+        stepsCount,
+        netlifyConfig: netlifyConfigC,
+        statuses: statusesB,
+        failedPlugins: failedPluginsA,
+        timers: timersC,
+        configMutations: configMutationsB,
+    };
+};

package/lib/steps/update_config.js

@@ -0,0 +1,66 @@
+import { isDeepStrictEqual } from 'util';
+import pFilter from 'p-filter';
+import { pathExists } from 'path-exists';
+import { resolveUpdatedConfig } from '../core/config.js';
+import { addErrorInfo } from '../error/info.js';
+import { logConfigOnUpdate } from '../log/messages/config.js';
+import { logConfigMutations } from '../log/messages/mutations.js';
+// If `netlifyConfig` was updated or `_redirects` was created, the configuration
+// is updated by calling `@netlify/config` again.
+export const updateNetlifyConfig = async function ({ configOpts, netlifyConfig, headersPath, redirectsPath, configMutations, newConfigMutations, configSideFiles, errorParams, logs, debug, }) {
+    if (!(await shouldUpdateConfig({ newConfigMutations, configSideFiles, headersPath, redirectsPath }))) {
+        return { netlifyConfig, configMutations };
+    }
+    validateConfigMutations(newConfigMutations);
+    logConfigMutations(logs, newConfigMutations, debug);
+    const configMutationsA = [...configMutations, ...newConfigMutations];
+    const { config: netlifyConfigA, headersPath: headersPathA, redirectsPath: redirectsPathA, } = await resolveUpdatedConfig(configOpts, configMutationsA);
+    logConfigOnUpdate({ logs, netlifyConfig: netlifyConfigA, debug });
+    errorParams.netlifyConfig = netlifyConfigA;
+    return {
+        netlifyConfig: netlifyConfigA,
+        configMutations: configMutationsA,
+        headersPath: headersPathA,
+        redirectsPath: redirectsPathA,
+    };
+};
+const shouldUpdateConfig = async function ({ newConfigMutations, configSideFiles, headersPath, redirectsPath }) {
+    return (newConfigMutations.length !== 0 || (await haveConfigSideFilesChanged(configSideFiles, headersPath, redirectsPath)));
+};
+// The configuration mostly depends on `netlify.toml` and UI build settings.
+// However, it also uses some additional optional side files like `_redirects`.
+// Those are often created by the build command. When those are created, we need
+// to update the configuration. We detect this by checking for file existence
+// before and after running plugins and the build command.
+const haveConfigSideFilesChanged = async function (configSideFiles, headersPath, redirectsPath) {
+    const newSideFiles = await listConfigSideFiles([headersPath, redirectsPath]);
+    return !isDeepStrictEqual(newSideFiles, configSideFiles);
+};
+// List all the files used for configuration besides `netlify.toml`.
+// This is useful when applying configuration mutations since those files
+// sometimes have higher priority and should therefore be deleted in order to
+// apply any configuration update on `netlify.toml`.
+export const listConfigSideFiles = async function (sideFiles) {
+    const configSideFiles = await pFilter(sideFiles, pathExists);
+    return configSideFiles.sort();
+};
+// Validate each new configuration change
+const validateConfigMutations = function (newConfigMutations) {
+    try {
+        newConfigMutations.forEach(validateConfigMutation);
+    }
+    catch (error) {
+        addErrorInfo(error, { type: 'pluginValidation' });
+        throw error;
+    }
+};
+// Triggered when calling `netlifyConfig.{key} = undefined | null`
+// We do not allow this because the back-end only receives mutations as a
+// `netlify.toml`, i.e. cannot apply property deletions since `undefined` is
+// not serializable in TOML.
+const validateConfigMutation = function ({ value, keysString }) {
+    if (value === undefined || value === null) {
+        throw new Error(`Setting "netlifyConfig.${keysString}" to ${value} is not allowed.
+Please set this property to a specific value instead.`);
+    }
+};

package/lib/telemetry/main.js

@@ -0,0 +1,97 @@
+import { platform } from 'process';
+import got from 'got';
+import osName from 'os-name';
+import { addErrorInfo } from '../error/info.js';
+import { roundTimerToMillisecs } from '../time/measure.js';
+import { ROOT_PACKAGE_JSON } from '../utils/json.js';
+const DEFAULT_TELEMETRY_TIMEOUT = 1200;
+const DEFAULT_TELEMETRY_CONFIG = {
+    origin: 'https://api.segment.io/v1',
+    writeKey: 'dWhlM1lYSlpNd1k5Uk9rcjFra2JSOEoybnRjZjl0YTI6',
+    timeout: DEFAULT_TELEMETRY_TIMEOUT,
+};
+// Send telemetry request when build completes
+export const trackBuildComplete = async function ({ deployId, buildId, status, stepsCount, pluginsOptions, durationNs, siteInfo, telemetry, userNodeVersion, framework, testOpts: { telemetryOrigin = DEFAULT_TELEMETRY_CONFIG.origin, telemetryTimeout = DEFAULT_TELEMETRY_CONFIG.timeout }, }) {
+    if (!telemetry) {
+        return;
+    }
+    try {
+        const payload = getPayload({
+            deployId,
+            buildId,
+            status,
+            stepsCount,
+            pluginsOptions,
+            durationNs,
+            siteInfo,
+            userNodeVersion,
+            framework,
+        });
+        await track({
+            payload,
+            config: { ...DEFAULT_TELEMETRY_CONFIG, origin: telemetryOrigin, timeout: telemetryTimeout },
+        });
+    }
+    catch (error) {
+        addErrorInfo(error, { type: 'telemetry' });
+        throw error;
+    }
+};
+// Send track HTTP request to telemetry.
+const track = async function ({ payload, config: { origin, writeKey, timeout } }) {
+    const url = `${origin}/track`;
+    await got.post(url, {
+        json: payload,
+        timeout,
+        retry: 0,
+        headers: { Authorization: `Basic ${writeKey}` },
+    });
+};
+// Retrieve telemetry information
+// siteInfo can be empty if the build fails during the get config step
+const getPayload = function ({ deployId, buildId, status, stepsCount, pluginsOptions, durationNs, userNodeVersion, siteInfo = {}, framework, }) {
+    return {
+        userId: 'buildbot_user',
+        event: 'build:ci_build_process_completed',
+        timestamp: Date.now(),
+        properties: {
+            deployId,
+            buildId,
+            status,
+            steps: stepsCount,
+            buildVersion: ROOT_PACKAGE_JSON.version,
+            // We're passing the node version set by the buildbot/user which will run the `build.command` and
+            // the `package.json`/locally defined plugins
+            nodeVersion: userNodeVersion,
+            osPlatform: OS_TYPES[platform],
+            osName: osName(),
+            framework,
+            siteId: siteInfo.id,
+            ...(pluginsOptions !== undefined && {
+                plugins: pluginsOptions.map(getPlugin),
+                pluginCount: pluginsOptions.length,
+            }),
+            ...(durationNs !== undefined && { duration: roundTimerToMillisecs(durationNs) }),
+        },
+    };
+};
+const OS_TYPES = {
+    linux: 'Linux',
+    darwin: 'MacOS',
+    win32: 'Windows',
+    android: 'Android',
+    sunos: 'SunOS',
+    aix: 'AIX',
+    freebsd: 'FreeBSD',
+    openbsd: 'OpenBSD',
+};
+const getPlugin = function ({ packageName, origin, loadedFrom, nodeVersion, pinnedVersion, pluginPackageJson: { version } = {}, }) {
+    const installType = getInstallType(origin, loadedFrom);
+    return { name: packageName, installType, nodeVersion, pinnedVersion, version };
+};
+const getInstallType = function (origin, loadedFrom) {
+    if (loadedFrom === 'auto_install') {
+        return origin === 'ui' ? 'ui' : 'netlify_toml';
+    }
+    return loadedFrom;
+};

package/lib/time/aggregate.js

@@ -0,0 +1,120 @@
+import { createTimer, TOP_PARENT_TAG } from './main.js';
+// Some timers are computed based on others:
+//   - `others` is `total` minus the other timers
+//   - `run_plugins` is the sum of all plugins
+//   - `run_netlify_build_per_type` aggregates timers but per system/plugin/user
+//   - each plugin timer is the sum of its event handlers
+export const addAggregatedTimers = function (timers) {
+    const timersA = addRunPluginsTimer(timers);
+    const timersB = addPluginTimers(timersA);
+    const timersC = addOthersTimers(timersB);
+    const timersD = addTypeTimers(timersC);
+    return timersD;
+};
+// Having a `total` timer is redundant since the buildbot already measures this.
+// The buildbot measurement is better since it includes the time to load Node.
+// Instead, we only use `total` to measure what did not get `measureDuration()`.
+const addOthersTimers = function (timers) {
+    const totalTimer = timers.find(isTotalTimer);
+    const timersA = timers.filter((timer) => !isTotalTimer(timer));
+    const topTimers = timersA.filter(isTopTimer);
+    const othersTimer = createOthersTimer(topTimers, totalTimer);
+    return [...timersA, othersTimer];
+};
+const isTotalTimer = function ({ stageTag, parentTag }) {
+    return stageTag === 'total' && parentTag === 'build_site';
+};
+const createOthersTimer = function (topTimers, { durationNs: totalTimerDurationNs }) {
+    const topTimersDurationNs = computeTimersDuration(topTimers);
+    const otherTimersDurationNs = Math.max(0, totalTimerDurationNs - topTimersDurationNs);
+    const othersTimer = createTimer(OTHERS_STAGE_TAG, otherTimersDurationNs);
+    return othersTimer;
+};
+const OTHERS_STAGE_TAG = 'others';
+// Measure the total time running plugins
+const addRunPluginsTimer = function (timers) {
+    const pluginsTimers = timers.filter(isPluginTimer);
+    return pluginsTimers.length === 0 ? timers : [...timers, createSumTimer(pluginsTimers, RUN_PLUGINS_STAGE_TAG)];
+};
+const RUN_PLUGINS_STAGE_TAG = 'run_plugins';
+// Retrieve one timer for each plugin, summing all its individual timers
+// (one per event handler)
+const addPluginTimers = function (timers) {
+    const timersA = timers.filter((timer) => !isCommunityPluginTimer(timer));
+    const pluginsTimers = timersA.filter(isPluginTimer);
+    if (pluginsTimers.length === 0) {
+        return timersA;
+    }
+    const pluginPackages = getPluginPackages(pluginsTimers);
+    const wholePluginsTimers = pluginPackages.map((pluginPackage) => getWholePluginTimer(pluginPackage, pluginsTimers));
+    return [...timersA, ...wholePluginsTimers];
+};
+// We only measure plugins maintained by us, not community
+const isCommunityPluginTimer = function (timer) {
+    return isPluginTimer(timer) && !isNetlifyMaintainedPlugin(getPluginTimerPackage(timer));
+};
+const isNetlifyMaintainedPlugin = function (pluginPackage) {
+    return NETLIFY_MAINTAINED_PLUGINS.has(pluginPackage);
+};
+const NETLIFY_MAINTAINED_PLUGINS = new Set([
+    'netlify_plugin_gatsby_cache',
+    'netlify_plugin_sitemap',
+    'netlify_plugin_debug_cache',
+    'netlify_plugin_is_website_vulnerable',
+    'netlify_plugin_lighthouse',
+    'netlify_plugin_nextjs',
+    'netlify_plugin_gatsby',
+]);
+const getPluginPackages = function (pluginsTimers) {
+    const pluginPackages = pluginsTimers.map(getPluginTimerPackage);
+    return [...new Set(pluginPackages)];
+};
+const getWholePluginTimer = function (pluginPackage, pluginsTimers) {
+    const pluginTimers = pluginsTimers.filter((pluginTimer) => getPluginTimerPackage(pluginTimer) === pluginPackage);
+    const wholePluginsTimer = createSumTimer(pluginTimers, pluginPackage, RUN_PLUGINS_STAGE_TAG);
+    return wholePluginsTimer;
+};
+const getPluginTimerPackage = function ({ parentTag }) {
+    return parentTag;
+};
+// Check if a timer relates to a Build plugin
+const isPluginTimer = function ({ category }) {
+    return category === 'pluginEvent';
+};
+// Reports total time depending on whether it was system, plugin or user
+const addTypeTimers = function (timers) {
+    const topTimers = timers.filter(isTopTimer);
+    const typeTimers = TYPE_TIMERS.map(({ name, stages }) => getTypeTimer(name, stages, topTimers)).filter(Boolean);
+    return [...timers, ...typeTimers];
+};
+const TYPE_TIMERS = [
+    { name: 'system', stages: ['resolve_config', 'get_plugins_options', 'start_plugins', 'others'] },
+    { name: 'plugin', stages: ['load_plugins', 'run_plugins'] },
+    { name: 'user', stages: ['build_command', 'functions_bundling', 'deploy_site'] },
+];
+const getTypeTimer = function (name, stages, topTimers) {
+    const topTimersA = topTimers.filter(({ stageTag }) => stages.includes(stageTag));
+    if (topTimersA.length === 0) {
+        return;
+    }
+    const typeTimer = createSumTimer(topTimersA, name, 'run_netlify_build_per_type');
+    return typeTimer;
+};
+const isTopTimer = function ({ parentTag }) {
+    return parentTag === TOP_PARENT_TAG;
+};
+// Creates a timer that sums up the duration of several others
+const createSumTimer = function (timers, stageTag, parentTag) {
+    const durationNs = computeTimersDuration(timers);
+    const timer = createTimer(stageTag, durationNs, { parentTag });
+    return timer;
+};
+const computeTimersDuration = function (timers) {
+    return timers.map(getTimerDuration).reduce(reduceSum, 0);
+};
+const getTimerDuration = function ({ durationNs }) {
+    return durationNs;
+};
+const reduceSum = function (sum, number) {
+    return sum + number;
+};

package/lib/time/main.js

@@ -0,0 +1,37 @@
+import slugify from '@sindresorhus/slugify';
+import keepFuncProps from 'keep-func-props';
+import { startTimer, endTimer } from './measure.js';
+// Initialize the `timers` array
+export const initTimers = function () {
+    return [];
+};
+// Wrap an async function to measure how long it takes.
+// The function must:
+//   - take a plain object as first argument. This must contain a `timers`.
+//   - return a plain object. This may or may not contain a modified `timers`.
+// The `durationNs` will be returned by the function. A new `timers` with the
+// additional duration timer will be returned as well.
+const kMeasureDuration = function (func, stageTag, { parentTag, category } = {}) {
+    return async function measuredFunc({ timers, ...opts }, ...args) {
+        const timerNs = startTimer();
+        const { timers: timersA = timers, ...returnObject } = await func({ timers, ...opts }, ...args);
+        const { tags = {} } = returnObject;
+        const durationNs = endTimer(timerNs);
+        const timer = createTimer(stageTag, durationNs, { parentTag, category, tags });
+        const timersB = [...timersA, timer];
+        return { ...returnObject, timers: timersB, durationNs };
+    };
+};
+// Ensure the wrapped function `name` is not `anonymous` in stack traces
+export const measureDuration = keepFuncProps(kMeasureDuration);
+// Create a new object representing a completed timer
+export const createTimer = function (stageTag, durationNs, { metricName = DEFAULT_METRIC_NAME, parentTag = TOP_PARENT_TAG, category, tags } = {}) {
+    return { metricName, stageTag, parentTag, durationNs, category, tags };
+};
+const DEFAULT_METRIC_NAME = 'buildbot.build.stage.duration';
+export const TOP_PARENT_TAG = 'run_netlify_build';
+// Make sure the timer name does not include special characters.
+// For example, the `packageName` of local plugins includes dots.
+export const normalizeTimerName = function (name) {
+    return slugify(name, { separator: '_' });
+};

package/lib/time/measure.js

@@ -0,0 +1,18 @@
+import { hrtime } from 'process';
+// Starts a timer
+export const startTimer = function () {
+    return hrtime();
+};
+// Stops a timer
+export const endTimer = function ([startSecs, startNsecs]) {
+    const [endSecs, endNsecs] = hrtime();
+    const durationNs = (endSecs - startSecs) * NANOSECS_TO_SECS + endNsecs - startNsecs;
+    return durationNs;
+};
+// statsd expects milliseconds integers.
+// To prevent double rounding errors, rounding should only be applied once.
+export const roundTimerToMillisecs = function (durationNs) {
+    return Math.round(durationNs / NANOSECS_TO_MSECS);
+};
+const NANOSECS_TO_SECS = 1e9;
+const NANOSECS_TO_MSECS = 1e6;

package/lib/time/report.js

@@ -0,0 +1,47 @@
+import { promisify } from 'util';
+import StatsdClient from 'statsd-client';
+import { addAggregatedTimers } from './aggregate.js';
+import { roundTimerToMillisecs } from './measure.js';
+// TODO: replace with `timers/promises` after dropping Node < 15.0.0
+const pSetTimeout = promisify(setTimeout);
+// Record the duration of a build phase, for monitoring.
+// Sends to statsd daemon.
+export const reportTimers = async function ({ timers, statsdOpts: { host, port }, framework }) {
+    if (host === undefined) {
+        return;
+    }
+    const timersA = addAggregatedTimers(timers);
+    await sendTimers({ timers: timersA, host, port, framework });
+};
+const sendTimers = async function ({ timers, host, port, framework }) {
+    const client = await startClient(host, port);
+    timers.forEach((timer) => {
+        sendTimer({ timer, client, framework });
+    });
+    await closeClient(client);
+};
+// The socket creation is delayed until the first packet is sent. In our
+// case, this happens just before `client.close()` is called, which is too
+// late and make it not send anything. We need to manually create it using
+// the internal API.
+const startClient = async function (host, port) {
+    const client = new StatsdClient({ host, port, socketTimeout: 0 });
+    await promisify(client._socket._createSocket.bind(client._socket))();
+    return client;
+};
+const sendTimer = function ({ timer: { metricName, stageTag, parentTag, durationNs, tags }, client, framework }) {
+    const durationMs = roundTimerToMillisecs(durationNs);
+    const frameworkTag = framework === undefined ? {} : { framework };
+    client.distribution(metricName, durationMs, { stage: stageTag, parent: parentTag, ...tags, ...frameworkTag });
+};
+// UDP packets are buffered and flushed at regular intervals by statsd-client.
+// Closing force flushing all of them.
+const closeClient = async function (client) {
+    client.close();
+    // statsd-clent does not provide with a way of knowing when the socket is done
+    // closing, so we need to use the following hack.
+    await pSetTimeout(CLOSE_TIMEOUT);
+    await pSetTimeout(CLOSE_TIMEOUT);
+};
+// See https://github.com/msiebuhr/node-statsd-client/blob/45a93ee4c94ca72f244a40b06cb542d4bd7c3766/lib/EphemeralSocket.js#L81
+const CLOSE_TIMEOUT = 11;