feat(events): add hard cap to event write

This applies to both client side and server side events.
Two write points for events to clickhouse-batch route for client side events, and logEvent for server side.

Max batch size for client side events is 500.
We decrease item quantity after batch is uploaded for clickhouse. The alternative is to either do a check for eventsItem.quantity -batchSize <=0 before the upload and block upsert based on it (which would result in users not getting their full limit) or doing some weird partial batch upload.
At most, with this approach, we would give users ~500 extra events. This is 0.5% extra on free plan, so we judge that it is ok.

frontend-banners pop up on analytics when at 80%+ and when you hit your limit, with an option to upgrade your plan.

We deliberated using tryDecreaseQuantity instead to both check and debit items, but there is potential for debit to happen even when clickhouse is down with that approach. This would be worse for users, so we accept the slight race condition.

Manual testing: on local, changed events for free and team plan to smaller numbers. Checked analytics tables to verify no new events being added after limit reached.

Author: nams1570

apps/backend/src/app/api/latest/analytics/events/batch/route.tsx

@@ -1,8 +1,11 @@
 import { getClickhouseAdminClient } from "@/lib/clickhouse";
+import { getBillingTeamId } from "@/lib/plan-entitlements";
 import { findRecentSessionReplay } from "@/lib/session-replays";
+import { getStackServerApp } from "@/stack";
 import { getPrismaClientForTenancy } from "@/prisma-client";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
 import { KnownErrors } from "@stackframe/stack-shared";
