@kortyx/usage-telemetry 0.3.0 → 0.5.0

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   classifyUsageError: () => classifyUsageError,
+  classifyUsageHttpStatus: () => classifyUsageHttpStatus,
   createCollectorTransport: () => createCollectorTransport,
   createPostHogTransport: () => createPostHogTransport,
   createUsageTelemetry: () => createUsageTelemetry,
@@ -58,6 +59,8 @@ var operations = [
   "sdk.checkpoint.rollback",
   "sdk.export",
   "studio.setup",
+  "studio.sample",
+  "studio.help",
   "studio.connection",
   "studio.read",
   "studio.render",
@@ -72,6 +75,11 @@ var operations = [
   "studio.settings",
   "studio.update",
   "studio.ingest",
+  "cli.command",
+  "studio.eval.execution",
+  "studio.diagnostic",
+  "studio.table.layout",
+  "studio.help",
   "cli.topology",
   "cli.eval"
 ];
@@ -86,9 +94,256 @@ var outcomes = [
   "ungraded"
 ];
 var publicCatalog = {
-  products: ["sdk", "oss_studio"],
+  products: ["sdk", "oss_studio", "cli"],
   operations,
   properties: {
+    help_action: [
+      "open",
+      "documentation",
+      "start",
+      "step",
+      "complete",
+      "skip",
+      "exit",
+      "error",
+      "example_request",
+      "example_accept",
+      "example_cancel"
+    ],
+    help_page: [
+      "runs",
+      "run",
+      "sessions",
+      "session",
+      "workflows",
+      "interrupts",
+      "interrupt",
+      "prompts",
+      "prompt",
+      "prompt-groups",
+      "prompt-group",
+      "evals",
+      "eval-suites",
+      "eval-suite",
+      "evaluation",
+      "eval-run",
+      "eval-case",
+      "eval-comparison",
+      "eval-case-comparison",
+      "diagnostic",
+      "settings",
+      "onboarding",
+      "other"
+    ],
+    help_context: ["sample", "real"],
+    help_step: [
+      "overview",
+      "controls",
+      "records",
+      "tabs",
+      "content",
+      "navigation",
+      "state"
+    ],
+    sample_action: [
+      "select",
+      "view",
+      "hide",
+      "show",
+      "tour_start",
+      "tour_complete",
+      "tour_skip",
+      "tour_error",
+      "tour_step",
+      "tour_hub",
+      "tour_resume",
+      "tour_exit",
+      "tour_full_start",
+      "tour_full_complete",
+      "tour_full_partial",
+      "tour_reset"
+    ],
+    tour_chapter: [
+      "sample-execution",
+      "debug-execution",
+      "conversation",
+      "approvals",
+      "prompt-versions",
+      "evaluation-results",
+      "error-diagnostics",
+      "evaluation-progress",
+      "personalize"
+    ],
+    tour_step: [
+      "project-selector",
+      "sample-run",
+      "execution-details",
+      "find-failed-run",
+      "failure-summary",
+      "failure-trace",
+      "failure-model-io",
+      "session-history",
+      "session-runs",
+      "workflow-topology",
+      "workflow-system",
+      "approval-decision",
+      "approval-timeline",
+      "approval-result",
+      "prompt-original",
+      "prompt-updated",
+      "prompt-diff",
+      "suite-definition",
+      "evaluation-summary",
+      "case-evidence",
+      "saved-comparison",
+      "diagnostic-exception",
+      "diagnostic-capture",
+      "diagnostic-context",
+      "evaluation-progress-summary",
+      "evaluation-grading",
+      "evaluation-pending-evidence",
+      "appearance",
+      "sample-visibility"
+    ],
+    tour_failure: ["load", "target", "entry"],
+    tour_mode: ["chapter", "full"],
+    tour_version: ["1"],
+    help_placement: ["card", "button"],
+    measurement_version: ["2"],
+    measurement_kind: [
+      "invocation",
+      "stage",
+      "execution",
+      "attempt",
+      "chunk",
+      "output",
+      "update",
+      "poll",
+      "request",
+      "call",
+      "feature",
+      "observation"
+    ],
+    traffic_source: ["internal", "synthetic", "external", "unknown"],
+    layout_action: [
+      "visibility",
+      "show_all",
+      "reset",
+      "apply",
+      "reset_width",
+      "pin",
+      "unpin",
+      "resize",
+      "reorder"
+    ],
+    eval_phase: [
+      "params",
+      "setup",
+      "execute",
+      "responder",
+      "reference",
+      "grading",
+      "verification",
+      "cleanup",
+      "reporting"
+    ],
+    cli_resource: ["evals.runs", "evals.suites"],
+    retryable: "boolean",
+    retried: "boolean",
+    recovered: "boolean",
+    retry_attempt: ["1", "2-5", "6-20", "21-100", "101+"],
+    batch_size: ["1", "2-5", "6-20", "21-100", "101+"],
+    http_status_class: ["1xx", "2xx", "3xx", "4xx", "5xx"],
+    cause_category: [
+      "configuration",
+      "provider",
+      "validation",
+      "domain",
+      "workflow",
+      "persistence",
+      "request",
+      "transport",
+      "internal",
+      "unknown"
+    ],
+    cli_command: [
+      "studio.start",
+      "studio.stop",
+      "studio.restart",
+      "studio.status",
+      "studio.logs",
+      "studio.credentials",
+      "studio.reset",
+      "studio.prompts",
+      "studio.evals",
+      "studio.runs",
+      "studio.sessions",
+      "studio.interrupts",
+      "studio.workflows",
+      "studio.diagnostics",
+      "studio.inspect",
+      "studio.doctor",
+      "studio.catalogs",
+      "connections",
+      "evals.run",
+      "evals.list",
+      "topology.push",
+      "help",
+      "unknown"
+    ],
+    cli_action: [
+      "start",
+      "stop",
+      "restart",
+      "status",
+      "logs",
+      "credentials",
+      "reset",
+      "run",
+      "list",
+      "get",
+      "show",
+      "inspect",
+      "analyze",
+      "download",
+      "doctor",
+      "cancel",
+      "compare",
+      "create",
+      "update",
+      "delete",
+      "import",
+      "export",
+      "pull",
+      "push",
+      "add",
+      "remove",
+      "use",
+      "verify",
+      "versions",
+      "diff",
+      "validate",
+      "action",
+      "tag",
+      "untag",
+      "rollback",
+      "promote",
+      "archive",
+      "restore",
+      "test",
+      "copy",
+      "apply",
+      "wait",
+      "catalogs",
+      "help",
+      "unknown"
+    ],
+    dry_run: "boolean",
+    json_output: "boolean",
+    topology_strict: "boolean",
+    settings_override: "boolean",
+    case_timeout_override: "boolean",
+    run_timeout_override: "boolean",
     phase: [
       "admission",
       "execution",
@@ -233,6 +488,7 @@ var publicCatalog = {
       "pending",
       "expired"
     ],
+    match: ["all", "any"],
     filter: [
       "search",
       "status",
@@ -265,6 +521,7 @@ var publicCatalog = {
       "401",
       "403",
       "404",
+      "408",
       "409",
       "413",
       "422",
@@ -288,6 +545,48 @@ var publicCatalog = {
   },
   // Built-in contracts only; application codes and provider response text are excluded.
   errorCodes: [
+    "UNCLASSIFIED_FAILURE",
+    "HTTP_UNAUTHORIZED",
+    "HTTP_FORBIDDEN",
+    "HTTP_NOT_FOUND",
+    "HTTP_TIMEOUT",
+    "HTTP_CONFLICT",
+    "HTTP_TOO_LARGE",
+    "HTTP_RATE_LIMITED",
+    "HTTP_SERVER_ERROR",
+    "HTTP_INVALID_REQUEST",
+    "NETWORK_DNS_FAILED",
+    "NETWORK_CONNECTION_REFUSED",
+    "NETWORK_CONNECTION_RESET",
+    "NETWORK_TIMEOUT",
+    "NETWORK_TLS_FAILED",
+    "CLI_ARGUMENT_INVALID",
+    "CLI_EXIT_FAILED",
+    "KTX_TOPOLOGY_INCOMPLETE",
+    "STUDIO_NOT_CONFIGURED",
+    "STUDIO_RESPONSE_INVALID",
+    "EVAL_CONCURRENCY_CHANGED",
+    "EVAL_CONSUMER_FAILED",
+    "EVAL_CONTRACT_CHANGED",
+    "EVAL_DISCOVERY_REJECTED",
+    "EVAL_EXECUTION_CONFLICT",
+    "EVAL_EXECUTION_STORE_CHANGED",
+    "EVAL_EXECUTION_UNKNOWN",
+    "EVAL_EXECUTOR_BUSY",
+    "EVAL_EXECUTOR_FAILED",
+    "EVAL_EXECUTOR_REJECTED",
+    "EVAL_EXECUTOR_UNAUTHORIZED",
+    "EVAL_GRADING_FAILED",
+    "EVAL_GRADING_TIMEOUT",
+    "EVAL_JUDGE_UNAVAILABLE",
+    "EVAL_LEASE_LOST",
+    "EVAL_RETRY_DELAY_EXCEEDED",
+    "EVAL_SETUP_TIMEOUT",
+    "EVAL_TRANSPORT_UNAVAILABLE",
+    "EVAL_VERIFICATION_TIMEOUT",
+    "EVAL_RESULT_INVALID",
+    "EVAL_RUN_TIMEOUT",
+    "EVAL_SETTINGS_INVALID",
     "EXECUTION_FAILED",
     "INVALID_REQUEST",
     "INVALID_RESUME",
@@ -355,8 +654,8 @@ function scale(value) {
   return value <= 1 ? "1" : value <= 5 ? "2-5" : value <= 20 ? "6-20" : value <= 100 ? "21-100" : "101+";
 }
 
-// src/client.ts
-function property(value, key) {
+// src/failure.ts
+function usageErrorProperty(value, key) {
   try {
     if (!value || typeof value !== "object") return void 0;
     const descriptor = Object.getOwnPropertyDescriptor(value, key);
@@ -365,40 +664,201 @@ function property(value, key) {
     return void 0;
   }
 }
-function classifyUsageError(error, catalog = publicCatalog) {
-  const name = property(error, "name");
-  const code = property(error, "code") ?? property(property(error, "failure"), "code");
-  if (name === "AbortError" || code === "EXECUTION_CANCELLED")
+var networkCodes = {
+  ENOTFOUND: "NETWORK_DNS_FAILED",
+  EAI_AGAIN: "NETWORK_DNS_FAILED",
+  ECONNREFUSED: "NETWORK_CONNECTION_REFUSED",
+  ECONNRESET: "NETWORK_CONNECTION_RESET",
+  EPIPE: "NETWORK_CONNECTION_RESET",
+  ETIMEDOUT: "NETWORK_TIMEOUT",
+  UND_ERR_CONNECT_TIMEOUT: "NETWORK_TIMEOUT",
+  UND_ERR_HEADERS_TIMEOUT: "NETWORK_TIMEOUT",
+  UND_ERR_BODY_TIMEOUT: "NETWORK_TIMEOUT",
+  CERT_HAS_EXPIRED: "NETWORK_TLS_FAILED",
+  DEPTH_ZERO_SELF_SIGNED_CERT: "NETWORK_TLS_FAILED",
+  UNABLE_TO_VERIFY_LEAF_SIGNATURE: "NETWORK_TLS_FAILED"
+};
+function classifyUsageHttpStatus(status) {
+  if (!Number.isInteger(status) || status < 100 || status > 599)
+    return {
+      outcome: "failed",
+      properties: {
+        error_code: "UNCLASSIFIED_FAILURE",
+        error_category: "unknown"
+      }
+    };
+  if (status < 400)
+    return {
+      outcome: "success",
+      properties: { http_status_class: `${Math.floor(status / 100)}xx` }
+    };
+  const code = status === 401 ? "HTTP_UNAUTHORIZED" : status === 403 ? "HTTP_FORBIDDEN" : status === 404 ? "HTTP_NOT_FOUND" : status === 408 || status === 504 ? "HTTP_TIMEOUT" : status === 409 ? "HTTP_CONFLICT" : status === 413 ? "HTTP_TOO_LARGE" : status === 429 ? "HTTP_RATE_LIMITED" : status >= 500 ? "HTTP_SERVER_ERROR" : "HTTP_INVALID_REQUEST";
+  return {
+    outcome: "failed",
+    properties: {
+      error_code: code,
+      error_category: status >= 500 || status === 408 ? "transport" : "request",
+      http_status: String(status),
+      http_status_class: `${Math.floor(status / 100)}xx`,
+      retryable: status === 408 || status === 429 || status >= 500
+    }
+  };
+}
+function nativeExceptionName(value) {
+  try {
+    if (typeof DOMException !== "undefined")
+      return Object.getOwnPropertyDescriptor(
+        DOMException.prototype,
+        "name"
+      )?.get?.call(value);
+  } catch {
+  }
+  return void 0;
+}
+function classifyOne(error, catalog) {
+  const read = (key) => usageErrorProperty(error, key);
+  let name = read("name") ?? nativeExceptionName(error);
+  try {
+    if (name === void 0 && error instanceof SyntaxError)
+      name = "SyntaxError";
+  } catch {
+  }
+  const code = read("code");
+  if (name === "AbortError" || code === "EXECUTION_CANCELLED" || code === "ABORT_ERR")
     return { outcome: "cancelled", properties: {} };
   if (code === "EXECUTION_LIMIT_REACHED" || name === "ExecutionLimitReached")
     return { outcome: "limit_reached", properties: {} };
-  if (name === "GraphInterrupt" || name === "NodeInterrupt" || name === "Interrupt")
+  if (typeof name === "string" && [
+    "GraphInterrupt",
+    "NodeInterrupt",
+    "Interrupt",
+    "ParallelChildWaiting"
+  ].includes(name))
     return { outcome: "suspended", properties: {} };
-  const known = typeof code === "string" && catalog.errorCodes.includes(code);
-  const category = known && code !== "EXECUTION_FAILED" ? property(error, "category") ?? property(property(error, "failure"), "category") ?? "unknown" : "unknown";
-  const status = property(error, "status") ?? property(property(error, "failure"), "status");
-  return {
-    outcome: "failed",
-    properties: {
-      error_code: known ? code : "other",
-      error_category: category,
-      ...typeof status === "number" ? { http_status: String(status) } : {}
+  if (name === "EvalConfigurationError")
+    return {
+      outcome: "failed",
+      properties: {
+        error_code: "EVAL_SETTINGS_INVALID",
+        error_category: "configuration",
+        retryable: false
+      }
+    };
+  if (name === "TimeoutError")
+    return {
+      outcome: "failed",
+      properties: {
+        error_code: "NETWORK_TIMEOUT",
+        error_category: "transport",
+        retryable: true
+      }
+    };
+  if (typeof code === "string" && Object.hasOwn(networkCodes, code))
+    return {
+      outcome: "failed",
+      properties: {
+        error_code: networkCodes[code] ?? "UNCLASSIFIED_FAILURE",
+        error_category: "transport",
+        retryable: true
+      }
+    };
+  if (typeof code === "string" && catalog.errorCodes.includes(code)) {
+    const failure = usageErrorProperty(error, "failure");
+    const category = read("category") ?? usageErrorProperty(failure, "category");
+    const retryable = read("retryable") ?? usageErrorProperty(failure, "retryable");
+    const status2 = read("status") ?? usageErrorProperty(failure, "status");
+    return {
+      outcome: "failed",
+      properties: {
+        ...typeof status2 === "number" ? classifyUsageHttpStatus(status2).properties : {},
+        // The framework code is more specific than its HTTP projection.
+        error_code: code,
+        error_category: code !== "EXECUTION_FAILED" && typeof category === "string" && Array.isArray(catalog.properties.error_category) && catalog.properties.error_category.includes(category) ? category : "unknown",
+        ...typeof retryable === "boolean" ? { retryable } : {}
+      }
+    };
+  }
+  const status = read("status") ?? read("statusCode");
+  if (typeof status === "number" && Number.isInteger(status) && status >= 400 && status <= 599)
+    return classifyUsageHttpStatus(status);
+  if (name === "ZodError" || name === "SyntaxError")
+    return {
+      outcome: "failed",
+      properties: {
+        error_code: "SCHEMA_VALIDATION",
+        error_category: "validation"
+      }
+    };
+  return void 0;
+}
+function classifyUsageError(error, catalog = publicCatalog) {
+  const seen = /* @__PURE__ */ new Set();
+  const pending = [{ value: error, depth: 0 }];
+  let result;
+  while (pending.length && seen.size < 8) {
+    const current = pending.shift();
+    if (!current || seen.has(current.value)) continue;
+    seen.add(current.value);
+    const found = classifyOne(current.value, catalog);
+    if (found) {
+      if (!result) result = found;
+      else if (found.properties.error_code && found.outcome === "failed" && found.properties.error_code !== result.properties.error_code) {
+        result.properties.cause_code = found.properties.error_code;
+        result.properties.cause_category = found.properties.error_category ?? "unknown";
+        if (result.properties.retryable === void 0 && typeof found.properties.retryable === "boolean")
+          result.properties.retryable = found.properties.retryable;
+        break;
+      }
+      if (result === found && found.outcome !== "failed") return found;
     }
+    if (current.depth < 3)
+      for (const key of ["failure", "cause", "error"]) {
+        const value = usageErrorProperty(current.value, key);
+        if (value && typeof value === "object")
+          pending.push({ value, depth: current.depth + 1 });
+      }
+  }
+  return result ?? {
+    outcome: "failed",
+    properties: { error_code: "other", error_category: "unknown" }
   };
 }
+
+// src/measurement.ts
+function usageMeasurement(event, operation, input) {
+  if (event === "usage.feature")
+    return usageErrorProperty(input, "origin") === "background" || usageErrorProperty(input, "origin") === "server" ? "observation" : "feature";
+  if (operation === "cli.command" || operation === "sdk.eval")
+    return "invocation";
+  if (operation === "studio.setup") return "stage";
+  if (operation === "sdk.execution" || operation === "studio.eval.execution")
+    return "execution";
+  if (operation === "sdk.export" || operation === "sdk.model") return "attempt";
+  if (operation === "sdk.structured") {
+    const format = usageErrorProperty(input, "format");
+    return format === "text-delta" ? "chunk" : format === "final" ? "output" : "update";
+  }
+  if (usageErrorProperty(input, "origin") === "background") return "poll";
+  if (operation.startsWith("studio.")) return "request";
+  return "call";
+}
+
+// src/client.ts
 function sanitizeProperties(input, catalog = publicCatalog) {
   const safe = {};
   for (const [key, rule] of Object.entries(catalog.properties)) {
-    const value = property(input, key);
+    const value = usageErrorProperty(input, key);
     if (value === void 0) continue;
     if (rule === "boolean") {
       if (typeof value === "boolean") safe[key] = value;
     } else if (typeof value === "string")
       safe[key] = rule.includes(value) ? value : "other";
   }
-  const code = property(input, "error_code");
-  if (typeof code === "string")
-    safe.error_code = catalog.errorCodes.includes(code) ? code : "other";
+  for (const key of ["error_code", "cause_code"]) {
+    const code = usageErrorProperty(input, key);
+    if (typeof code === "string")
+      safe[key] = catalog.errorCodes.includes(code) ? code : "other";
+  }
   return safe;
 }
 var durationBounds = [10, 100, 1e3, 1e4, 6e4];
@@ -419,6 +879,16 @@ function createUsageTelemetry(options) {
   let disposed = false;
   let dropped = 0;
   let delivered = 0;
+  let lostObservations = 0;
+  let failedBatches = 0;
+  let reportedLoss = 0;
+  let reportedFailures = 0;
+  const lose = (count) => {
+    lostObservations = Math.min(
+      Number.MAX_SAFE_INTEGER,
+      lostObservations + count
+    );
+  };
   let hour = Math.floor(now() / 36e5);
   let sent = 0;
   const active = () => {
@@ -454,6 +924,10 @@ function createUsageTelemetry(options) {
     pending.clear();
     if (!records.length) return;
     let attempted = records.length;
+    let attemptedObservations = records.reduce(
+      (total, record2) => total + record2.count,
+      0
+    );
     flight = (async () => {
       try {
         if (options.debug?.()) {
@@ -471,7 +945,14 @@ function createUsageTelemetry(options) {
         );
         const batch = records.slice(0, allowance);
         dropped += records.length - batch.length;
+        lose(
+          records.slice(allowance).reduce((total, record2) => total + record2.count, 0)
+        );
         attempted = batch.length;
+        attemptedObservations = batch.reduce(
+          (total, record2) => total + record2.count,
+          0
+        );
         if (!batch.length || !active()) return;
         const identified = await options.identity();
         const identity = typeof identified === "string" ? identified : identified.id;
@@ -482,13 +963,25 @@ function createUsageTelemetry(options) {
           identity
         )) {
           dropped += batch.length;
+          lose(attemptedObservations);
           return;
         }
         sent += batch.length;
+        const lossSnapshot = lostObservations;
+        const failureSnapshot = failedBatches;
+        if (batch[0] && (lossSnapshot > reportedLoss || failureSnapshot > reportedFailures))
+          batch[0].delivery_health = {
+            dropped_observations: lossSnapshot - reportedLoss,
+            failed_batches: failureSnapshot - reportedFailures
+          };
         await options.transport(batch, identity);
+        reportedLoss = lossSnapshot;
+        reportedFailures = failureSnapshot;
         delivered += batch.length;
       } catch {
         dropped += attempted;
+        lose(attemptedObservations);
+        failedBatches = Math.min(Number.MAX_SAFE_INTEGER, failedBatches + 1);
       }
     })().finally(() => {
       flight = void 0;
@@ -512,12 +1005,29 @@ function createUsageTelemetry(options) {
       }
       if (!configured || !catalog.operations.includes(operation) || !outcomes.includes(outcome))
         return;
-      const properties = sanitizeProperties(input, catalog);
+      const failed = outcome === "failed";
+      const status = usageErrorProperty(input, "http_status");
+      const http = typeof status === "string" && /^\d{3}$/.test(status) ? classifyUsageHttpStatus(Number(status)).properties : {};
+      const properties = sanitizeProperties(
+        {
+          measurement_version: "2",
+          measurement_kind: usageMeasurement(event, operation, input),
+          ...failed ? {
+            error_code: "UNCLASSIFIED_FAILURE",
+            error_category: "unknown",
+            ...http
+          } : {},
+          ...sanitizeProperties(input, catalog),
+          traffic_source: options.context.trafficSource ?? "unknown"
+        },
+        catalog
+      );
       const key = JSON.stringify([event, operation, outcome, properties]);
       let existing = pending.get(key);
       if (!existing) {
         if (pending.size >= (options.maxGroups ?? 64)) {
           dropped++;
+          lose(1);
           return;
         }
         existing = {
@@ -529,7 +1039,9 @@ function createUsageTelemetry(options) {
           component: options.context.component,
           version: options.context.version,
           analytics_environment: options.context.environment ?? "production",
-          runtime_mode: options.context.runtimeMode ?? "unknown",
+          runtime_mode: ["development", "production", "ci"].includes(
+            options.context.runtimeMode ?? ""
+          ) ? options.context.runtimeMode ?? "unknown" : "unknown",
           identity_scope: options.context.identityScope ?? "installation",
           operation,
           outcome,
@@ -574,8 +1086,11 @@ function createUsageTelemetry(options) {
           if (ended) return;
           ended = true;
           try {
+            const status = usageErrorProperty(extra, "http_status");
+            const http = outcome === "failed" && typeof status === "string" && /^\d{3}$/.test(status) ? classifyUsageHttpStatus(Number(status)).properties : {};
             record("usage.operation", operation, outcome, now() - began, {
               ...initial,
+              ...http,
               ...sanitizeProperties(extra, catalog)
             });
           } catch {
@@ -658,6 +1173,10 @@ function createPostHogTransport(options) {
         count: record.count,
         duration_total_ms: record.duration_total_ms,
         duration_buckets: record.duration_buckets,
+        ...record.delivery_health ? {
+          usage_dropped_observations: record.delivery_health.dropped_observations,
+          usage_failed_batches: record.delivery_health.failed_batches
+        } : {},
         $process_person_profile: false,
         $geoip_disable: true,
         $ip: null
@@ -712,6 +1231,7 @@ function createCollectorTransport(options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   classifyUsageError,
+  classifyUsageHttpStatus,
   createCollectorTransport,
   createPostHogTransport,
   createUsageTelemetry,