@mondaydotcomorg/z2h-cli 0.25.7 → 0.25.9

package/handler-api/backend-runner/channels/channel-map.ts

@@ -1,5 +1,6 @@
-import { logger, metric } from '@mondaydotcomorg/trident-backend-runtime';
+import { logger } from '@mondaydotcomorg/trident-backend-runtime';
 
+import { withChannelTelemetry } from './channel-telemetry';
 import { makeDbChannel } from './db-channel/db.channel';
 import { makeLlmChannel } from './llm-channel/llm.channel';
 import { makeMondayChannel } from './monday-channel/monday.channel';
@@ -56,8 +57,9 @@ const OAUTH_CHANNELS: Record<string, (caller: Caller) => ChannelMap> = {
  * `monday_not_connected`, `monday_auth`, … A `4xx` means the handler (or the user's
  * setup) is wrong and retrying won't help; `502` means the upstream failed.
  *
- * Each key is wrapped with `z2h.channel.<key>` duration + error metrics, tagged by app.
- * Failures also reach BI generically at the invoke level — see `runner.service.ts`.
+ * Each key emits a unified call counter, duration distribution, and BI event tagged
+ * by app, channel, method, and outcome. Uncaught failures also reach BI at the
+ * invocation level — see `runner.service.ts`.
  */
 export function buildChannels(appName: string, caller: Caller, declaredIntegrations: string[]): ChannelMap {
   const channels: ChannelMap = {
@@ -78,13 +80,5 @@ export function buildChannels(appName: string, caller: Caller, declaredIntegrati
     }
   }
 
-  return Object.fromEntries(
-    Object.entries(channels).map(([key, fn]) => [
-      key,
-      metric.wrapFunctionWithMetrics(fn, {
-        customName: `z2h.channel.${key}`,
-        tags: { highCardinalityTags: { appName } },
-      }),
-    ]),
-  );
+  return Object.fromEntries(Object.entries(channels).map(([key, fn]) => [key, withChannelTelemetry(appName, key, fn)]));
 }

package/handler-api/backend-runner/channels/channel-telemetry.ts

@@ -0,0 +1,79 @@
+import { metric } from '@mondaydotcomorg/trident-backend-runtime';
+import { BackendRunnerEvents } from '@mondaydotcomorg/z2h-shared-utils/observability';
+import { trackEvent } from '@mondaydotcomorg/z2h-shared-utils/observability/trident';
+
+import { ChannelError } from '../backend-runner.errors';
+import type { ChannelHandler } from '../backend-runner.types';
+import { BI_SOURCE } from '../constants';
+
+type ChannelOutcome = 'success' | 'failure';
+
+function parseChannelKey(key: string): { channel: string; method: string } {
+  const parts = key.split('.');
+  if (parts.length !== 2 || parts.some((part) => !part)) {
+    throw new Error(`channel key must use <channel>.<method>: ${key}`);
+  }
+  return { channel: parts[0], method: parts[1] };
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    (typeof value === 'object' || typeof value === 'function') &&
+    value !== null &&
+    typeof (value as PromiseLike<unknown>).then === 'function'
+  );
+}
+
+function recordChannelCall(
+  appName: string,
+  channel: string,
+  method: string,
+  outcome: ChannelOutcome,
+  startedAt: number,
+  error?: unknown,
+): void {
+  const durationMs = performance.now() - startedAt;
+  const dimensions = { appName, channel, method };
+
+  metric.increment(BackendRunnerEvents.channel.callMetric, { ...dimensions, outcome });
+  metric.distribution(BackendRunnerEvents.channel.durationMetric, durationMs, dimensions);
+  void trackEvent(
+    BackendRunnerEvents.channel.biEvent,
+    {
+      ...dimensions,
+      outcome,
+      duration_ms: durationMs,
+      ...(error instanceof ChannelError ? { error_code: error.code } : {}),
+    },
+    BI_SOURCE,
+  );
+}
+
+export function withChannelTelemetry(appName: string, key: string, handler: ChannelHandler): ChannelHandler {
+  const { channel, method } = parseChannelKey(key);
+
+  return (args) => {
+    const startedAt = performance.now();
+    try {
+      const result = handler(args);
+      if (isPromiseLike(result)) {
+        return Promise.resolve(result).then(
+          (value) => {
+            recordChannelCall(appName, channel, method, 'success', startedAt);
+            return value;
+          },
+          (error: unknown) => {
+            recordChannelCall(appName, channel, method, 'failure', startedAt, error);
+            throw error;
+          },
+        );
+      }
+
+      recordChannelCall(appName, channel, method, 'success', startedAt);
+      return result;
+    } catch (error) {
+      recordChannelCall(appName, channel, method, 'failure', startedAt, error);
+      throw error;
+    }
+  };
+}

package/handler-api/backend-runner/channels/snowflake-channel/run-query.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 
-import { context, logger } from '@mondaydotcomorg/trident-backend-runtime';
+import { context, logger, metric } from '@mondaydotcomorg/trident-backend-runtime';
 import { BackendRunnerEvents } from '@mondaydotcomorg/z2h-shared-utils/observability';
 import { trackEvent } from '@mondaydotcomorg/z2h-shared-utils/observability/trident';
 import { getDefaultClient } from 'src/utils/elasticache';
