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

package/telemetry/bind-telemetry-context.js

@@ -0,0 +1,73 @@
+/**
+ * Wrap a telemetry service so an integration instance's emissions automatically
+ * carry its context — with no per-call boilerplate. Two channels are filled:
+ *  - `integration_type` onto attributes (the one bounded, low-cardinality label);
+ *  - the full identifier set onto the bus `context` arg (integrationId, userId,
+ *    version, …), which the usage rollup and traces read.
+ *
+ * So integration code writes `this.telemetry.count('records.synced', n, { entity })`
+ * or `this.telemetry.event('thing')` and both channels are populated. An
+ * explicitly passed context still wins (e.g. a requester attaching a per-call
+ * `url`), and high-cardinality ids ride the bus context only, never metric
+ * labels (Cardinality note).
+ *
+ * @param {object} base The underlying telemetry service.
+ * @param {() => object} getContext Lazy accessor for the instance's context.
+ */
+function bindTelemetryContext(base, getContext) {
+    if (!base) return base;
+
+    const readContext = () => {
+        try {
+            return (getContext && getContext()) || undefined;
+        } catch (_) {
+            return undefined;
+        }
+    };
+
+    const withType = (attributes, ctx) => {
+        const integrationType = ctx && ctx.integrationType;
+        if (!integrationType || 'integration_type' in attributes) {
+            return attributes;
+        }
+        return { integration_type: integrationType, ...attributes };
+    };
+
+    const resolveContext = (context, ctx) =>
+        context !== undefined ? context : ctx;
+
+    return {
+        // Single source of truth for the instance context, so callers (e.g.
+        // instrumentHandler) read it here instead of gathering it separately.
+        getContext: () => readContext() || {},
+        count(name, value = 1, attributes = {}, context) {
+            const ctx = readContext();
+            return base.count(
+                name,
+                value,
+                withType(attributes, ctx),
+                resolveContext(context, ctx)
+            );
+        },
+        event(name, attributes = {}, context) {
+            const ctx = readContext();
+            return base.event(
+                name,
+                withType(attributes, ctx),
+                resolveContext(context, ctx)
+            );
+        },
+        span: (...args) => base.span(...args),
+        startSpan: (...args) => base.startSpan(...args),
+        withContext: (...args) => base.withContext(...args),
+        on: (...args) => base.on(...args),
+        forceFlush: (...args) => base.forceFlush(...args),
+        shutdown: (...args) =>
+            typeof base.shutdown === 'function'
+                ? base.shutdown(...args)
+                : undefined,
+        isEnabled: (...args) => base.isEnabled(...args),
+    };
+}
+
+module.exports = { bindTelemetryContext };

package/telemetry/canonical-counters.js

@@ -0,0 +1,52 @@
+/**
+ * Canonical usage-counter vocabulary.
+ *
+ * These core-owned, versioned keys are the ONLY metrics guaranteed comparable
+ * *across* integration types — they power ADR-010's apples-to-apples comparison
+ * report. Custom keys (declared in an integration's `Definition.usage.custom`)
+ * are comparable only *within* an integration type.
+ *
+ * The registry is **additive**: new keys may be added, existing keys never
+ * change or are removed, so existing reports never break.
+ *
+ * `dims` are the bounded dimensions a counter may carry (Cardinality note) —
+ * high-cardinality ids (integrationId, userId) never appear here.
+ */
+const CANONICAL_COUNTERS = {
+    'records.synced': {
+        unit: 'count',
+        label: 'Records synced',
+        dims: ['entity'],
+    },
+    'webhooks.received': {
+        unit: 'count',
+        label: 'Webhooks received',
+        dims: ['event'],
+    },
+    'workflows.invoked': {
+        unit: 'count',
+        label: 'Workflows invoked',
+        dims: ['workflow'],
+    },
+    'api.requests': {
+        unit: 'count',
+        label: 'API requests',
+        dims: ['endpoint', 'status'],
+    },
+    user_actions: { unit: 'count', label: 'User actions', dims: ['action'] },
+};
+
+// NOTE: the framework-signal → canonical mapping lives in the usage rollup
+// subscriber (METRIC_TO_CANONICAL, keyed by the actual emitted metric names).
+// `records.synced` / `workflows.invoked` have no auto-signal — they are
+// explicit-only (`this.telemetry.count(...)`), so a canonical counter is never
+// shipped that silently stays at zero.
+
+function isCanonicalCounter(name) {
+    return Object.prototype.hasOwnProperty.call(CANONICAL_COUNTERS, name);
+}
+
+module.exports = {
+    CANONICAL_COUNTERS,
+    isCanonicalCounter,
+};

package/telemetry/exporters.js

