@farm.js/otel 0.1.0-beta.25 → 0.1.0-beta.27

package/dist/farm-events.d.ts

@@ -0,0 +1,30 @@
+import { type MeterProvider } from "@opentelemetry/api";
+/** Instrumentation scope shared by every instrument created here. */
+export declare const FARM_EVENTS_METER_NAME = "@farm.js/otel";
+export interface FarmEventMappingOptions {
+    /** Record counters and histograms for mapped events. Defaults to `true`. */
+    metrics?: boolean;
+    /** Add mapped events to the active span. Defaults to `true`. */
+    spanEvents?: boolean;
+    /**
+     * Meter provider the instruments are created from. Defaults to the globally
+     * registered provider, which only becomes real once an SDK has started, so
+     * instruments must be created after `sdk.start()`.
+     */
+    meterProvider?: MeterProvider;
+}
+/**
+ * Subscribes to Farm's observability bus and records the framework's own cache,
+ * PPR, streaming and middleware signals as OpenTelemetry metrics plus events on
+ * the active span.
+ *
+ * Metric attributes are deliberately limited to bounded values. A cache `key`
+ * embeds the serialized arguments of the cached call and a `tag` is authored at
+ * runtime, so neither is ever used as a metric attribute; per-request detail
+ * stays on span events, where high cardinality is free.
+ *
+ * Returns a dispose function. Call it during shutdown so a development restart
+ * does not stack subscribers.
+ */
+export declare function recordFarmEvents(options?: FarmEventMappingOptions): Promise<() => void>;
+//# sourceMappingURL=farm-events.d.ts.map

package/dist/farm-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"farm-events.d.ts","sourceRoot":"","sources":["../src/farm-events.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,aAAa,EAEnB,MAAM,oBAAoB,CAAC;AAG5B,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AAEtD,MAAM,WAAW,uBAAuB;IACtC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAmCD;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAmDjG"}

package/dist/farm-events.js

