@friggframework/core 2.0.0--canary.517.2bfd339.0 → 2.0.0--canary.622.16ee19d.0

package/README.md

@@ -200,6 +200,46 @@ const secureData = cryptor.encrypt(JSON.stringify({
 }));
 ```
 
+### 4b. Telemetry & Usage Tracking (`/telemetry`, `/usage`)
+
+Vendor-neutral OpenTelemetry observability plus durable, per-integration usage
+counters (ADR-011). No-op by default (zero cold-start cost); framework seams are
+auto-instrumented so integrations get handler/API-module/webhook metrics for free.
+
+**Usage:**
+```javascript
+// App definition — turn on export + declare a North Star:
+const Definition = {
+    name: 'my-app',
+    telemetry: {
+        exporter: { type: 'otlp', endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT },
+        northStar: { default: { name: 'records.synced' } },
+    },
+};
+
+// Integration code — custom metrics/spans (this.telemetry is auto-tagged):
+await this.telemetry.span('delta_sync', async () => {
+    this.telemetry.count('records.synced', batch.length, { entity: 'contact' });
+});
+
+// Declare which usage counters an integration reports (opts into reporting):
+class HubSpotIntegration extends IntegrationBase {
+    static Definition = {
+        name: 'hubspot',
+        usage: { canonical: ['records.synced', 'api.requests'] },
+    };
+}
+
+// Read the durable usage store (never an APM):
+const frigg = createFriggCommands({ integrationClass: HubSpotIntegration });
+await frigg.usage.totals({ metric: 'records.synced', groupBy: 'integrationType' });
+```
+
+**See:** [`telemetry/README.md`](telemetry/README.md) for the full guide
+(exporters, custom metrics, the Usage-Counter contract, North Star, the plugin
+tap, cardinality rules, and caveats) and [`usage/README.md`](usage/README.md) for
+the store internals.
+
 ### 5. Error Handling (`/errors`)
 
 Standardized error types with proper HTTP status codes.

package/application/commands/usage-commands.js

@@ -0,0 +1,76 @@
+/**
+ * Usage Commands
+ *
+ * Application Layer — the read/write surface over the durable usage store
+ * (ADR-011 §5). Exposed as `frigg.usage.*` on the unified command object so
+ * reports and integration code query usage without touching the repository.
+ *
+ * @example
+ * const frigg = createFriggCommands({ integrationClass: MyIntegration });
+ * await frigg.usage.totals({ metric: 'records.synced', groupBy: 'integrationType', since });
+ * await frigg.usage.series({ metric: 'records.synced', integrationType: 'hubspot', bucket: 'day' });
+ */
+const {
+    createUsageRepository,
+} = require('../../usage/repositories/usage-repository-factory');
+const { computeUsageWindows } = require('../../telemetry/usage-windows');
+const { resolveNorthStarEntry } = require('../../telemetry/north-star');
+
+function createUsageCommands({ usageRepository, northStar = null } = {}) {
+    const repository = usageRepository || createUsageRepository();
+
+    return {
+        /**
+         * Record a usage counter for a point in time. Callers pass `at` (a Date,
+         * default now) — NOT a raw window key — and both the day and hour windows
+         * are derived, matching how the auto-rollup persists so series() reads
+         * back consistently at either granularity.
+         */
+        async recordUsageCounter({
+            integrationId,
+            integrationType,
+            metric,
+            value = 1,
+            at = new Date(),
+        }) {
+            for (const window of computeUsageWindows(at)) {
+                await repository.increment({
+                    integrationId,
+                    integrationType,
+                    metric,
+                    window,
+                    value,
+                });
+            }
+        },
+
+        async totals(args) {
+            return repository.totals(args);
+        },
+
+        async series(args) {
+            return repository.series(args);
+        },
+
+        /**
+         * First-class North Star read (ADR-011 Decision 5). Resolves the
+         * configured counter for an integration type (byType wins over default),
+         * then returns its totals from the durable usage store. Returns `null`
+         * when no North Star is configured, so callers can branch without
+         * knowing the counter key. Trends read via `series({ metric })`.
+         */
+        async northStar({ integrationType, since, groupBy = 'integrationType', bucket } = {}) {
+            const entry = resolveNorthStarEntry(northStar, integrationType);
+            if (!entry) return null;
+            const totals = await repository.totals({
+                metric: entry.name,
+                groupBy,
+                since,
+                bucket,
+            });
+            return { metric: entry.name, totals };
+        },
+    };
+}
+
+module.exports = { createUsageCommands };

package/application/index.js

@@ -4,15 +4,25 @@ const {
 } = require('./commands/integration-commands');
 const { createUserCommands } = require('./commands/user-commands');
 const { createEntityCommands } = require('./commands/entity-commands');
-const {
-    createCredentialCommands,
-} = require('./commands/credential-commands');
-const {
-    createProcessCommands,
-} = require('./commands/process-commands');
-const {
-    createSchedulerCommands,
-} = require('./commands/scheduler-commands');
+const { createCredentialCommands } = require('./commands/credential-commands');
+const { createProcessCommands } = require('./commands/process-commands');
+const { createSchedulerCommands } = require('./commands/scheduler-commands');
+const { createUsageCommands } = require('./commands/usage-commands');
+const { loadAppDefinition } = require('../handlers/app-definition-loader');
+
+/**
+ * Resolve the adopter's North Star config from the app definition so
+ * `frigg.usage.northStar(...)` can read it (ADR-011 Decision 5). Guarded: a
+ * missing/unloadable app definition (e.g. in unit tests) must never break the
+ * command factory — usage reads simply have no North Star.
+ */
+function resolveNorthStarConfig() {
+    try {
+        return loadAppDefinition().telemetry?.northStar ?? null;
+    } catch (_) {
+        return null;
+    }
+}
 
 /**
  * Create a unified command factory with all CRUD operations
@@ -56,6 +66,9 @@ function createFriggCommands({ integrationClass }) {
 
         // Process commands
         ...processCommands,
+
+        // Usage read/write (ADR-011) — nested to match `frigg.usage.*`
+        usage: createUsageCommands({ northStar: resolveNorthStarConfig() }),
     };
 }
 
@@ -70,6 +83,7 @@ module.exports = {
     createCredentialCommands,
     createProcessCommands,
     createSchedulerCommands,
+    createUsageCommands,
 
     // Legacy standalone function
     findIntegrationContextByExternalEntityId,

package/core/create-handler.js

@@ -4,6 +4,82 @@
 
 const { initDebugLog, flushDebugLog } = require('../logs');
 const { secretsToEnv } = require('./secrets-to-env');
+const { getTelemetry } = require('../telemetry/telemetry-singleton');
+const {
+    getUsageRollupSubscriber,
+} = require('../telemetry/usage-rollup-singleton');
+const {
+    getPluginTelemetrySubscribers,
+} = require('../telemetry/plugin-subscribers-singleton');
+
+// Bounds the tail latency telemetry adds to every warm invocation. Kept low so
+// an unreachable OTLP endpoint (e.g. a VPC Lambda with no NAT/egress) costs at
+// most this, not multiple seconds. Override with OTEL_FLUSH_TIMEOUT_MS.
+const DEFAULT_FLUSH_TIMEOUT_MS =
+    Number(process.env.OTEL_FLUSH_TIMEOUT_MS) || 500;
+
+/**
+ * Fold the invocation's buffered usage counters into the durable store, then
+ * clear the buffer. On an SQS redelivery (ApproximateReceiveCount > 1) we
+ * DISCARD rather than flush — the prior delivery already counted, and the usage
+ * accuracy contract is "approximate, skip obvious redeliveries". Fully guarded.
+ */
+async function flushUsageRollup(subscriber, eventSummary, shouldUseDatabase) {
+    if (!subscriber) return;
+    try {
+        // Persisting usage requires a DB connection. DB-free handlers (e.g. the
+        // webhook-receipt route) never called connectPrisma, so drop the buffer
+        // instead of issuing a connectionless Prisma write.
+        if (!shouldUseDatabase) {
+            subscriber.discard();
+            return;
+        }
+        const redelivered =
+            Array.isArray(eventSummary?.records) &&
+            eventSummary.records.some((r) => Number(r.receiveCount) > 1);
+        if (redelivered) {
+            subscriber.discard();
+        } else {
+            await subscriber.flush();
+        }
+    } catch (_) {
+        // Usage rollup must never break the handler.
+    }
+}
+
+/**
+ * Flush telemetry before the Lambda container freezes. Because
+ * `callbackWaitsForEmptyEventLoop=false` (below) stops the event loop the moment
+ * the handler returns, OTel's timer-driven batch processors would never fire —
+ * so spans/metrics must be flushed synchronously here. Bounded by a timeout so a
+ * stalled exporter can never block the response, and fully guarded so a flush
+ * failure never breaks the handler.
+ */
+async function flushTelemetry(telemetry, timeoutMs) {
+    try {
+        if (
+            !telemetry ||
+            typeof telemetry.isEnabled !== 'function' ||
+            !telemetry.isEnabled()
+        ) {
+            return;
+        }
+        let timer;
+        const deadline = new Promise((resolve) => {
+            timer = setTimeout(resolve, timeoutMs);
+        });
+        try {
+            await Promise.race([
+                Promise.resolve(telemetry.forceFlush()),
+                deadline,
+            ]);
+        } finally {
+            clearTimeout(timer);
+        }
+    } catch (_) {
+        // Telemetry flush must never break the handler.
+    }
+}
 
 // Best-effort extraction of correlation identifiers from a Lambda event.
 // For SQS: pulls messageIds + parsed event/processId/integrationId from each
@@ -36,8 +112,7 @@ const summarizeLambdaEvent = (event) => {
     if (event.httpMethod || event.requestContext?.http) {
         return {
             source: 'http',
-            method:
-                event.httpMethod || event.requestContext?.http?.method,
+            method: event.httpMethod || event.requestContext?.http?.method,
             path: event.path || event.rawPath,
         };
     }
@@ -50,6 +125,9 @@ const createHandler = (optionByName = {}) => {
         isUserFacingResponse = true,
         method,
         shouldUseDatabase = true,
+        telemetry,
+        flushTimeoutMs = DEFAULT_FLUSH_TIMEOUT_MS,
+        usageRollup,
     } = optionByName;
 
     if (!method) {
@@ -58,16 +136,23 @@ const createHandler = (optionByName = {}) => {
 
     return async (event, context) => {
         const eventSummary = summarizeLambdaEvent(event);
+        const activeTelemetry = telemetry || getTelemetry();
+        const activeUsageRollup =
+            usageRollup !== undefined
+                ? usageRollup
+                : getUsageRollupSubscriber();
+
+        // Wire adopter-declared telemetry subscribers once per cold start
+        // (ADR-011 Decision 6). Memoized in the singleton, so this is a cheap
+        // no-op after the first invocation.
+        getPluginTelemetrySubscribers();
 
         try {
-            console.info(
-                `[createHandler] ${eventName}: handler entry`,
-                {
-                    eventName,
-                    awsRequestId: context?.awsRequestId,
-                    ...eventSummary,
-                }
-            );
+            console.info(`[createHandler] ${eventName}: handler entry`, {
+                eventName,
+                awsRequestId: context?.awsRequestId,
+                ...eventSummary,
+            });
 
             initDebugLog(eventName, event);
 
@@ -139,6 +224,14 @@ const createHandler = (optionByName = {}) => {
 
             // Here we can just rethrow and let AWS build the response.
             throw error;
+        } finally {
+            // Flush telemetry + usage before the container freezes.
+            await flushTelemetry(activeTelemetry, flushTimeoutMs);
+            await flushUsageRollup(
+                activeUsageRollup,
+                eventSummary,
+                shouldUseDatabase
+            );
         }
     };
 };