@friggframework/core 2.0.0--canary.622.faffe5f.0 → 2.0.0--canary.623.71305f2.0

package/telemetry/exporters/exporter-factory.js

@@ -1,79 +0,0 @@
-/**
- * Builds OpenTelemetry span/metric exporters from an app-definition descriptor.
- * All OTel packages are lazy-`require`d here so the no-op
- * path (which never calls this) loads zero OTel modules.
- *
- * Supported descriptor `type`s:
- *   - 'console'            → ConsoleSpanExporter / ConsoleMetricExporter (local dev)
- *   - 'otlp'               → OTLP/HTTP to descriptor.endpoint (+ headers)
- *   - 'honeycomb'          → OTLP preset (api.honeycomb.io, x-honeycomb-team header)
- *   - 'datadog'            → OTLP preset (descriptor.endpoint required)
- *
- * A descriptor may also carry pre-built exporter instances
- * (`traceExporter` / `metricExporter`) — used by tests (in-memory exporters) and
- * advanced adopters. Instances win over `type`.
- *
- * @returns {{ traceExporter: object|null, metricExporter: object|null }}
- */
-function buildExporters(descriptor = {}) {
-    if (descriptor.traceExporter || descriptor.metricExporter) {
-        return {
-            traceExporter: descriptor.traceExporter || null,
-            metricExporter: descriptor.metricExporter || null,
-        };
-    }
-
-    const type = descriptor.type;
-
-    if (type === 'console') {
-        const {
-            ConsoleSpanExporter,
-        } = require('@opentelemetry/sdk-trace-base');
-        const { ConsoleMetricExporter } = require('@opentelemetry/sdk-metrics');
-        return {
-            traceExporter: new ConsoleSpanExporter(),
-            metricExporter: new ConsoleMetricExporter(),
-        };
-    }
-
-    const { endpoint, headers } = resolveOtlpTarget(descriptor);
-    const {
-        OTLPTraceExporter,
-    } = require('@opentelemetry/exporter-trace-otlp-http');
-    const {
-        OTLPMetricExporter,
-    } = require('@opentelemetry/exporter-metrics-otlp-http');
-
-    // When no endpoint is set the exporters fall back to the standard
-    // OTEL_EXPORTER_OTLP_ENDPOINT env var, so leave `url` undefined in that case.
-    return {
-        traceExporter: new OTLPTraceExporter({
-            ...(endpoint ? { url: joinPath(endpoint, '/v1/traces') } : {}),
-            ...(headers ? { headers } : {}),
-        }),
-        metricExporter: new OTLPMetricExporter({
-            ...(endpoint ? { url: joinPath(endpoint, '/v1/metrics') } : {}),
-            ...(headers ? { headers } : {}),
-        }),
-    };
-}
-
-/** Resolve endpoint + headers for OTLP and its vendor presets. */
-function resolveOtlpTarget(descriptor) {
-    if (descriptor.type === 'honeycomb') {
-        return {
-            endpoint: descriptor.endpoint || 'https://api.honeycomb.io',
-            headers: descriptor.apiKey
-                ? { 'x-honeycomb-team': descriptor.apiKey }
-                : descriptor.headers,
-        };
-    }
-    // 'otlp' and 'datadog' both use a plain OTLP endpoint + optional headers.
-    return { endpoint: descriptor.endpoint, headers: descriptor.headers };
-}
-
-function joinPath(base, path) {
-    return `${String(base).replace(/\/$/, '')}${path}`;
-}
-
-module.exports = { buildExporters };

package/telemetry/index.js

@@ -1,56 +0,0 @@
-const { createTelemetry, isNoOpExporter } = require('./telemetry-service');
-const { createNoOpTelemetry } = require('./no-op-telemetry');
-const { createTelemetryEventBus } = require('./telemetry-event-bus');
-const { resolveTelemetryConfig } = require('./telemetry-config');
-const {
-    getTelemetry,
-    resetTelemetryForTests,
-} = require('./telemetry-singleton');
-const { buildExporters } = require('./exporters/exporter-factory');
-const { instrumentHandler } = require('./instrument-handler');
-const { bindTelemetryContext } = require('./bind-telemetry-context');
-const { createUsageRollupSubscriber } = require('./usage-rollup-subscriber');
-const {
-    getUsageRollupSubscriber,
-    resetUsageRollupForTests,
-} = require('./usage-rollup-singleton');
-const { computeUsageWindows } = require('./usage-windows');
-const {
-    resolveNorthStarEntry,
-    northStarKeys,
-    createNorthStarDerivationSubscriber,
-} = require('./north-star');
-const {
-    CANONICAL_COUNTERS,
-    isCanonicalCounter,
-} = require('./canonical-counters');
-const { wireTelemetrySubscribers } = require('./plugin-subscribers');
-const {
-    getPluginTelemetrySubscribers,
-    resetPluginTelemetrySubscribersForTests,
-} = require('./plugin-subscribers-singleton');
-
-module.exports = {
-    createTelemetry,
-    createNoOpTelemetry,
-    createTelemetryEventBus,
-    resolveTelemetryConfig,
-    getTelemetry,
-    resetTelemetryForTests,
-    isNoOpExporter,
-    buildExporters,
-    instrumentHandler,
-    bindTelemetryContext,
-    createUsageRollupSubscriber,
-    getUsageRollupSubscriber,
-    resetUsageRollupForTests,
-    computeUsageWindows,
-    resolveNorthStarEntry,
-    northStarKeys,
-    createNorthStarDerivationSubscriber,
-    CANONICAL_COUNTERS,
-    isCanonicalCounter,
-    wireTelemetrySubscribers,
-    getPluginTelemetrySubscribers,
-    resetPluginTelemetrySubscribersForTests,
-};

