convex/src/cli/insights.ts

Client for the Convex Cloud

import { Command } from "@commander-js/extra-typings";
// eslint-disable-next-line no-restricted-imports -- stdout output uses default chalk
import chalk from "chalk";
import { oneoffContext } from "../bundler/context.js";
import { logOutput } from "../bundler/log.js";
import {
  deploymentSelectionWithinProjectFromOptions,
  loadSelectedDeploymentCredentials,
} from "./lib/api.js";
import { actionDescription } from "./lib/command.js";
import { deploymentDashboardUrlPage } from "./lib/dashboard.js";
import { getDeploymentSelection } from "./lib/deploymentSelection.js";
import { type Insight, fetchInsights } from "./lib/insights.js";

function formatInsightKind(kind: string): string {
  switch (kind) {
    case "occRetried":
      return "OCC Retried";
    case "occFailedPermanently":
      return "OCC Failed Permanently";
    case "bytesReadLimit":
      return "Bytes Read Limit Exceeded";
    case "bytesReadThreshold":
      return "Bytes Read Near Limit";
    case "documentsReadLimit":
      return "Documents Read Limit Exceeded";
    case "documentsReadThreshold":
      return "Documents Read Near Limit";
    default:
      return kind;
  }
}

function formatFunctionName(insight: Insight): string {
  if (insight.componentPath) {
    return `${insight.componentPath}:${insight.functionId}`;
  }
  return insight.functionId;
}

function formatInsight(insight: Insight, details: boolean): string {
  const severity =
    insight.severity === "error"
      ? chalk.red(`[ERROR]`)
      : chalk.yellow(`[WARNING]`);
  const kind = formatInsightKind(insight.kind);
  const fn = chalk.bold(formatFunctionName(insight));

  let detail: string;
  if ("occCalls" in insight) {
    const table = insight.occTableName
      ? ` on table ${chalk.cyan(insight.occTableName)}`
      : "";
    detail = `${insight.occCalls} OCC conflict${insight.occCalls !== 1 ? "s" : ""}${table}`;
  } else {
    detail = `${insight.count} occurrence${insight.count !== 1 ? "s" : ""}`;
  }

  let output = `${severity} ${kind}: ${fn} — ${detail}`;

  if (details && insight.recentEvents && insight.recentEvents.length > 0) {
    output += "\n";
    for (const event of insight.recentEvents) {
      const time = chalk.dim(new Date(event.timestamp).toLocaleString());
      const reqId = chalk.dim(`req:${event.request_id}`);

      if ("occ_retry_count" in event) {
        const docId = event.occ_document_id
          ? ` doc:${event.occ_document_id}`
          : "";
        const source = event.occ_write_source
          ? ` source:${event.occ_write_source}`
          : "";
        output += `    ${time}  ${reqId}  retries:${event.occ_retry_count}${docId}${source}\n`;
      } else {
        const status = event.success ? chalk.green("ok") : chalk.red("fail");
        const calls = event.calls
          .map(
            (c) =>
              `${c.table_name}(${c.documents_read} docs, ${c.bytes_read} bytes)`,
          )
          .join(", ");
        output += `    ${time}  ${reqId}  ${status}  ${calls}\n`;
      }
    }
  }

  return output;
}

export const insights = new Command("insights")
  .summary("Show health insights for your deployment")
  .description(
    "Show health insights for a Convex deployment over the last 72 hours.\n" +
      "Displays OCC conflicts and resource limit issues that may indicate performance problems.\n\n" +
      "Only available for cloud deployments with user-level authentication.",
  )
  .allowExcessArguments(false)
  .option("--details", "Show recent events for each insight", false)
  .addDeploymentSelectionOptions(actionDescription("Show insights for"))
  .showHelpAfterError()
  .action(async (cmdOptions) => {
    const ctx = await oneoffContext(cmdOptions);

    const selectionWithinProject =
      deploymentSelectionWithinProjectFromOptions(cmdOptions);
    const deploymentSelection = await getDeploymentSelection(ctx, cmdOptions);
    const credentials = await loadSelectedDeploymentCredentials(
      ctx,
      deploymentSelection,
      selectionWithinProject,
    );

    const deploymentName = credentials.deploymentFields?.deploymentName ?? null;
    if (deploymentName === null) {
      return await ctx.crash({
        exitCode: 1,
        errorType: "fatal",
        printedMessage:
          "Insights are only available for cloud deployments. Local deployments do not have insights data.",
      });
    }

    const auth = ctx.bigBrainAuth();
    if (
      auth === null ||
      auth.kind === "deploymentKey" ||
      auth.kind === "projectKey"
    ) {
      return await ctx.crash({
        exitCode: 1,
        errorType: "fatal",
        printedMessage:
          "Insights require user-level authentication. Deploy keys and project keys cannot access team usage data.",
      });
    }

    const insightsList = await fetchInsights(ctx, deploymentName, {
      includeRecentEvents: cmdOptions.details,
    });

    const dashboardUrl = deploymentDashboardUrlPage(
      deploymentName,
      "/insights",
    );

    if (insightsList.length === 0) {
      logOutput(
        chalk.green(
          "No issues found. The deployment is healthy over the last 72 hours.",
        ),
      );
    } else {
      const errorCount = insightsList.filter(
        (i) => i.severity === "error",
      ).length;
      const warningCount = insightsList.filter(
        (i) => i.severity === "warning",
      ).length;

      const parts: string[] = [];
      if (errorCount > 0)
        parts.push(
          chalk.red(`${errorCount} error${errorCount > 1 ? "s" : ""}`),
        );
      if (warningCount > 0)
        parts.push(
          chalk.yellow(`${warningCount} warning${warningCount > 1 ? "s" : ""}`),
        );
      logOutput(`Found ${parts.join(" and ")} in the last 72 hours:\n`);

      for (const insight of insightsList) {
        logOutput(formatInsight(insight, cmdOptions.details));
      }
    }

    logOutput(`\nDashboard: ${chalk.cyan(dashboardUrl)}`);
  });