@friggframework/core 2.0.0-next.11 → 2.0.0-next.110

package/telemetry/otel-telemetry.js

@@ -0,0 +1,213 @@
+const otelApi = require('@opentelemetry/api');
+const {
+    BasicTracerProvider,
+    BatchSpanProcessor,
+    ParentBasedSampler,
+    TraceIdRatioBasedSampler,
+    AlwaysOnSampler,
+} = require('@opentelemetry/sdk-trace-base');
+const {
+    MeterProvider,
+    PeriodicExportingMetricReader,
+} = require('@opentelemetry/sdk-metrics');
+const { resourceFromAttributes } = require('@opentelemetry/resources');
+const { resolveExporter } = require('./exporters');
+const { createTelemetryEventBus } = require('./telemetry-event-bus');
+const {
+    runWithTelemetryContext,
+    mergeTelemetryContext,
+} = require('./telemetry-context');
+
+const TRACER_NAME = 'frigg';
+const METRIC_EXPORT_INTERVAL_MS =
+    Number(process.env.OTEL_METRIC_EXPORT_INTERVAL_MS) || 60000;
+
+/**
+ * Register an AsyncLocalStorage-backed OTel context manager once per process.
+ * Without it `BasicTracerProvider` uses the Noop context manager, so
+ * `startActiveSpan` never sets an active context — spans would be unparented
+ * roots, `getActiveSpan()` always undefined, and baggage inert. Guarded so
+ * repeated telemetry construction (tests) doesn't re-register.
+ */
+let contextManagerRegistered = false;
+function ensureContextManager() {
+    if (contextManagerRegistered) return;
+    contextManagerRegistered = true;
+    try {
+        const {
+            AsyncLocalStorageContextManager,
+        } = require('@opentelemetry/context-async-hooks');
+        const manager = new AsyncLocalStorageContextManager();
+        manager.enable();
+        otelApi.context.setGlobalContextManager(manager);
+    } catch (_) {
+        // If registration fails, traces are flat but usage attribution (which
+        // rides the separate telemetry-context ALS) is unaffected.
+    }
+}
+
+/**
+ * OpenTelemetry-backed telemetry adapter. Constructed only when a real exporter
+ * is configured (`createTelemetry` returns the no-op otherwise). `BatchSpanProcessor`
+ * is used uniformly — spans are delivered by the bounded `forceFlush()` the Lambda
+ * handler awaits before the container freezes (`callbackWaitsForEmptyEventLoop=false`),
+ * never by background timers.
+ */
+class OtelTelemetry {
+    constructor({
+        exporter,
+        resource = {},
+        sampleRatio,
+        bus = createTelemetryEventBus(),
+    } = {}) {
+        ensureContextManager();
+        const { traceExporter, metricExporter } = resolveExporter(exporter);
+
+        const resourceAttrs = { 'service.name': resource.service || 'frigg' };
+        if (resource.stage) {
+            resourceAttrs['deployment.environment'] = resource.stage;
+            resourceAttrs.stage = resource.stage;
+        }
+        if (resource.appName) resourceAttrs.appName = resource.appName;
+        const res = resourceFromAttributes(resourceAttrs);
+
+        const sampler =
+            typeof sampleRatio === 'number' && sampleRatio < 1
+                ? new ParentBasedSampler({
+                      root: new TraceIdRatioBasedSampler(sampleRatio),
+                  })
+                : new AlwaysOnSampler();
+
+        this._tracerProvider = new BasicTracerProvider({
+            resource: res,
+            sampler,
+            spanProcessors: traceExporter
+                ? [new BatchSpanProcessor(traceExporter)]
+                : [],
+        });
+
+        const metricReader = metricExporter
+            ? new PeriodicExportingMetricReader({
+                  exporter: metricExporter,
+                  exportIntervalMillis: METRIC_EXPORT_INTERVAL_MS,
+              })
+            : null;
+        this._meterProvider = new MeterProvider({
+            resource: res,
+            readers: metricReader ? [metricReader] : [],
+        });
+
+        this._bus = bus;
+        this._tracer = this._tracerProvider.getTracer(TRACER_NAME);
+        this._meter = this._meterProvider.getMeter(TRACER_NAME);
+        // One instrument instance per metric name — OTel requires it, and
+        // re-creating a counter would drop data points.
+        this._counters = new Map();
+    }
+
+    _getCounter(name) {
+        if (!this._counters.has(name)) {
+            this._counters.set(name, this._meter.createCounter(name));
+        }
+        return this._counters.get(name);
+    }
+
+    count(name, value = 1, attributes = {}, context) {
+        try {
+            this._getCounter(name).add(value, attributes);
+        } catch (_) {
+            // Telemetry must never break the wrapped path.
+        }
+        // Mirror onto the internal stream for the usage rollup + plugin taps; the
+        // bus context (incl. high-cardinality ids) rides the bus only, never the
+        // OTel metric attributes.
+        const merged = mergeTelemetryContext(context);
+        const payload = { name, value, attributes };
+        if (merged) payload.context = merged;
+        this._bus.emit('metric', payload);
+    }
+
+    event(name, attributes = {}, context) {
+        try {
+            const active = otelApi.trace.getActiveSpan();
+            if (active) active.addEvent(name, attributes);
+        } catch (_) {}
+        const merged = mergeTelemetryContext(context);
+        const payload = { name, attributes };
+        if (merged) payload.context = merged;
+        this._bus.emit('event', payload);
+    }
+
+    startSpan(name, options) {
+        return this._tracer.startSpan(name, options);
+    }
+
+    async span(name, fn, options = {}) {
+        return this._tracer.startActiveSpan(name, options, async (span) => {
+            try {
+                const result =
+                    typeof fn === 'function' ? await fn(span) : undefined;
+                span.setStatus({ code: otelApi.SpanStatusCode.OK });
+                return result;
+            } catch (err) {
+                span.recordException(err);
+                span.setStatus({
+                    code: otelApi.SpanStatusCode.ERROR,
+                    message: err && err.message,
+                });
+                throw err;
+            } finally {
+                span.end();
+            }
+        });
+    }
+
+    /**
+     * Run `fn` with the given identifiers on (a) the AsyncLocalStorage telemetry
+     * context — which the usage rollup reads to attribute emissions per-integration
+     * on ANY path — and (b) OTel baggage for trace propagation. High-cardinality
+     * ids ride here, never on metric labels.
+     */
+    async withContext(attributes = {}, fn) {
+        const entries = {};
+        for (const [key, value] of Object.entries(attributes)) {
+            if (value !== undefined && value !== null) {
+                entries[key] = { value: String(value) };
+            }
+        }
+        const baggage = otelApi.propagation.createBaggage(entries);
+        const ctx = otelApi.propagation.setBaggage(
+            otelApi.context.active(),
+            baggage
+        );
+        return runWithTelemetryContext(attributes, () =>
+            otelApi.context.with(ctx, () =>
+                typeof fn === 'function' ? fn() : undefined
+            )
+        );
+    }
+
+    on(eventType, callback) {
+        return this._bus.on(eventType, callback);
+    }
+
+    async forceFlush() {
+        await Promise.allSettled([
+            this._tracerProvider.forceFlush(),
+            this._meterProvider.forceFlush(),
+        ]);
+    }
+
+    async shutdown() {
+        await Promise.allSettled([
+            this._tracerProvider.shutdown(),
+            this._meterProvider.shutdown(),
+        ]);
+    }
+
+    isEnabled() {
+        return true;
+    }
+}
+
+module.exports = { OtelTelemetry };