@@ -0,0 +1,85 @@
+// Telemetry exporters — build the OTel { traceExporter, metricExporter } pair
+// for one destination. OTel SDK packages are require'd lazily INSIDE the
+// builders, so loading this module pulls in zero OTel (cold-start invariant).
+
+function joinPath(base, path) {
+    return `${String(base).replace(/\/$/, '')}${path}`;
+}
+
+/**
+ * Normalize a descriptor to an OTLP target { endpoint, headers }, folding in
+ * vendor presets (Honeycomb). Pure — no OTel required — so it stays unit-testable.
+ */
+function otlpTarget({ type, endpoint, headers, apiKey } = {}) {
+    if (type === 'honeycomb') {
+        return {
+            endpoint: endpoint || 'https://api.honeycomb.io',
+            headers: apiKey ? { 'x-honeycomb-team': apiKey } : headers,
+        };
+    }
+    return { endpoint, headers };
+}
+
+function buildOtlp(descriptor = {}) {
+    const {
+        OTLPTraceExporter,
+    } = require('@opentelemetry/exporter-trace-otlp-http');
+    const {
+        OTLPMetricExporter,
+    } = require('@opentelemetry/exporter-metrics-otlp-http');
+    const { endpoint, headers } = otlpTarget(descriptor);
+    // With no endpoint the SDK falls back to OTEL_EXPORTER_OTLP_ENDPOINT, so
+    // leave `url` unset in that case.
+    const options = (path) => ({
+        ...(endpoint ? { url: joinPath(endpoint, path) } : {}),
+        ...(headers ? { headers } : {}),
+    });
+    return {
+        traceExporter: new OTLPTraceExporter(options('/v1/traces')),
+        metricExporter: new OTLPMetricExporter(options('/v1/metrics')),
+    };
+}
+
+function buildConsole() {
+    const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace-base');
+    const { ConsoleMetricExporter } = require('@opentelemetry/sdk-metrics');
+    return {
+        traceExporter: new ConsoleSpanExporter(),
+        metricExporter: new ConsoleMetricExporter(),
+    };
+}
+
+// type → builder. Add a destination = add one entry. Datadog ingests OTLP/HTTP
+// natively; Honeycomb is an OTLP preset resolved in otlpTarget.
+const EXPORTERS = {
+    otlp: buildOtlp,
+    datadog: buildOtlp,
+    honeycomb: buildOtlp,
+    console: buildConsole,
+};
+
+/**
+ * Resolve a telemetry descriptor to its { traceExporter, metricExporter } pair.
+ * Pre-built instances (tests / advanced adopters) win over `type`; an unknown or
+ * absent type falls back to plain OTLP (which itself falls back to the standard
+ * OTLP env var). The own-property check keeps a `type` matching an
+ * Object.prototype member ('constructor', 'toString', …) from resolving an
+ * inherited key.
+ */
+function resolveExporter(descriptor = {}) {
+    if (descriptor.traceExporter || descriptor.metricExporter) {
+        return {
+            traceExporter: descriptor.traceExporter || null,
+            metricExporter: descriptor.metricExporter || null,
+        };
+    }
+    const build = Object.prototype.hasOwnProperty.call(
+        EXPORTERS,
+        descriptor.type
+    )
+        ? EXPORTERS[descriptor.type]
+        : buildOtlp;
+    return build(descriptor);
+}
+
+module.exports = { resolveExporter, EXPORTERS, otlpTarget, joinPath };

package/telemetry/index.js

@@ -0,0 +1,26 @@
+// Public telemetry surface. Framework-internal modules (adapters, bus, config,
+// exporters, subscribers, rollup) are deep-required by their consumers, not
+// re-exported here — every barrel export is semver surface.
+const { createTelemetry } = require('./telemetry-service');
+const {
+    getTelemetry,
+    setTelemetryForTests,
+    resetTelemetryRuntimeForTests,
+} = require('./telemetry-runtime');
+const { bindTelemetryContext } = require('./bind-telemetry-context');
+const { instrumentHandler } = require('./instrument-handler');
+const {
+    CANONICAL_COUNTERS,
+    isCanonicalCounter,
+} = require('./canonical-counters');
+
+module.exports = {
+    createTelemetry,
+    getTelemetry,
+    setTelemetryForTests,
+    resetTelemetryRuntimeForTests,
+    bindTelemetryContext,
+    instrumentHandler,
+    CANONICAL_COUNTERS,
+    isCanonicalCounter,
+};

package/telemetry/instrument-handler.js

@@ -0,0 +1,87 @@
+/**
+ * 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 Bound telemetry service (no-op-safe; null → just
+ *   runs fn). The context is read from `telemetry.getContext()` — the per-instance
+ *   bound wrapper carries it; a raw service degrades to 'unknown'.
+ * @param {{event: string, eventType: string}} descriptor Event name + bounded type.
+ * @param {Function} fn The handler invocation.
+ */
+async function instrumentHandler(telemetry, descriptor = {}, fn) {
+    if (!telemetry || typeof telemetry.span !== 'function') {
+        return fn();
+    }
+
+    const context =
+        typeof telemetry.getContext === 'function'
+            ? telemetry.getContext()
+            : {};
+    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

@@ -0,0 +1,67 @@
+const { createTelemetryEventBus } = require('./telemetry-event-bus');
+const {
+    runWithTelemetryContext,
+    mergeTelemetryContext,
+} = require('./telemetry-context');
+
+/**
+ * No-op telemetry adapter: the default when no exporter is configured, so
+ * telemetry "rides for free". Imports **zero** OpenTelemetry packages (guarded by
+ * a require-graph test) — the no-op path never loads the OTel SDK, protecting
+ * Lambda cold-start. The internal event bus is still active: `count`/`event` are
+ * mirrored onto it so the durable usage rollup + plugin taps work even with
+ * export off (emitting to a bus with no subscribers is cheap).
+ */
+class NoOpTelemetry {
+    constructor({ bus = createTelemetryEventBus() } = {}) {
+        this._bus = bus;
+    }
+
+    count(name, value = 1, attributes = {}, context) {
+        const merged = mergeTelemetryContext(context);
+        const payload = { name, value, attributes };
+        if (merged) payload.context = merged;
+        this._bus.emit('metric', payload);
+    }
+
+    event(name, attributes = {}, context) {
+        const merged = mergeTelemetryContext(context);
+        const payload = { name, attributes };
+        if (merged) payload.context = merged;
+        this._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 this._bus.on(eventType, callback);
+    }
+
+    async forceFlush() {}
+
+    async shutdown() {}
+
+    isEnabled() {
+        return false;
+    }
+}
+
+module.exports = { NoOpTelemetry };

package/telemetry/north-star.js

@@ -0,0 +1,103 @@
+/**
+ * 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.getTotalsByDimension({ 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,
+};