@friggframework/core 2.0.0-next.102 → 2.0.0-next.103

package/telemetry/README.md

@@ -0,0 +1,331 @@
+# Frigg Telemetry & Usage Tracking
+
+Vendor-neutral observability (traces + metrics) and durable, per-integration
+feature-usage counters for `@friggframework/core`, built on OpenTelemetry.
+Implements [ADR-011](../../../docs/architecture-decisions/011-integration-telemetry-and-usage-tracking.md).
+
+## Overview
+
+Two capabilities ride the same primitive:
+
+1. **Observability** — spans + low-cardinality metrics across handlers, API
+   modules, queues and webhooks, per integration, exported to any OTLP backend
+   (Honeycomb, Datadog, Grafana, an OTel Collector, …).
+2. **Usage tracking** — durable per-integration counters (records synced,
+   webhooks received, API requests, user actions, …) folded into a Frigg-owned
+   store that the reporting endpoint reads for apples-to-apples comparison.
+
+### Key properties
+
+- **Rides for free.** Framework seams are auto-instrumented — integrations get
+  handler/API-module/webhook metrics with zero code.
+- **No-op by default.** With no exporter configured the service emits nothing and
+  loads **zero** OpenTelemetry modules — no cold-start cost. Integration code can
+  always call `this.telemetry.*`.
+- **Vendor-neutral.** Integration code never imports a backend SDK. Swap exporters
+  in the app definition.
+- **Usage store ≠ APM.** Reports read the durable Frigg store, never an external
+  APM.
+
+## Configuration (app definition)
+
+```js
+// backend/index.js
+const Definition = {
+    name: 'my-app',
+    integrations: [HubSpotIntegration, SalesforceIntegration],
+
+    telemetry: {
+        // none | console | otlp | honeycomb | datadog
+        exporter: {
+            type: 'otlp',
+            endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+            // headers: { 'x-honeycomb-team': process.env.HONEYCOMB_KEY }, // or use type:'honeycomb' + apiKey
+        },
+        sampleRatio: 1.0, // parent-based trace sampling (0..1)
+        northStar: {
+            default: { name: 'records.synced' },
+        },
+    },
+};
+```
+
+**Exporter default (no `telemetry.exporter` set):** `console` only when
+`STAGE=local` (a genuinely local run); every deployed stage — including `dev` —
+defaults to `none` (no per-event cost, no data written to CloudWatch). Point
+`exporter` at an OTLP backend to turn export on.
+
+**Sampling (`sampleRatio`, `0..1`, default `1`):** the fraction of **traces**
+exported — a cost knob for high-traffic fleets (`0.1` ≈ keep 10%). Whole traces
+are sampled (trace-ID-based + parent-based, so a distributed trace is never
+half-kept), and it does **not** thin the durable **usage counters** — those stay
+exact at any ratio (they ride the event bus, not the sampled trace pipeline). It
+is **not** error-aware: a low ratio drops failed-run traces too, so for "keep all
+errors, sample the rest" use tail-based sampling at an OTel Collector, not this
+knob. Typical: `1.0` in dev, lower (e.g. `0.1`) in high-volume prod.
+
+### Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP backend URL (referenced from `telemetry.exporter.endpoint`). Auto-passed through to Lambda when an OTLP-family exporter is configured. |
+| `OTEL_EXPORTER_OTLP_HEADERS` | OTLP headers (e.g. auth). |
+| `OTEL_FLUSH_TIMEOUT_MS` | Max time the handler waits to flush telemetry before returning (default `500`). Bounds tail latency if the backend is unreachable. |
+| `OTEL_METRIC_EXPORT_INTERVAL_MS` | Metric reader interval (default `60000`). |
+| `STAGE` | `local` enables the `console` default. |
+
+> **VPC note:** a Lambda in a private subnet needs a NAT gateway or VPC endpoint
+> to reach an external OTLP backend. Without egress the exporter fails silently
+> within `OTEL_FLUSH_TIMEOUT_MS`.
+
+## What you get for free (auto-instrumentation)
+
+No integration code required — every emission carries `{integration_type, event,
+status, ...}` bounded labels, with high-cardinality ids on span baggage / the bus
+context only.
+
+| Seam | Span | Metric |
+| --- | --- | --- |
+| Handler dispatch (USER_ACTION / CRON / QUEUE / WEBHOOK / lifecycle) | `frigg.handler.<type>` | `frigg.handler.invocations{integration_type, event, status}` |
+| Outbound API-module request | `frigg.apimodule.request` | `frigg.apimodule.requests{module, method, status}` |
+
+Request URLs are redacted (query string + userinfo stripped) before they touch a
+span, so credentials in query params never leak.
+
+> **Usage-attribution boundary.** The OTel metrics above fire for *every* seam
+> invocation. The durable per-integration **usage** rollup, though, only counts
+> emissions that carry an integration context — set by the handler seams. Requests
+> an API module makes *before an integration exists* (OAuth/token exchange, entity
+> discovery during connection setup) are observable in traces but not attributed to
+> an `api.requests` usage counter (there is no integration to attribute them to).
+
+## Custom metrics (integration code)
+
+Every integration instance carries `this.telemetry` (auto-tagged with its
+`integration_type`):
+
+```js
+class HubSpotIntegration extends IntegrationBase {
+    async deltaSync() {
+        // A span wraps the operation (nested under the handler span):
+        await this.telemetry.span('delta_sync', async () => {
+            const batch = await this.hubspot.api.getContacts();
+
+            // A counter — declare 'records.synced' in Definition.usage to persist it:
+            this.telemetry.count('records.synced', batch.length, {
+                entity: 'contact',
+            });
+
+            // A one-off event (attached to the active span):
+            this.telemetry.event('workflow_invoked', { workflow: 'lead_route' });
+        });
+    }
+}
+```
+
+## Usage counters (durable, comparable)
+
+### 1. Declare which counters an integration reports
+
+```js
+class HubSpotIntegration extends IntegrationBase {
+    static Definition = {
+        name: 'hubspot',
+        usage: {
+            // Canonical keys → comparable ACROSS integration types (reporting):
+            canonical: ['records.synced', 'webhooks.received', 'api.requests'],
+            // Custom keys → comparable only WITHIN this integration type:
+            custom: { 'deals.enriched': { unit: 'count', label: 'Deals enriched' } },
+        },
+    };
+}
+```
+
+**Canonical vocabulary** (core-owned, versioned):
+
+| Key | Source |
+| --- | --- |
+| `api.requests` | auto — every outbound API-module request |
+| `user_actions` | auto — every `USER_ACTION` handler |
+| `webhooks.received` | auto — the `ON_WEBHOOK` queue dispatch (per-integration, DB-connected) |
+| `records.synced` | explicit — `this.telemetry.count('records.synced', n, { entity })` |
+| `workflows.invoked` | explicit — `this.telemetry.count('workflows.invoked', 1, { workflow })` |
+
+Only **declared** keys are persisted. Declaring a canonical key opts the
+integration into the comparison report.
+
+### 2. Read the usage store
+
+`frigg.usage.*` (via `createFriggCommands`) reads the durable store — never an APM:
+
+```js
+const { createFriggCommands } = require('@friggframework/core');
+const frigg = createFriggCommands({ integrationClass: HubSpotIntegration });
+
+// Apples-to-apples comparison across integration types:
+await frigg.usage.getTotalsByDimension({
+    metric: 'records.synced',
+    groupBy: 'integrationType', // or 'metric'
+    since: daysAgo(30),
+    bucket: 'day', // 'day' (default) | 'hour'
+});
+// → [{ integrationType: 'hubspot', value: 4200 }, { integrationType: 'salesforce', value: 1180 }]
+
+// Trend series for one type (aggregated across its instances):
+await frigg.usage.getTimeSeries({
+    metric: 'records.synced',
+    integrationType: 'hubspot',
+    from: daysAgo(7),
+    to: new Date(),
+    bucket: 'day',
+});
+// → [{ bucket: 'day:2026-07-04', value: 610 }, { bucket: 'day:2026-07-05', value: 720 }]
+
+// Manual write (day + hour windows derived from `at`):
+await frigg.usage.recordUsageCounter({
+    integrationId: 'int_1',
+    integrationType: 'hubspot',
+    metric: 'deals.enriched',
+    value: 3,
+    at: new Date(),
+});
+```
+
+The [reporting endpoint](../reporting/README.md) surfaces these as additive
+`usage` columns on each `byType` bucket.
+
+## North Star metric
+
+Declare an adopter North Star that reports/snapshots read as a first-class
+counter — populated by direct emission, or derived from a trace signal with no
+integration code:
+
+```js
+telemetry: {
+    northStar: {
+        default: { name: 'records.synced' },
+        byType: {
+            hubspot: {
+                name: 'contacts_synced',
+                // derive from an auto-emitted signal:
+                deriveFrom: { apiRequest: { endpoint: '/contacts', method: 'POST' } },
+                // or: deriveFrom: { userAction: { action: 'route_lead' } }
+            },
+        },
+    },
+}
+```
+
+Read it as a first-class metric without knowing the configured key — the North
+Star resolves per integration type (`byType` wins over `default`):
+
+```js
+// The caller passes the North Star config it already holds (from the app
+// definition); this resolves the counter for the type and returns its totals.
+await frigg.usage.getNorthStarTotals({
+    northStar: definition.telemetry.northStar,
+    integrationType: 'hubspot',
+    since: daysAgo(30),
+});
+// → { metric: 'contacts_synced', totals: [{ integrationType: 'hubspot', value: 900 }] }
+// → null when `northStar` is absent or has no entry for the type
+```
+
+Or read it like any counter once you know the key:
+`frigg.usage.getTotalsByDimension({ metric: 'contacts_synced' })`; trends via `frigg.usage.getTimeSeries({ metric })`.
+
+> The North Star read takes its config as a **call argument** — nothing
+> telemetry-specific is threaded through `createFriggCommands`. The caller that
+> owns the app definition (e.g. a report runner) passes `telemetry.northStar` in;
+> omit it and `getNorthStarTotals()` returns `null`.
+
+## Plugin / extension tap
+
+Telemetry flows onto an internal event stream (independent of OTel export, so
+taps fire even with `exporter: none`). Two ways to subscribe:
+
+**Declarative (app definition)** — the framework wires these once per cold start,
+each guarded so a bad subscriber can't break emission or its siblings:
+
+```js
+// backend/index.js
+const Definition = {
+    telemetry: {
+        subscribers: [
+            // (a) declarative object — `event` optional; omit to receive both:
+            { event: 'metric', handler: ({ name, value, attributes, context }) => {
+                forwardToStatsd(name, value, attributes);
+            } },
+            // (b) factory — gets the telemetry service, registers itself, may
+            //     return an unsubscribe:
+            (telemetry) => telemetry.on('event', (payload) => auditSink.write(payload)),
+        ],
+    },
+};
+```
+
+**Imperative** — subscribe from anywhere that runs at startup:
+
+```js
+const { getTelemetry } = require('@friggframework/core');
+
+const off = getTelemetry().on('metric', ({ name, value, attributes, context }) => {
+    // `attributes` = bounded metric labels; `context` = high-cardinality ids
+    // (integrationId, integrationType, userId, url, …). Never throws upstream.
+});
+// off() to unsubscribe
+```
+
+> The bus payload shape (`{ name, value, attributes, context? }` for `'metric'`,
+> `{ name, attributes, context? }` for `'event'`) is a stable contract.
+
+## Cardinality rule
+
+High-cardinality identifiers (`integrationId`, `userId`, request `url`, action
+names) ride **span baggage / the bus `context`** — never OTel **metric** labels.
+Metric labels stay bounded (`integration_type`, `event`, `status`, `method`,
+`module`). The usage rollup derives per-integration counts from the bus context,
+not from metric labels.
+
+## How it works
+
+```
+this.telemetry.count / auto-instrumented seam
+        │  (bounded metric labels → OTel; ids → bus context via AsyncLocalStorage)
+        ├──────────────► OTel exporter (traces + metrics)   [observability]
+        └──────────────► TelemetryEventBus ('metric'/'event')
+                              │
+                              ├─ UsageRollupSubscriber ── buffers per invocation,
+                              │     flushes to the UsageCounter store on handler exit
+                              │     (discards on SQS redelivery — approximate contract)
+                              └─ your plugin taps
+
+frigg.usage.getTotalsByDimension / getTimeSeries ◄── UsageCounter store ──► reporting usage columns
+```
+
+- **Flush is Lambda-safe:** `create-handler` awaits a bounded `forceFlush` in a
+  `finally` (background timers can't fire once the container freezes).
+- **Usage accuracy is approximate:** at-least-once delivery means a retried
+  handler could double-count. The invocation buffer is discarded only when the
+  **whole** SQS batch is a redelivery (`ApproximateReceiveCount > 1`); a mixed
+  batch flushes so a redelivered sibling never drops a fresh record's counts.
+
+## Caveats / current limitations
+
+- **Usage persistence requires a DB-connected handler.** DB-free handlers (e.g.
+  the raw webhook-receipt route) can't write; `webhooks.received` is counted at
+  the DB-connected `ON_WEBHOOK` queue dispatch instead.
+- **DocumentDB** uses a raw-command adapter (`$runCommandRaw`) for increment and
+  aggregate; command shapes are unit-tested but not yet run against a real cluster.
+- **Retention:** the `UsageCounter` table has no pruning yet — hour-grain rows
+  accumulate. Add a scheduled prune for high-volume deployments. (Read paths are
+  covered by composite indexes `(metric, window)` and `(metric, integrationType,
+  window)`.)
+- Metric `value` is a `BigInt` per `(integrationId, integrationType, metric,
+  window)` row; reads coerce the sum to a JS Number (safe below 2^53).
+
+## See also
+
+- Architecture: [ADR-011](../../../docs/architecture-decisions/011-integration-telemetry-and-usage-tracking.md)
+- Reporting hand-off: [`reporting/README.md`](../reporting/README.md)
+- Encryption (same repository-triad pattern): [`database/encryption/README.md`](../database/encryption/README.md)

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 };