package/telemetry/plugin-subscribers.js

@@ -0,0 +1,77 @@
+/**
+ * Declarative plugin/extension telemetry taps.
+ *
+ * The built-in usage rollup and North Star derivation subscribe to the telemetry
+ * bus in framework code; this lets an ADOPTER subscribe declaratively from the
+ * app definition (`Definition.telemetry.subscribers: [...]`) — forward to a
+ * custom sink, compute aggregates, persist counters — without writing wiring code.
+ *
+ * A subscriber is one of:
+ *   - a **factory** `fn(telemetry)` that registers itself (e.g. calls
+ *     `telemetry.on('metric', ...)`) and MAY return an unsubscribe function; or
+ *   - a **declarative object** `{ event?: 'metric'|'event', handler(payload, eventType) }`
+ *     — when `event` is omitted the handler receives both metric and event payloads.
+ *
+ * Every attach and every handler invocation is guarded so a misbehaving
+ * subscriber can never break emission, its siblings, or a handler (mirrors the
+ * bus's own per-subscriber isolation).
+ *
+ * @param {object} params
+ * @param {object} params.telemetry Telemetry service exposing `on(eventType, cb)`.
+ * @param {Array<Function|{event?: string, handler: Function}>} [params.subscribers]
+ * @returns {Array<Function>} unsubscribe functions for the wired subscribers.
+ */
+const EVENT_TYPES = ['metric', 'event'];
+
+function wireTelemetrySubscribers({ telemetry, subscribers = [] } = {}) {
+    if (
+        !telemetry ||
+        typeof telemetry.on !== 'function' ||
+        !Array.isArray(subscribers)
+    ) {
+        return [];
+    }
+
+    const unsubscribes = [];
+
+    for (const subscriber of subscribers) {
+        try {
+            if (typeof subscriber === 'function') {
+                const off = subscriber(telemetry);
+                if (typeof off === 'function') unsubscribes.push(off);
+                continue;
+            }
+
+            if (subscriber && typeof subscriber.handler === 'function') {
+                const events = subscriber.event
+                    ? [subscriber.event]
+                    : EVENT_TYPES;
+                for (const eventType of events) {
+                    const off = telemetry.on(eventType, (payload) => {
+                        try {
+                            subscriber.handler(payload, eventType);
+                        } catch (error) {
+                            console.warn(
+                                `[Frigg][telemetry] subscriber handler for "${eventType}" threw: ${
+                                    error && error.message
+                                }`
+                            );
+                        }
+                    });
+                    if (typeof off === 'function') unsubscribes.push(off);
+                }
+            }
+        } catch (error) {
+            // A single bad subscriber must never break wiring of the others.
+            console.warn(
+                `[Frigg][telemetry] failed to wire a telemetry subscriber: ${
+                    error && error.message
+                }`
+            );
+        }
+    }
+
+    return unsubscribes;
+}
+
+module.exports = { wireTelemetrySubscribers };