@@ -26,6 +26,18 @@ export interface SnowflakeRow {
 export interface RunQueryOptions {
   /** Clamped to MAX_TIMEOUT_MS. Defaults to DEFAULT_TIMEOUT_MS. */
   timeoutMs?: number;
+  /** Human-readable label for the pool identifier/logs, e.g. a widget name, instead of the default query-shape hash. Sanitized to `[a-z0-9-_]`, max 64 chars. */
+  identifier?: string;
+}
+
+const MAX_IDENTIFIER_LENGTH = 64;
+
+function sanitizeIdentifier(raw: string): string {
+  return raw
+    .toLowerCase()
+    .replace(/[^a-z0-9-_]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, MAX_IDENTIFIER_LENGTH);
 }
 
 function hashQuery(boundSql: string, params: Record<string, SnowflakeParamValue>): string {
@@ -133,12 +145,14 @@ export async function runSnowflakeQuery(
 
   // Cache key stays parameter-sensitive; the pool identifier deliberately is not.
   const queryCacheKey = hashQuery(boundSql, params ?? {});
-  const queryIdentifier = hashQueryShape(sql);
+  const sanitizedIdentifier = options?.identifier ? sanitizeIdentifier(options.identifier) : '';
+  const queryIdentifier = sanitizedIdentifier || hashQueryShape(sql);
   const scope = cacheScope(useStateless);
   const startMs = Date.now();
   const cached = scope ? await readCache(queryCacheKey, scope) : null;
   if (cached) {
     const duration_ms = Date.now() - startMs;
+    metric.increment(BackendRunnerEvents.snowflake.cacheMetric, { appName, result: 'hit' });
     void trackEvent(BackendRunnerEvents.snowflake.queryExecuted, { appName, duration_ms, cache_hit: true }, BI_SOURCE);
     logger.info(
       {
@@ -183,7 +197,7 @@ export async function runSnowflakeQuery(
     );
   } catch (err) {
     // Failure BI tracking already happens generically at the invoke level
-    // (runner.service.ts's BackendRunnerEvents.invoke.failed, tagged with this
+    // (runner.service.ts's BackendRunnerEvents.invoke.biEvent, tagged with this
     // ChannelError's `code`) — this stays a log only, for the queryHash/
     // queryIdentifier that generic event can't know about.
     const duration_ms = Date.now() - startMs;
@@ -194,6 +208,7 @@ export async function runSnowflakeQuery(
   const rows = Array.isArray(data) ? data : [];
   if (scope) {
     await writeCache(queryCacheKey, scope, rows);
+    metric.increment(BackendRunnerEvents.snowflake.cacheMetric, { appName, result: 'miss' });
   }
   const duration_ms = Date.now() - startMs;
   void trackEvent(BackendRunnerEvents.snowflake.queryExecuted, { appName, duration_ms, cache_hit: false }, BI_SOURCE);

package/handler-api/backend-runner/channels/snowflake-channel/snowflake.channel.ts

@@ -33,7 +33,11 @@ export function makeSnowflakeChannel(appName: string) {
      *
      * @param sql - A SELECT statement. Non-SELECT is rejected with `400`.
      * @param params - Optional map of `:name` → `string | number | boolean | null` bindings.
-     * @param options - Optional `{ timeoutMs?: number }` — clamped to 5 min (`MAX_TIMEOUT_MS`); effective ceiling is ~5.5 min including the host backstop.
+     * @param options - Optional `{ timeoutMs?: number, identifier?: string }`. `timeoutMs` is
+     *   clamped to 5 min (`MAX_TIMEOUT_MS`); effective ceiling is ~5.5 min including the host
+     *   backstop. `identifier` names this query in logs/metrics and the Snowflake pool identifier
+     *   (e.g. a widget name) instead of the default query-shape hash — sanitized to `[a-z0-9-_]`,
+     *   max 64 chars.
      * @returns Array of row objects with **camelCase keys** — SQL aliases are normalized
      *   to camelCase regardless of their casing in the query
      *   (e.g. `AS current_user` → `rows[0].currentUser`, `AS total_count` → `rows[0].totalCount`).
@@ -63,6 +67,14 @@ export function makeSnowflakeChannel(appName: string) {
      *   { timeoutMs: 25_000 },
      * );
      *
+     * @example
+     * // Name this query in logs/metrics instead of the default hash
+     * const rows = await ctx.api.v1.snowflake.query(
+     *   `SELECT COUNT(*) AS total FROM monday_items`,
+     *   undefined,
+     *   { identifier: 'total-items-kpi' },
+     * );
+     *
      * @throws `400` `snowflake_invalid_argument` — `sql` was not a non-empty string.
      * @throws `400` `snowflake_not_read_only` — the statement is not a SELECT.
      * @throws `400` `snowflake_invalid_sql` — the statement could not be parsed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.25.7",
+  "version": "0.25.9",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -51,7 +51,7 @@
   ],
   "dependencies": {
     "@aws-sdk/client-s3": "^3.706.0",
-    "@mondaydotcomorg/z2h-shared-utils": "^0.4.1",
+    "@mondaydotcomorg/z2h-shared-utils": "^0.4.3",
     "chokidar": "^3.6.0",
     "commander": "^12.1.0",
     "cors": "^2.8.6",