fix(posthog): flush on SIGTERM and log async capture errors (#217)

Author: saulmc

src/api/v2/agent-templates/services/posthog.ts

@@ -15,6 +15,7 @@
 /* eslint-disable @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-explicit-any */
 
 import { POSTHOG_HOST, POSTHOG_PROJECT_TOKEN } from "@/config";
+import logger from "@/utils/logger";
 import type { GenerationMetrics } from "./templateGen";
 
 // ---------------------------------------------------------------------------
@@ -73,6 +74,16 @@ function getPostHogClient(): any {
     PostHog: new (apiKey: string, opts: { host: string }) => any;
   };
   _posthogClient = new PostHog(POSTHOG_PROJECT_TOKEN, { host: POSTHOG_HOST });
+  // Surface async capture failures (auth 401s on a wrong token, wrong host,
+  // network errors). capture() is fire-and-forget so these are otherwise
+  // invisible — the request that triggered it has already returned. Subscribe
+  // once at client creation; client is cached for the lifetime of the process.
+  _posthogClient.on("error", (err: unknown) => {
+    logger.error(
+      { err: err instanceof Error ? err.message : err },
+      "[posthog] async capture error",
+    );
+  });
   return _posthogClient;
 }
 
@@ -129,9 +140,36 @@ export function capturePostHog(properties: PostHogCaptureProperties): void {
       properties,
     });
   } catch (err) {
-    console.error(
-      "[posthog] capture failed:",
-      err instanceof Error ? err.message : err,
+    logger.error(
+      { err: err instanceof Error ? err.message : err },
+      "[posthog] capture failed",
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Graceful shutdown
+// ---------------------------------------------------------------------------
+
+/**
+ * Flush any buffered events and tear down the PostHog client. Call once
+ * during SIGTERM so events captured in the last `flushInterval` window
+ * (default 10s in posthog-node v5) aren't lost when the process exits.
+ *
+ * No-op when the client was never created (env vars unset, or test
+ * override installed). Errors are caught and logged — never propagate
+ * to the caller so shutdown can continue.
+ */
+export async function shutdownPostHog(timeoutMs = 5000): Promise<void> {
+  const client = _posthogClient;
+  if (!client) return;
+  _posthogClient = null;
+  try {
+    await client.shutdown(timeoutMs);
+  } catch (err) {
+    logger.error(
+      { err: err instanceof Error ? err.message : err },
+      "[posthog] shutdown failed",
     );
   }
 }

src/index.ts

@@ -3,6 +3,7 @@ import cookieParser from "cookie-parser";
 import cors from "cors";
 import express from "express";
 import helmet from "helmet";
+import { shutdownPostHog } from "@/api/v2/agent-templates/services/posthog";
 import {
   startTtlSweep as startGenerationTtlSweep,
   stopTtlSweep as stopGenerationTtlSweep,
@@ -89,15 +90,26 @@ validateJWTKeys()
       }
     });
 
+    // Wrap the async drain steps in a void-IIFE so the SIGTERM listener
+    // itself returns void (Node ignores the listener's return value, and
+    // an `async` listener would trip @typescript-eslint/no-misused-promises).
+    // `shutdownPostHog()` catches its own errors, so the IIFE never rejects.
     process.on("SIGTERM", () => {
-      logger.info("SIGTERM signal received: closing Convos API service");
-      // Stop the generation TTL sweep so its setInterval doesn't keep
-      // dispatching DB queries against a closing pool during the drain
-      // window. No-op if the sweep was never started (production gate).
-      stopGenerationTtlSweep();
-      server.close(() => {
-        logger.info("Convos API service closed");
-      });
+      void (async () => {
+        logger.info("SIGTERM signal received: closing Convos API service");
+        // Stop the generation TTL sweep so its setInterval doesn't keep
+        // dispatching DB queries against a closing pool during the drain
+        // window. No-op if the sweep was never started (production gate).
+        stopGenerationTtlSweep();
+        // Flush buffered PostHog events before the process exits. The SDK
+        // buffers up to flushAt (default 20) or flushInterval (default 10s)
+        // — without an explicit shutdown, low-volume captures get dropped
+        // on every redeploy. Catches its own errors; never throws.
+        await shutdownPostHog();
+        server.close(() => {
+          logger.info("Convos API service closed");
+        });
+      })();
     });
   })
   .catch((error: unknown) => {