package/telemetry/telemetry-config.js

@@ -0,0 +1,120 @@
+/**
+ * Resolves and validates the telemetry section of an app definition
+ * into a normalized config the TelemetryService and
+ * usage rollup consume: `{ exporter, northStar, sampleRatio }`.
+ *
+ * Exporter default is keyed off STAGE: only a genuinely LOCAL run (STAGE=local)
+ * gets `console` (visible, free); every deployed stage — including `dev` —
+ * defaults to `none`. `dev` is a deployed AWS stage, and `console` there would
+ * write full spans to CloudWatch by default (cost + a data-exposure surface).
+ * Adopters opt into `console`/`otlp` explicitly for deployed stages.
+ */
+const VALID_EXPORTER_TYPES = [
+    'none',
+    'noop',
+    'console',
+    'otlp',
+    'honeycomb',
+    'datadog',
+];
+
+function normalizeExporterConfig(exporter, stage) {
+    if (!exporter) {
+        return stage === 'local' ? { type: 'console' } : { type: 'none' };
+    }
+
+    // Pre-built exporter instances (tests / advanced adopters) bypass type checks.
+    if (exporter.traceExporter || exporter.metricExporter) {
+        return exporter;
+    }
+
+    if (!VALID_EXPORTER_TYPES.includes(exporter.type)) {
+        throw new Error(
+            `[Frigg][telemetry] invalid exporter type "${exporter.type}". ` +
+                `Supported: ${VALID_EXPORTER_TYPES.join(', ')}`
+        );
+    }
+    return exporter;
+}
+
+// Fraction of TRACES exported (0..1, default 1) — a cost knob wired to the OTel
+// sampler in otel-telemetry. Does NOT thin usage counters; those stay exact.
+function resolveSampleRatio(sampleRatio) {
+    if (sampleRatio === undefined || sampleRatio === null) return 1;
+    if (
+        typeof sampleRatio !== 'number' ||
+        Number.isNaN(sampleRatio) ||
+        sampleRatio < 0 ||
+        sampleRatio > 1
+    ) {
+        throw new Error(
+            `[Frigg][telemetry] sampleRatio must be a number in [0,1], got ${sampleRatio}`
+        );
+    }
+    return sampleRatio;
+}
+
+function validateNorthStarEntry(entry, where) {
+    if (!entry || typeof entry.name !== 'string' || !entry.name) {
+        throw new Error(
+            `[Frigg][telemetry] northStar.${where} must reference a counter { name }`
+        );
+    }
+}
+
+/**
+ * Adopter-declared telemetry subscribers. Each is either a factory
+ * function `fn(telemetry)` or a declarative `{ event?, handler }` object. Kept as
+ * an array so `wireTelemetrySubscribers` can attach them to the bus at runtime.
+ */
+function resolveSubscribers(subscribers) {
+    if (subscribers === undefined || subscribers === null) return [];
+    if (!Array.isArray(subscribers)) {
+        throw new Error(
+            '[Frigg][telemetry] subscribers must be an array of functions or { handler } objects'
+        );
+    }
+    for (const subscriber of subscribers) {
+        const ok =
+            typeof subscriber === 'function' ||
+            (subscriber && typeof subscriber.handler === 'function');
+        if (!ok) {
+            throw new Error(
+                '[Frigg][telemetry] each subscriber must be a function or an object with a handler function'
+            );
+        }
+    }
+    return subscribers;
+}
+
+function resolveNorthStar(northStar) {
+    if (!northStar) return null;
+    if (northStar.default) validateNorthStarEntry(northStar.default, 'default');
+    if (northStar.byType) {
+        for (const [type, entry] of Object.entries(northStar.byType)) {
+            validateNorthStarEntry(entry, `byType.${type}`);
+        }
+    }
+    return northStar;
+}
+
+/**
+ * @param {object} appDefinition The backend `Definition` export.
+ * @param {object} [ctx]
+ * @param {string} [ctx.stage] Deployment stage (defaults to STAGE/NODE_ENV).
+ * @returns {{ exporter: object, northStar: object|null, sampleRatio: number }}
+ */
+function resolveTelemetryConfig(appDefinition = {}, ctx = {}) {
+    const stage =
+        ctx.stage || process.env.STAGE || process.env.NODE_ENV || 'production';
+    const telemetry = appDefinition.telemetry || {};
+
+    return {
+        exporter: normalizeExporterConfig(telemetry.exporter, stage),
+        northStar: resolveNorthStar(telemetry.northStar),
+        sampleRatio: resolveSampleRatio(telemetry.sampleRatio),
+        subscribers: resolveSubscribers(telemetry.subscribers),
+    };
+}
+
+module.exports = { resolveTelemetryConfig };