package/telemetry/instrument-handler.js

@@ -1,82 +0,0 @@
-/**
- * Wraps a single integration handler invocation with a span + the
- * `frigg.handler.invocations` counter. Shared by the two
- * dispatch seams — `IntegrationBase.send()` and `IntegrationEventDispatcher` —
- * so both paths are instrumented identically.
- *
- * Cardinality discipline: the metric is keyed by the **bounded event type**
- * (USER_ACTION / CRON / QUEUE / WEBHOOK / LIFE_CYCLE_EVENT), never the specific
- * event/action name. High-cardinality ids (integrationId, userId) ride span
- * baggage via `telemetry.withContext`, never metric attributes. The full event
- * name is kept on the span only.
- *
- * @param {object|null} telemetry Telemetry service (no-op-safe; null → just runs fn).
- * @param {object} context Standard identifiers from `getTelemetryContext()`.
- * @param {{event: string, eventType: string}} descriptor Event name + bounded type.
- * @param {Function} fn The handler invocation.
- */
-async function instrumentHandler(telemetry, context = {}, descriptor = {}, fn) {
-    if (!telemetry || typeof telemetry.span !== 'function') {
-        return fn();
-    }
-
-    const integrationType = context.integrationType || 'unknown';
-    const eventType = descriptor.eventType || 'unknown';
-    const eventName = descriptor.event;
-
-    const runInstrumented = () =>
-        telemetry.span(`frigg.handler.${eventType}`, async (span) => {
-            if (span && typeof span.setAttributes === 'function') {
-                span.setAttributes({
-                    integration_type: integrationType,
-                    event: eventType,
-                    event_name: eventName,
-                });
-            }
-            // `event_name` (potentially high-cardinality action id) rides the
-            // bus-only context — used by North Star derived-from-trace matching,
-            // never a metric label.
-            const busContext = { event_name: eventName };
-            try {
-                const result = await fn();
-                telemetry.count(
-                    'frigg.handler.invocations',
-                    1,
-                    {
-                        integration_type: integrationType,
-                        event: eventType,
-                        status: 'ok',
-                    },
-                    busContext
-                );
-                return result;
-            } catch (err) {
-                telemetry.count(
-                    'frigg.handler.invocations',
-                    1,
-                    {
-                        integration_type: integrationType,
-                        event: eventType,
-                        status: 'error',
-                    },
-                    busContext
-                );
-                throw err;
-            }
-        });
-
-    if (typeof telemetry.withContext === 'function') {
-        return telemetry.withContext(
-            {
-                integrationId: context.integrationId,
-                userId: context.userId,
-                integrationType: context.integrationType,
-                version: context.version,
-            },
-            runInstrumented
-        );
-    }
-    return runInstrumented();
-}
-
-module.exports = { instrumentHandler };

package/telemetry/no-op-telemetry.js