+import { ITEM_IDS } from "@stackframe/stack-shared/dist/plans";
 import { adaptSchema, clientOrHigherAuthTypeSchema, yupArray, yupMixed, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
 
@@ -61,6 +64,16 @@ export const POST = createSmartRouteHandler({
     const refreshTokenId = auth.refreshTokenId;
     const tenancyId = auth.tenancy.id;
 
+    const app = getStackServerApp();
+
+    const billingTeamId = getBillingTeamId(auth.tenancy.project);
+    if (billingTeamId != null) {
+      const eventsItem = await app.getItem({ itemId: ITEM_IDS.analyticsEvents, teamId: billingTeamId });
+      if (eventsItem.quantity <= 0) {
+        throw new KnownErrors.ItemQuantityInsufficientAmount(ITEM_IDS.analyticsEvents, billingTeamId, eventsItem.quantity);
+      }
+    }
+
     const prisma = await getPrismaClientForTenancy(auth.tenancy);
     const recentSession = await findRecentSessionReplay(prisma, { tenancyId, refreshTokenId });
 
@@ -89,6 +102,11 @@ export const POST = createSmartRouteHandler({
       },
     });
 
+    if (billingTeamId != null) {
+      const eventsItem = await app.getItem({ itemId: ITEM_IDS.analyticsEvents, teamId: billingTeamId });
+      await eventsItem.decreaseQuantity(body.events.length);
+    }
+
     return {
       statusCode: 200,
       bodyType: "json",

apps/backend/src/lib/events.tsx

@@ -1,9 +1,12 @@
 import withPostHog from "@/analytics";
 import { globalPrismaClient } from "@/prisma-client";
+import { getBillingTeamId } from "@/lib/plan-entitlements";
+import { getStackServerApp } from "@/stack";
 import { runAsynchronouslyAndWaitUntil } from "@/utils/vercel";
+import { ITEM_IDS } from "@stackframe/stack-shared/dist/plans";
 import { urlSchema, yupBoolean, yupMixed, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { getEnvVariable, getNodeEnvironment } from "@stackframe/stack-shared/dist/utils/env";
-import { StackAssertionError, throwErr } from "@stackframe/stack-shared/dist/utils/errors";
+import { captureError, StackAssertionError, throwErr } from "@stackframe/stack-shared/dist/utils/errors";
 import { HTTP_METHODS } from "@stackframe/stack-shared/dist/utils/http";
 import { filterUndefined, typedKeys } from "@stackframe/stack-shared/dist/utils/objects";
 import { UnionToIntersection } from "@stackframe/stack-shared/dist/utils/types";
@@ -264,6 +267,31 @@ export async function logEvent<T extends EventType[]>(
 
   // rest is no more dynamic APIs so we can run it asynchronously
   runAsynchronouslyAndWaitUntil((async () => {
+    // Resolve billing team for analytics event quota enforcement
+    let billingTeamId: string | null = null;
+    if (projectId) {
+      const project = await globalPrismaClient.project.findUnique({
+        where: { id: projectId },
+        select: { id: true, ownerTeamId: true },
+      });
+      if (project != null) {
+        billingTeamId = getBillingTeamId(project);
+      }
+    }
+
+    // Check analytics event limit before writing anything (Postgres + ClickHouse treated as atomic)
+    if (billingTeamId != null) {
+      const app = getStackServerApp();
+      const eventsItem = await app.getItem({ itemId: ITEM_IDS.analyticsEvents, teamId: billingTeamId });
+      if (eventsItem.quantity <= 0) {
+        captureError("logEvent", new StackAssertionError(
+          `Analytics event limit exceeded, dropping event. Project: ${projectId}, owner team: ${billingTeamId}, remaining quantity: ${eventsItem.quantity}`,
+          { projectId, ownerTeamId: billingTeamId },
+        ));
+        return;
+      }
+    }
+
     // log event in DB
     await globalPrismaClient.event.create({
       data: {
@@ -377,6 +405,13 @@ export async function logEvent<T extends EventType[]>(
       });
     }
 
+    // Debit analytics event quota after successful writes
+    if (billingTeamId != null) {
+      const app = getStackServerApp();
+      const eventsItem = await app.getItem({ itemId: ITEM_IDS.analyticsEvents, teamId: billingTeamId });
+      await eventsItem.decreaseQuantity(1);
+    }
+
     // log event in PostHog
     if (getNodeEnvironment().includes("production") && !getEnvVariable("CI", "")) {
       await withPostHog(async posthog => {

apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/analytics/queries/page-client.tsx

@@ -35,6 +35,7 @@ import { AppEnabledGuard } from "../../app-enabled-guard";
 import { PageLayout } from "../../page-layout";
 import { useAdminApp } from "../../use-admin-app";
 import {
+  AnalyticsEventLimitBanner,
   ErrorDisplay,
   FolderWithId,
   RowData,
@@ -838,6 +839,7 @@ export default function PageClient() {
   return (
     <AppEnabledGuard appId="analytics">
       <PageLayout fillWidth noPadding>
+        <AnalyticsEventLimitBanner />
         <QueriesContent />
       </PageLayout>
     </AppEnabledGuard>

apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/analytics/replays/page-client.tsx

@@ -26,6 +26,7 @@ import { TeamSearchTable } from "@/components/data-table/team-search-table";
 import { AppEnabledGuard } from "../../app-enabled-guard";
 import { PageLayout } from "../../page-layout";
 import { useAdminApp } from "../../use-admin-app";
+import { AnalyticsEventLimitBanner } from "../shared";
 import {
   createInitialState,
   replayReducer,
@@ -1384,6 +1385,7 @@ export default function PageClient() {
   return (
     <AppEnabledGuard appId="analytics">
       <PageLayout title="Session Replays" fillWidth>
+        <AnalyticsEventLimitBanner />
         <PanelGroup direction="horizontal" className="!h-[calc(100vh-180px)] min-h-[520px] rounded-xl border border-border/40 overflow-hidden bg-background">
           <Panel defaultSize={25} minSize={16}>
             <div className="h-full flex flex-col">

apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/analytics/shared.tsx

@@ -14,9 +14,13 @@ import {
   ArrowClockwiseIcon,
   WarningCircleIcon
 } from "@phosphor-icons/react";
+import { Alert, AlertDescription, Button } from "@/components/ui";
+import { useUser } from "@stackframe/stack";
+import { PLAN_LIMITS, type PlanId } from "@stackframe/stack-shared/dist/plans";
 import { runAsynchronouslyWithAlert } from "@stackframe/stack-shared/dist/utils/promises";
 import { useVirtualizer } from "@tanstack/react-virtual";
 import { useMemo, useRef } from "react";
+import { useAdminApp } from "../use-admin-app";
 
 // ============================================================================
 // Types
@@ -316,3 +320,83 @@ export function ErrorDisplay({ error, onRetry }: { error: unknown, onRetry: () =
     </div>
   );
 }
+
+function resolvePlanId(products: Array<{ id: string | null, type: string }>): PlanId {
+  if (products.some(p => p.id === "growth" && p.type === "subscription")) return "growth";
+  if (products.some(p => p.id === "team" && p.type === "subscription")) return "team";
+  return "free";
+}
+
+/**
+ * Shows a warning banner when analytics event usage is at 80%+ or 100%.
+ * Fetches the billing team's analytics_events item and computes usage against the plan's total allocation.
+ */
+export function AnalyticsEventLimitBanner() {
+  const adminApp = useAdminApp();
+  const project = adminApp.useProject();
+  const user = useUser({ or: "redirect", projectIdMustMatch: "internal" });
+  const teams = user.useTeams();
+
+  const ownerTeam = useMemo(
+    () => teams.find(t => t.id === project.ownerTeamId),
+    [teams, project.ownerTeamId],
+  );
+
+  if (ownerTeam == null) {
+    return null;
+  }
+
+  return <AnalyticsEventLimitBannerInner team={ownerTeam} />;
+}
+
+function AnalyticsEventLimitBannerInner({ team }: { team: { useItem: (itemId: string) => { quantity: number }, useProducts: () => Array<{ id: string | null, type: string }>, createCheckoutUrl: (options: { productId: string, returnUrl: string }) => Promise<string> } }) {
+  const eventsItem = team.useItem("analytics_events");
+  const products = team.useProducts();
+  const planId = resolvePlanId(products);
+  const totalAllocation = PLAN_LIMITS[planId].analyticsEvents;
+  const used = totalAllocation - eventsItem.quantity;
+  const usagePercent = totalAllocation > 0 ? (used / totalAllocation) * 100 : 0;
+
+  if (usagePercent < 80) {
+    return null;
+  }
+
+  const isExhausted = eventsItem.quantity <= 0;
+  const canUpgrade = planId !== "growth";
+
+  const handleUpgrade = async () => {
+    const targetProduct = planId === "free" ? "team" : "growth";
+    const checkoutUrl = await team.createCheckoutUrl({
+      productId: targetProduct,
+      returnUrl: window.location.href,
+    });
+    window.location.assign(checkoutUrl);
+  };
+
+  return (
+    <Alert
+      variant={isExhausted ? "destructive" : "default"}
+      className={isExhausted ? undefined : "border-amber-500/50 text-amber-700 dark:text-amber-400 bg-amber-500/5 [&>svg]:text-amber-500"}
+    >
+      <WarningCircleIcon className="h-4 w-4" />
+      <AlertDescription className="flex items-center justify-between gap-3">
+        <span>
+          {isExhausted
+            ? "You've reached your analytics event limit. New events are no longer being tracked."
+            : "You're approaching your analytics event limit."
+          }
+          {canUpgrade && !isExhausted && " Consider upgrading your plan."}
+        </span>
+        {canUpgrade && (
+          <Button
+            size="sm"
+            variant={isExhausted ? "destructive" : "outline"}
+            onClick={handleUpgrade}
+          >
+            Upgrade plan
+          </Button>
+        )}
+      </AlertDescription>
+    </Alert>
+  );
+}

apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/analytics/tables/page-client.tsx

@@ -31,6 +31,7 @@ import { AppEnabledGuard } from "../../app-enabled-guard";
 import { PageLayout } from "../../page-layout";
 import { useAdminApp } from "../../use-admin-app";
 import {
+  AnalyticsEventLimitBanner,
   isDateValue,
   isJsonValue,
   JsonValue,
@@ -592,6 +593,7 @@ export default function PageClient() {
   return (
     <AppEnabledGuard appId="analytics">
       <PageLayout fillWidth noPadding>
+        <AnalyticsEventLimitBanner />
         <div className="flex flex-1 min-h-0 overflow-hidden -mx-2">
           {/* Left sidebar - table list (doesn't scroll, border extends full height) */}
           <div className="w-48 flex-shrink-0 border-r border-border/50 flex flex-col pl-2">