package/telemetry/telemetry-context.js

@@ -0,0 +1,40 @@
+const { AsyncLocalStorage } = require('node:async_hooks');
+
+/**
+ * Ambient telemetry context. A single process-wide AsyncLocalStorage
+ * holds the standard identifiers ({integrationId, integrationType, userId,
+ * version, ...}) for the duration of a handler, set once at the handler seam via
+ * `telemetry.withContext(...)`. Any emission during that async scope — including
+ * deep calls like an API-module request — reads the ambient context, so the
+ * usage rollup can attribute counters per-integration WITHOUT threading context
+ * through every call and WITHOUT relying on OTel baggage (which does not exist
+ * on the no-op path). This is the propagation mechanism the plan intended.
+ *
+ * Only bus-payload `context` is populated from here; high-cardinality ids never
+ * touch OTel metric labels.
+ */
+const store = new AsyncLocalStorage();
+
+function runWithTelemetryContext(context, fn) {
+    return store.run(context || {}, fn);
+}
+
+function getTelemetryContextStore() {
+    return store.getStore() || null;
+}
+
+/**
+ * Merge the ambient context with an explicit per-call context (explicit keys
+ * win, e.g. a request `url`). Returns undefined when there is nothing to attach.
+ */
+function mergeTelemetryContext(explicit) {
+    const ambient = store.getStore();
+    if (!ambient && !explicit) return undefined;
+    return { ...(ambient || {}), ...(explicit || {}) };
+}
+
+module.exports = {
+    runWithTelemetryContext,
+    getTelemetryContextStore,
+    mergeTelemetryContext,
+};

