convex-occ-insights-quickstart

From Convex

The linked Convex cloud deployment has a fresh insight in `npx convex insights`: a new OCC (optimistic concurrency control) write conflict or a read-limit issue surfaced in the last 72h of deployment health data. This monitor polls `npx convex insights` every 10 minutes, filters to substantive lines (occRetried, occFailedPermanently, documentsRead/bytesRead Limit or Threshold), and notifies only on lines that were not present in the previous snapshot — so each notification means something NEW went wrong, not a replay of old history. When this fires, the playbook is: (1) For occRetried/occFailedPermanently — identify the function and table involved, shrink the transaction (read less, write less, finish faster), move contended counters or aggregates to the @convex-dev/aggregate or @convex-dev/sharded-counter components, and avoid read-modify-write patterns on hot documents that many mutations touch concurrently. (2) For documentsRead/bytesRead Limit or Threshold — the function is scanning too much data: add a .withIndex() to narrow the scan to exactly the rows needed, or switch to .paginate() instead of .collect() on large tables. Run `npx convex insights --details` for per-event detail showing exactly which function and table are conflicting or over-reading. Caveats: `npx convex insights` only works for cloud deployments with user-level auth — it errors on local/anonymous deployments and refuses deploy keys/project keys — so this monitor hard-guards and silently no-ops in those cases (no .env.local, CONVEX_DEPLOYMENT=anonymous, missing npx, or any non-zero/empty `npx convex insights` run). The first successful poll after arming is saved as a baseline without notifying, so stale 72h-old insights never fire on startup.

Security

Trust and execution context for this monitor

Command

Shell command executed when the monitor triggers

Details

Trigger condition and source location