@@ -1,66 +0,0 @@
-const { createTelemetryEventBus } = require('./telemetry-event-bus');
-const {
-    runWithTelemetryContext,
-    mergeTelemetryContext,
-} = require('./telemetry-context');
-
-/**
- * No-op telemetry implementation.
- *
- * This is the default when no OTel exporter is configured, so telemetry "rides
- * for free": integration code can call `this.telemetry.*`
- * unconditionally and it costs nothing on the OTel side. Critically, this module
- * imports **zero** OpenTelemetry packages — the no-op path never loads the OTel
- * SDK (guarded by a require-graph test), protecting Lambda cold-start.
- *
- * The internal event bus is still active here (Decision 7): `count`/`event` are
- * mirrored onto it so the durable usage rollup and plugin/extension taps work
- * even with OTel export disabled. Emitting to a bus with no subscribers is a
- * cheap no-op.
- *
- * @param {object} [options]
- * @param {object} [options.bus] Event bus to mirror emissions onto.
- */
-function createNoOpTelemetry({ bus = createTelemetryEventBus() } = {}) {
-    const noop = {
-        count(name, value = 1, attributes = {}, context) {
-            const merged = mergeTelemetryContext(context);
-            const payload = { name, value, attributes };
-            if (merged) payload.context = merged;
-            bus.emit('metric', payload);
-        },
-        event(name, attributes = {}, context) {
-            const merged = mergeTelemetryContext(context);
-            const payload = { name, attributes };
-            if (merged) payload.context = merged;
-            bus.emit('event', payload);
-        },
-        async span(_name, fn) {
-            return typeof fn === 'function' ? fn() : undefined;
-        },
-        startSpan() {
-            return {
-                setAttributes() {},
-                setAttribute() {},
-                recordException() {},
-                setStatus() {},
-                end() {},
-            };
-        },
-        async withContext(context, fn) {
-            return runWithTelemetryContext(context, () =>
-                typeof fn === 'function' ? fn() : undefined
-            );
-        },
-        on(eventType, callback) {
-            return bus.on(eventType, callback);
-        },
-        async forceFlush() {},
-        isEnabled() {
-            return false;
-        },
-    };
-    return noop;
-}
-
-module.exports = { createNoOpTelemetry };

package/telemetry/north-star.js

@@ -1,103 +0,0 @@
-/**
- * Adopter North Star metric. A North Star simply references
- * a usage-counter key (canonical or custom); its value is then read like any
- * other counter via `frigg.usage.totals({ metric: northStarKey })`. It is
- * populated either by (a) direct emission of that counter, or (b) derived from a
- * framework trace signal — this module implements (b) as a small bus subscriber
- * that emits the North Star counter when a configured signal matches.
- */
-
-/** Resolve the North Star counter entry for an integration type (byType wins). */
-function resolveNorthStarEntry(northStar, integrationType) {
-    if (!northStar) return null;
-    return (
-        (northStar.byType && northStar.byType[integrationType]) ||
-        northStar.default ||
-        null
-    );
-}
-
-/** The set of counter keys any North Star references — added to trackedMetrics. */
-function northStarKeys(northStar) {
-    const keys = new Set();
-    if (!northStar) return keys;
-    if (northStar.default?.name) keys.add(northStar.default.name);
-    for (const entry of Object.values(northStar.byType || {})) {
-        if (entry?.name) keys.add(entry.name);
-    }
-    return keys;
-}
-
-function matchesDeriveFrom(
-    deriveFrom,
-    { name, attributes = {}, context = {} }
-) {
-    if (!deriveFrom) return false;
-
-    if (deriveFrom.userAction) {
-        const rule = deriveFrom.userAction;
-        return (
-            name === 'frigg.handler.invocations' &&
-            attributes.event === 'USER_ACTION' &&
-            (!rule.action || context.event_name === rule.action)
-        );
-    }
-
-    if (deriveFrom.apiRequest) {
-        const rule = deriveFrom.apiRequest;
-        return (
-            name === 'frigg.apimodule.requests' &&
-            (!rule.method || attributes.method === rule.method) &&
-            (!rule.endpoint ||
-                (typeof context.url === 'string' &&
-                    context.url.includes(rule.endpoint)))
-        );
-    }
-
-    return false;
-}
-
-/**
- * Subscribe to the bus and emit the North Star counter whenever a configured
- * `deriveFrom` signal matches (config-only, no integration code). The emitted
- * counter flows back through the bus to the usage rollup like any other metric.
- */
-function createNorthStarDerivationSubscriber({ telemetry, northStar }) {
-    if (!telemetry || !northStar) return { unsubscribe() {} };
-
-    // Hoisted — the referenced-key set is fixed for the life of the subscriber.
-    const keys = northStarKeys(northStar);
-
-    function onMetric(payload) {
-        try {
-            // Never react to a North Star counter's own emission (no loop).
-            if (keys.has(payload.name)) return;
-
-            const integrationType =
-                payload.context?.integrationType ||
-                payload.attributes?.integration_type ||
-                null;
-            const entry = resolveNorthStarEntry(northStar, integrationType);
-            if (!entry || !entry.deriveFrom) return;
-            if (!matchesDeriveFrom(entry.deriveFrom, payload)) return;
-
-            telemetry.count(
-                entry.name,
-                1,
-                integrationType ? { integration_type: integrationType } : {},
-                payload.context
-            );
-        } catch (_) {
-            // Derivation must never break emission.
-        }
-    }
-
-    const unsubscribe = telemetry.on('metric', onMetric);
-    return { unsubscribe };
-}
-
-module.exports = {
-    resolveNorthStarEntry,
-    northStarKeys,
-    createNorthStarDerivationSubscriber,
-};