package/telemetry/telemetry-event-bus.js

@@ -0,0 +1,58 @@
+/**
+ * TelemetryEventBus — the internal event stream telemetry flows onto.
+ * Plugins/extensions and the built-in usage rollup
+ * subscribe here; it is deliberately independent of OTel export (Decision 7),
+ * so usage counters persist even when the OTel exporter is a no-op.
+ *
+ * This is intentionally a **synchronous** in-process fan-out (Frigg runs one
+ * invocation per Lambda container): a plain subscriber list with per-subscriber
+ * `try/catch` so a misbehaving subscriber can never break emission or its
+ * siblings. No queue/backpressure machinery — emission volume is bounded by a
+ * single invocation's work.
+ *
+ * ## Public event contract (semver-stable)
+ * Event types and their payload shapes:
+ *   - `'metric'` → `{ name: string, value: number, attributes: object, context?: object }`
+ *   - `'event'`  → `{ name: string, attributes: object, context?: object }`
+ * `attributes` are the bounded OTel metric labels. `context` (present when an
+ * ambient telemetry context is active) carries the high-cardinality identifiers
+ * — {integrationId, integrationType, userId, version, ...} plus per-call extras
+ * like a request `url` — which the usage rollup reads for attribution. Those ids
+ * NEVER appear in `attributes` (Cardinality note).
+ */
+function createTelemetryEventBus() {
+    /** @type {Map<string, Set<Function>>} */
+    const subscribers = new Map();
+
+    function on(eventType, callback) {
+        if (!subscribers.has(eventType)) {
+            subscribers.set(eventType, new Set());
+        }
+        const set = subscribers.get(eventType);
+        set.add(callback);
+        return function off() {
+            set.delete(callback);
+        };
+    }
+
+    function emit(eventType, payload) {
+        const set = subscribers.get(eventType);
+        if (!set || set.size === 0) return;
+        for (const callback of set) {
+            try {
+                callback(payload);
+            } catch (error) {
+                // A subscriber must never break emission or its siblings.
+                console.warn(
+                    `[Frigg][telemetry] subscriber for "${eventType}" threw: ${
+                        error && error.message
+                    }`
+                );
+            }
+        }
+    }
+
+    return { on, emit };
+}
+
+module.exports = { createTelemetryEventBus };

package/telemetry/telemetry-runtime.js

