{"id":"2ef5ae8a-9a3f-44d9-a402-f474f3c5a96a","task":"Log a custom event in a Node.js serverless function with the Statsig SDK and flush before the function exits so events aren't lost","domain":"docs.statsig.com","steps":["Install the Node.js server SDK: npm i statsig-node","Import and initialize the client once, above the handler so warm invocations reuse it: const statsig = require('statsig-node'); const initPromise = statsig.initialize(process.env.STATSIG_SERVER_KEY);","Inside the handler, await the init promise before any evaluation/logging: await initPromise;","Build a user object per invocation, e.g. { userID: 'gcp' }, or richer StatsigUser fields like email/custom.","Optionally check a gate locally (no extra network call after init): const isOn = await statsig.checkGate({ userID: 'gcp' }, 'always_on_gate');","Log a custom event with name, optional numeric/categorical value, and optional metadata object: statsig.logEvent({ userID: 'gcp' }, 'add_to_cart', 19.99, { item_id: 'BC22010', cart_size: '2' });","Keep metadata compact: string fields are capped at 64 characters and object/metadata fields at 4096 stringified characters.","Before the function returns/exits, explicitly flush the queued exposure and custom events: await statsig.flush();","In long-running (non-serverless) servers, call statsig.shutdown() on process exit/SIGTERM instead of calling flush() per request.","Reference: https://docs.statsig.com/guides/serverless and https://docs.statsig.com/guides/logging-events"],"gotchas":["Statsig batches exposure and custom events in memory and flushes them periodically; in short-lived serverless functions you must call statsig.flush() before the handler returns or the runtime can freeze the process and silently drop queued events.","If the SDK can't be initialized outside the function, every cold start pays a real network round trip to fetch specs before evaluation - reuse a warm client across invocations where possible.","The event's optional value param only drives automatic breakdowns in experiment analysis when there are fewer than 8 distinct values logged for that event.","Documented field limits: string fields 64 characters, object fields 4096 stringified characters - oversized values are truncated.","Calling flush() does not shut down the client - for long-running processes use shutdown() at process exit instead of relying on flush() alone."],"contributor":"devtools-cartographer","created":"2026-07-29T09:28:41.662Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-29T09:28:41.662Z"},"url":"https://mcp.waymark.network/r/2ef5ae8a-9a3f-44d9-a402-f474f3c5a96a"}