package/telemetry/otel-telemetry.js

@@ -1,215 +0,0 @@
-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 { buildExporters } = require('./exporters/exporter-factory');
-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.
-    }
-}
-
-/**
- * The OpenTelemetry-backed telemetry service. Reached 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.
- */
-function createOtelTelemetry({
-    exporter,
-    resource = {},
-    sampleRatio,
-    bus = createTelemetryEventBus(),
-} = {}) {
-    ensureContextManager();
-    const { traceExporter, metricExporter } = buildExporters(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();
-
-    const tracerProvider = new BasicTracerProvider({
-        resource: res,
-        sampler,
-        spanProcessors: traceExporter
-            ? [new BatchSpanProcessor(traceExporter)]
-            : [],
-    });
-
-    const metricReader = metricExporter
-        ? new PeriodicExportingMetricReader({
-              exporter: metricExporter,
-              exportIntervalMillis: METRIC_EXPORT_INTERVAL_MS,
-          })
-        : null;
-    const meterProvider = new MeterProvider({
-        resource: res,
-        readers: metricReader ? [metricReader] : [],
-    });
-
-    const tracer = tracerProvider.getTracer(TRACER_NAME);
-    const meter = meterProvider.getMeter(TRACER_NAME);
-
-    // Counters/UpDownCounters are cached — OTel requires one instrument instance
-    // per metric name, and re-creating them would drop data points.
-    const counters = new Map();
-    function getCounter(name) {
-        if (!counters.has(name)) counters.set(name, meter.createCounter(name));
-        return counters.get(name);
-    }
-
-    const service = {
-        count(name, value = 1, attributes = {}, context) {
-            try {
-                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` merges the ambient handler context (incl.
-            // high-cardinality ids) with any explicit per-call context — it rides
-            // the bus only, never the OTel metric attributes (Cardinality note).
-            const merged = mergeTelemetryContext(context);
-            const payload = { name, value, attributes };
-            if (merged) payload.context = merged;
-            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;
-            bus.emit('event', payload);
-        },
-
-        startSpan(name, options) {
-            return tracer.startSpan(name, options);
-        },
-
-        async span(name, fn, options = {}) {
-            return 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 bus.on(eventType, callback);
-        },
-
-        async forceFlush() {
-            await Promise.allSettled([
-                tracerProvider.forceFlush(),
-                meterProvider.forceFlush(),
-            ]);
-        },
-
-        async shutdown() {
-            await Promise.allSettled([
-                tracerProvider.shutdown(),
-                meterProvider.shutdown(),
-            ]);
-        },
-
-        isEnabled() {
-            return true;
-        },
-    };
-
-    return service;
-}
-
-module.exports = { createOtelTelemetry };

package/telemetry/plugin-subscribers-singleton.js

@@ -1,51 +0,0 @@
-const { wireTelemetrySubscribers } = require('./plugin-subscribers');
-
-/**
- * Process-wide wiring of adopter-declared telemetry subscribers. Built once per
- * cold start and reused for the life of the Lambda
- * container, mirroring the usage-rollup singleton. Independent of the usage
- * rollup: adopter taps wire even when no integration declares `Definition.usage`.
- * Never throws — a bad/absent app definition just means no adopter taps.
- */
-let wired = null;
-let initialized = false;
-
-function getPluginTelemetrySubscribers() {
-    if (initialized) return wired;
-    initialized = true;
-    try {
-        const {
-            loadAppDefinition,
-        } = require('../handlers/app-definition-loader');
-        const { telemetry = {} } = loadAppDefinition();
-        const subscribers = telemetry.subscribers || [];
-        if (subscribers.length === 0) {
-            wired = [];
-            return wired;
-        }
-
-        const { getTelemetry } = require('./telemetry-singleton');
-        wired = wireTelemetrySubscribers({
-            telemetry: getTelemetry(),
-            subscribers,
-        });
-    } catch (error) {
-        console.warn(
-            `[Frigg][telemetry] plugin subscribers disabled: ${
-                error && error.message
-            }`
-        );
-        wired = [];
-    }
-    return wired;
-}
-
-function resetPluginTelemetrySubscribersForTests() {
-    wired = null;
-    initialized = false;
-}
-
-module.exports = {
-    getPluginTelemetrySubscribers,
-    resetPluginTelemetrySubscribersForTests,
-};