@@ -0,0 +1,147 @@
+// The process composition root for telemetry: one shared state, per-part lazy
+// getters, one atomic reset — replacing three separate singleton module caches
+// (telemetry / usage-rollup / plugin-subscribers) that previously had to be
+// reset together in the right order. Bus identity across the parts is guaranteed
+// by construction: the rollup and plugin subscribers attach to the same
+// getTelemetry() instance reached through this module's own closure.
+
+const { createTelemetry } = require('./telemetry-service');
+const { NoOpTelemetry } = require('./no-op-telemetry');
+
+const UNSET = Symbol('unset');
+
+function newState() {
+    return { telemetry: null, usageRollup: UNSET, pluginSubscribers: UNSET };
+}
+let state = newState();
+
+function loadTelemetryConfig() {
+    // Lazy-required to avoid a load-time cycle with the handlers layer.
+    const { loadAppDefinition } = require('../handlers/app-definition-loader');
+    return loadAppDefinition();
+}
+
+/**
+ * The process telemetry service. Created lazily on first use and reused for the
+ * life of the Lambda container, so the OTel SDK initialises at most once per cold
+ * start. Never throws — any failure falls back to the no-op.
+ */
+function getTelemetry() {
+    if (state.telemetry) return state.telemetry;
+    try {
+        const { telemetry = {} } = loadTelemetryConfig();
+        const stage = process.env.STAGE || process.env.NODE_ENV || 'production';
+        state.telemetry = createTelemetry({
+            exporter: telemetry.exporter,
+            sampleRatio: telemetry.sampleRatio,
+            resource: { service: process.env.FRIGG_STACK || 'frigg', stage },
+        });
+    } catch (_) {
+        state.telemetry = new NoOpTelemetry();
+    }
+    return state.telemetry;
+}
+
+/**
+ * The process usage-rollup subscriber, wired to getTelemetry()'s bus. Returns
+ * null when usage is disabled (no Definition.usage opt-in and no North Star) or
+ * the app definition can't load. Never throws — the warn lets operators tell
+ * "usage off" from "usage broken" (e.g. unresolved DB_TYPE).
+ */
+function getUsageRollupSubscriber() {
+    if (state.usageRollup !== UNSET) return state.usageRollup;
+    state.usageRollup = null;
+    try {
+        const { computeTrackedMetrics } = require('../usage/tracked-metrics');
+        const {
+            northStarKeys,
+            createNorthStarDerivationSubscriber,
+        } = require('./north-star');
+        const { integrations = [], telemetry = {} } = loadTelemetryConfig();
+
+        // Track both Definition.usage opt-ins and any North Star counter keys,
+        // so a derived North Star persists even without an explicit usage decl.
+        const trackedMetrics = computeTrackedMetrics(integrations);
+        for (const key of northStarKeys(telemetry.northStar)) {
+            trackedMetrics.add(key);
+        }
+        if (trackedMetrics.size === 0) return state.usageRollup;
+
+        const {
+            createUsageRepository,
+        } = require('../usage/repositories/usage-repository-factory');
+        const {
+            createUsageRollupSubscriber,
+        } = require('./usage-rollup-subscriber');
+        const telemetryService = getTelemetry(); // same memo → shared bus
+
+        state.usageRollup = createUsageRollupSubscriber({
+            telemetry: telemetryService,
+            usageRepository: createUsageRepository(),
+            trackedMetrics,
+        });
+
+        // North Star derived-from-trace: emits the North Star counter when a
+        // configured signal matches; the emission flows to the rollup above.
+        if (telemetry.northStar) {
+            createNorthStarDerivationSubscriber({
+                telemetry: telemetryService,
+                northStar: telemetry.northStar,
+            });
+        }
+    } catch (error) {
+        console.warn(
+            `[Frigg][usage] rollup disabled: ${error && error.message}`
+        );
+        state.usageRollup = null;
+    }
+    return state.usageRollup;
+}
+
+/**
+ * Adopter-declared telemetry subscribers, wired to getTelemetry()'s bus once per
+ * cold start. Independent of the usage rollup (adopter taps wire even when no
+ * integration declares Definition.usage). Never throws.
+ */
+function getPluginTelemetrySubscribers() {
+    if (state.pluginSubscribers !== UNSET) return state.pluginSubscribers;
+    state.pluginSubscribers = [];
+    try {
+        const { wireTelemetrySubscribers } = require('./plugin-subscribers');
+        const { telemetry = {} } = loadTelemetryConfig();
+        const subscribers = telemetry.subscribers || [];
+        if (subscribers.length === 0) return state.pluginSubscribers;
+
+        state.pluginSubscribers = wireTelemetrySubscribers({
+            telemetry: getTelemetry(),
+            subscribers,
+        });
+    } catch (error) {
+        console.warn(
+            `[Frigg][telemetry] plugin subscribers disabled: ${
+                error && error.message
+            }`
+        );
+        state.pluginSubscribers = [];
+    }
+    return state.pluginSubscribers;
+}
+
+/** Test-only: reset the whole runtime — no stale cross-memo states possible. */
+function resetTelemetryRuntimeForTests() {
+    state = newState();
+}
+
+/** Test-only: install a telemetry service; dependent memos clear atomically. */
+function setTelemetryForTests(telemetry) {
+    state = newState();
+    state.telemetry = telemetry;
+}
+
+module.exports = {
+    getTelemetry,
+    getUsageRollupSubscriber,
+    getPluginTelemetrySubscribers,
+    resetTelemetryRuntimeForTests,
+    setTelemetryForTests,
+};