@@ -0,0 +1,264 @@
+import { metrics as metricsApi, trace, } from "@opentelemetry/api";
+/** Instrumentation scope shared by every instrument created here. */
+export const FARM_EVENTS_METER_NAME = "@farm.js/otel";
+const CACHE_LOOKUP_RESULTS = {
+    "cache.hit": "hit",
+    "cache.miss": "miss",
+    "cache.stale": "stale",
+    "cache.dedupe": "dedupe",
+    "cache.bypass": "bypass",
+};
+const CACHE_INVALIDATION_OPERATIONS = {
+    "cache.revalidateTag": "revalidateTag",
+    "cache.updateTag": "updateTag",
+    "cache.revalidatePath": "revalidatePath",
+    "cache.invalidated": "invalidated",
+};
+const PPR_SHELL_RESULTS = {
+    "ppr.shell.hit": "hit",
+    "ppr.shell.miss": "miss",
+    "ppr.shell.cached": "cached",
+    "ppr.shell.bypass": "bypass",
+    "ppr.shell.invalidated": "invalidated",
+};
+/**
+ * Subscribes to Farm's observability bus and records the framework's own cache,
+ * PPR, streaming and middleware signals as OpenTelemetry metrics plus events on
+ * the active span.
+ *
+ * Metric attributes are deliberately limited to bounded values. A cache `key`
+ * embeds the serialized arguments of the cached call and a `tag` is authored at
+ * runtime, so neither is ever used as a metric attribute; per-request detail
+ * stays on span events, where high cardinality is free.
+ *
+ * Returns a dispose function. Call it during shutdown so a development restart
+ * does not stack subscribers.
+ */
+export async function recordFarmEvents(options = {}) {
+    const recordMetrics = options.metrics !== false;
+    const recordSpanEvents = options.spanEvents !== false;
+    if (!recordMetrics && !recordSpanEvents)
+        return () => { };
+    let subscribe;
+    try {
+        // Imported lazily: `registerOTel` runs from `instrumentation.ts` before the
+        // application loads, so the pre-start module graph stays limited to the SDK,
+        // and a core that cannot be resolved costs telemetry rather than the server.
+        ({ onFarmEvent: subscribe } = await import("@farm.js/core/observability"));
+    }
+    catch (error) {
+        console.warn(`[farm:otel] farm events are unavailable, continuing without them: ${describe(error)}`);
+        return () => { };
+    }
+    let instruments;
+    if (recordMetrics) {
+        try {
+            const provider = options.meterProvider ?? metricsApi.getMeterProvider();
+            instruments = createFarmEventInstruments(provider.getMeter(FARM_EVENTS_METER_NAME));
+        }
+        catch (error) {
+            // A meter provider that cannot hand out instruments must not stop the
+            // server from starting.
+            console.warn(`[farm:otel] failed to create farm metrics, continuing without them: ${describe(error)}`);
+        }
+    }
+    if (!instruments && !recordSpanEvents)
+        return () => { };
+    let warned = false;
+    return subscribe((event) => {
+        try {
+            handleFarmEvent(event, instruments, recordSpanEvents);
+        }
+        catch (error) {
+            // Telemetry must never reach the emitting request. Warn once, because the
+            // failing event families are emitted on hot paths.
+            if (warned)
+                return;
+            warned = true;
+            console.warn(`[farm:otel] failed to record farm events: ${describe(error)}`);
+        }
+    }, 
+    // `observability.events` narrows which events reach application handlers and
+    // logs. Instruments are not a log drain, and Farm already records span
+    // events regardless of that filter, so the mapping stays consistent with it.
+    { unfiltered: true });
+}
+function createFarmEventInstruments(meter) {
+    return {
+        cacheLookups: meter.createCounter("farm.cache.lookups", {
+            description: "Farm cache lookups by outcome.",
+            unit: "{lookup}",
+        }),
+        cacheInvalidations: meter.createCounter("farm.cache.invalidations", {
+            description: "Farm cache invalidation operations by kind.",
+            unit: "{invalidation}",
+        }),
+        cacheInvalidatedEntries: meter.createCounter("farm.cache.invalidated_entries", {
+            description: "Cache entries removed by Farm cache invalidations.",
+            unit: "{entry}",
+        }),
+        pprShellLookups: meter.createCounter("farm.ppr.shell.lookups", {
+            description: "Partial prerender shell lookups by outcome.",
+            unit: "{lookup}",
+        }),
+        pprRefreshDuration: meter.createHistogram("farm.ppr.refresh.duration", {
+            description: "Duration of completed partial prerender shell refreshes.",
+            unit: "ms",
+        }),
+        shellDuration: meter.createHistogram("farm.render.stream.shell.duration", {
+            description: "Time from stream start to streaming shell ready.",
+            unit: "ms",
+        }),
+        middlewareShortCircuits: meter.createCounter("farm.middleware.short_circuits", {
+            description: "Requests answered by middleware before reaching a route.",
+            unit: "{short_circuit}",
+        }),
+    };
+}
+function handleFarmEvent(event, instruments, recordSpanEvents) {
+    const record = event;
+    switch (event.type) {
+        case "cache.hit":
+        case "cache.miss":
+        case "cache.stale":
+        case "cache.dedupe":
+        case "cache.bypass": {
+            const result = CACHE_LOOKUP_RESULTS[event.type];
+            const stale = event.type === "cache.hit" && event.stale === true;
+            const attributes = { "farm.cache.result": result };
+            if (stale)
+                attributes["farm.cache.stale"] = true;
+            instruments?.cacheLookups.add(1, attributes);
+            const span = spanForEvent(event, recordSpanEvents);
+            if (!span)
+                return;
+            const spanAttributes = { ...attributes };
+            copyAttribute(spanAttributes, "farm.route", record.route);
+            copyAttribute(spanAttributes, "farm.pathname", record.pathname);
+            copyAttribute(spanAttributes, "farm.tags", record.tags);
+            copyAttribute(spanAttributes, "farm.reason", record.reason);
+            copyAttribute(spanAttributes, "farm.revalidate", record.revalidate);
+            span.addEvent(event.type, spanAttributes, event.timestamp);
+            return;
+        }
+        case "cache.revalidateTag":
+        case "cache.updateTag":
+        case "cache.revalidatePath":
+        case "cache.invalidated": {
+            const operation = CACHE_INVALIDATION_OPERATIONS[event.type];
+            const attributes = { "farm.cache.operation": operation };
+            instruments?.cacheInvalidations.add(1, attributes);
+            const count = record.count;
+            if (typeof count === "number" && Number.isFinite(count) && count > 0) {
+                instruments?.cacheInvalidatedEntries.add(count, attributes);
+            }
+            const span = spanForEvent(event, recordSpanEvents);
+            if (!span)
+                return;
+            const spanAttributes = { ...attributes };
+            copyAttribute(spanAttributes, "farm.route", record.route);
+            copyAttribute(spanAttributes, "farm.tag", record.tag);
+            copyAttribute(spanAttributes, "farm.path", record.path);
+            copyAttribute(spanAttributes, "farm.reason", record.reason);
+            copyAttribute(spanAttributes, "farm.count", count);
+            span.addEvent(event.type, spanAttributes, event.timestamp);
+            return;
+        }
+        case "ppr.shell.hit":
+        case "ppr.shell.miss":
+        case "ppr.shell.cached":
+        case "ppr.shell.bypass":
+        case "ppr.shell.invalidated": {
+            const result = PPR_SHELL_RESULTS[event.type];
+            const attributes = { "farm.ppr.result": result };
+            instruments?.pprShellLookups.add(1, attributes);
+            const span = spanForEvent(event, recordSpanEvents);
+            if (!span)
+                return;
+            const spanAttributes = { ...attributes };
+            copyAttribute(spanAttributes, "farm.route", record.route);
+            copyAttribute(spanAttributes, "farm.reason", record.reason);
+            copyAttribute(spanAttributes, "farm.revalidate", record.revalidate);
+            copyAttribute(spanAttributes, "farm.count", record.count);
+            span.addEvent(event.type, spanAttributes, event.timestamp);
+            return;
+        }
+        case "ppr.refresh.complete": {
+            instruments?.pprRefreshDuration.record(event.durationMs);
+            const span = spanForEvent(event, recordSpanEvents);
+            if (!span)
+                return;
+            const spanAttributes = { "farm.durationMs": event.durationMs };
+            copyAttribute(spanAttributes, "farm.route", record.route);
+            span.addEvent(event.type, spanAttributes, event.timestamp);
+            return;
+        }
+        case "render.stream.shellReady": {
+            instruments?.shellDuration.record(event.durationMs);
+            const span = spanForEvent(event, recordSpanEvents);
+            if (!span)
+                return;
+            const spanAttributes = { "farm.durationMs": event.durationMs };
+            copyAttribute(spanAttributes, "farm.route", record.route);
+            span.addEvent(event.type, spanAttributes, event.timestamp);
+            return;
+        }
+        case "middleware.shortCircuit": {
+            const attributes = {};
+            // A middleware `route` is the configured matcher, not the request path,
+            // so unlike every other family here it is bounded by the application's
+            // own middleware list and is safe to keep on the counter.
+            copyAttribute(attributes, "farm.route", record.route);
+            const statusClass = toStatusClass(event.status);
+            if (statusClass)
+                attributes["farm.http.status_class"] = statusClass;
+            instruments?.middlewareShortCircuits.add(1, attributes);
+            const span = spanForEvent(event, recordSpanEvents);
+            if (!span)
+                return;
+            const spanAttributes = { ...attributes };
+            copyAttribute(spanAttributes, "farm.pathname", record.pathname);
+            copyAttribute(spanAttributes, "farm.name", record.name);
+            copyAttribute(spanAttributes, "farm.status", event.status);
+            span.addEvent(event.type, spanAttributes, event.timestamp);
+            return;
+        }
+        default:
+            return;
+    }
+}
+/**
+ * The span a mapped event should be recorded on, if any. Resolved before the
+ * attributes are collected so the common case, an event emitted with no
+ * recording span active, costs nothing.
+ */
+function spanForEvent(event, recordSpanEvents) {
+    if (!recordSpanEvents)
+        return undefined;
+    // Farm's own tracing layer already writes every event onto the active span
+    // when `observability.tracing` is enabled, and stamps the event with the span
+    // it recorded against. Adding a second copy here would duplicate the trace.
+    if (event.spanId)
+        return undefined;
+    const span = trace.getActiveSpan();
+    return span?.isRecording() ? span : undefined;
+}
+function copyAttribute(target, name, value) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        target[name] = value;
+        return;
+    }
+    if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+        target[name] = [...value];
+    }
+}
+function toStatusClass(status) {
+    if (typeof status !== "number" || !Number.isFinite(status))
+        return undefined;
+    if (status < 100 || status > 599)
+        return undefined;
+    return `${Math.floor(status / 100)}xx`;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/index.d.ts

@@ -1,10 +1,13 @@
-import type { Attributes } from "@opentelemetry/api";
+import { type Attributes } from "@opentelemetry/api";
 import { type InstrumentationConfigMap } from "@opentelemetry/auto-instrumentations-node";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import type { Instrumentation } from "@opentelemetry/instrumentation";
 import { type Resource } from "@opentelemetry/resources";
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { type Sampler, type SpanExporter, type SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { type FarmEventMappingOptions } from "./farm-events.js";
+export { FARM_EVENTS_METER_NAME, recordFarmEvents } from "./farm-events.js";
+export type { FarmEventMappingOptions } from "./farm-events.js";
 export interface FarmOTelOptions {
     serviceName?: string;
     serviceVersion?: string;
@@ -17,6 +20,22 @@ export interface FarmOTelOptions {
     autoInstrumentations?: boolean;
     instrumentationConfig?: InstrumentationConfigMap;
     instrumentations?: Array<Instrumentation | Instrumentation[]>;
+    /**
+     * Metric readers to export with. Farm registers a meter provider only when
+     * this is set or `OTEL_METRICS_EXPORTER` names an exporter, so an app that
+     * only asked for traces never gets a metrics pipeline it did not configure.
+     */
+    metricReaders?: NonNullable<ConstructorParameters<typeof NodeSDK>[0]>["metricReaders"];
+    /**
+     * Record Farm's own cache, PPR, streaming and middleware events as metrics
+     * and span events. Enabled by default; auto-instrumentation only sees generic
+     * HTTP, filesystem and database work, so without this everything the
+     * framework knows about itself is dropped.
+     *
+     * Pass `false` to leave Farm's event bus unsubscribed, or an object to record
+     * only metrics or only span events.
+     */
+    farmEvents?: boolean | FarmEventMappingOptions;
 }
 export interface FarmOTelController {
     sdk: NodeSDK;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAA0B,KAAK,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,+BAA+B,CAAC;AAGvC,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,kBAAkB,CAAC,EAAE,UAAU,CAAC;IAChC,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,EAAE,qBAAqB,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,qBAAqB,CAAC,EAAE,wBAAwB,CAAC;IACjD,gBAAgB,CAAC,EAAE,KAAK,CAAC,eAAe,GAAG,eAAe,EAAE,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,OAAO,CAAC;IACb,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAgBD,wBAAsB,YAAY,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsD7F;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAIpD;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAIlD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAA0B,KAAK,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAoB,KAAK,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAElF,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC5E,YAAY,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAEhE,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,kBAAkB,CAAC,EAAE,UAAU,CAAC;IAChC,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,EAAE,qBAAqB,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,qBAAqB,CAAC,EAAE,wBAAwB,CAAC;IACjD,gBAAgB,CAAC,EAAE,KAAK,CAAC,eAAe,GAAG,eAAe,EAAE,CAAC,CAAC;IAC9D;;;;OAIG;IACH,aAAa,CAAC,EAAE,WAAW,CAAC,qBAAqB,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;IACvF;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAAC;CAChD;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,OAAO,CAAC;IACb,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAwBD,wBAAsB,YAAY,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAqG7F;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAIpD;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAIlD"}

package/dist/index.js

@@ -1,14 +1,24 @@
+import { metrics } from "@opentelemetry/api";
 import { getNodeAutoInstrumentations, } from "@opentelemetry/auto-instrumentations-node";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace-base";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+import { recordFarmEvents } from "./farm-events.js";
+export { FARM_EVENTS_METER_NAME, recordFarmEvents } from "./farm-events.js";
 const FARM_OTEL_STATE = Symbol.for("@farm.js/otel/state");
 function getGlobalState() {
     const target = globalThis;
     return (target[FARM_OTEL_STATE] ??= {});
 }
+function resolveFarmEventOptions(option) {
+    if (option === false)
+        return undefined;
+    if (option === undefined || option === true)
+        return {};
+    return option;
+}
 export async function registerOTel(options = {}) {
     const state = getGlobalState();
     if (state.controller)
@@ -16,7 +26,7 @@ export async function registerOTel(options = {}) {
     if (state.initializing)
         return state.initializing;
     state.initializing = Promise.resolve()
-        .then(() => {
+        .then(async () => {
         const defaultResource = resourceFromAttributes({
             [ATTR_SERVICE_NAME]: options.serviceName ?? process.env.OTEL_SERVICE_NAME ?? "farm-app",
             ...(options.serviceVersion ? { [ATTR_SERVICE_VERSION]: options.serviceVersion } : {}),
@@ -30,21 +40,61 @@ export async function registerOTel(options = {}) {
             (options.autoInstrumentations === false
                 ? []
                 : [getNodeAutoInstrumentations(options.instrumentationConfig)]);
+        // Left unset, the Node SDK falls back to a periodic OTLP metrics pipeline
+        // pointed at localhost:4318. With nothing listening there, the first
+        // recorded metric turns graceful shutdown into the exporter's retry window
+        // (measured at ~8s), and farm's production lifecycle waits on
+        // instrumentation shutdown, so that is a stalled deploy.
+        //
+        // An empty reader list keeps the meter provider unregistered, which turns
+        // metrics off entirely, so it may only be the default when the app has
+        // pointed nothing at a collector. `OTEL_METRICS_EXPORTER` alone is not that
+        // signal: the spec already defaults it to `otlp`, so the ordinary
+        // production posture is to set an endpoint and leave the exporter variable
+        // alone. Treat any configured OTLP metrics destination as the opt-in, and
+        // leave `OTEL_METRICS_EXPORTER=none` as the documented way to turn metrics
+        // off.
+        const metricsDestinationConfigured = Boolean(process.env.OTEL_METRICS_EXPORTER ||
+            process.env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT ||
+            process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
+        const metricReaders = options.metricReaders ?? (metricsDestinationConfigured ? undefined : []);
         const sdk = new NodeSDK({
             resource,
             sampler: options.sampler,
             spanProcessors,
             instrumentations,
+            metricReaders,
         });
         sdk.start();
+        // After `start`, because the metrics API has no proxy provider: an
+        // instrument created before the SDK registers its meter provider stays a
+        // no-op for the life of the process.
+        const farmEventOptions = resolveFarmEventOptions(options.farmEvents);
+        const disposeFarmEvents = farmEventOptions
+            ? await recordFarmEvents(farmEventOptions)
+            : undefined;
         let shutdownPromise;
         const controller = {
             sdk,
             async forceFlush() {
                 await Promise.all(spanProcessors.map((processor) => processor.forceFlush()));
+                // Serverless runtimes freeze the process between requests, so the
+                // periodic metric reader never gets to export on its own. The API type
+                // has no `forceFlush`, so reach for the SDK's when it is there.
+                const meterProvider = metrics.getMeterProvider();
+                try {
+                    await meterProvider.forceFlush?.();
+                }
+                catch (error) {
+                    // A metrics exporter must not fail the response it was flushed for.
+                    console.warn(`[farm:otel] metric flush failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
             },
             shutdown() {
                 if (!shutdownPromise) {
+                    // Stop feeding instruments before the providers go away, and so a
+                    // development restart does not stack bus subscribers.
+                    disposeFarmEvents?.();
                     shutdownPromise = sdk.shutdown().finally(() => {
                         state.controller = undefined;
                         state.initializing = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farm.js/otel",
-  "version": "0.1.0-beta.25",
+  "version": "0.1.0-beta.27",
   "description": "OpenTelemetry SDK setup for Farm.js applications",
   "license": "MIT",
   "repository": {
@@ -33,14 +33,15 @@
     "@opentelemetry/resources": "2.10.0",
     "@opentelemetry/sdk-node": "0.221.0",
     "@opentelemetry/sdk-trace-base": "2.10.0",
-    "@opentelemetry/semantic-conventions": "1.43.0"
+    "@opentelemetry/semantic-conventions": "1.43.0",
+    "@farm.js/core": "0.1.0-beta.107"
   },
   "devDependencies": {
     "@types/node": "^20.10.5",
     "typescript": "^5.3.3"
   },
   "engines": {
-    "node": ">=20.6.0"
+    "node": ">=22.13.0"
   },
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",