Statsig Experimentation Platform: Architecture and Rollouts

2 collapsed lines
1
// Download & Evaluate Locally Model
2
import { Statsig } from "@statsig/statsig-node-core"
3

4
// Initialize with full config download
5
const statsig = await Statsig.initialize("secret-key", {
6
  environment: { tier: "production" },
7
  rulesetsSyncIntervalMs: 10000,
8
})
9

10
// Synchronous, in-memory evaluation - the key pattern
11
function evaluateUserFeatures(user: StatsigUser) {
12
  const isFeatureEnabled = statsig.checkGate(user, "new_ui_feature")
13
  const config = statsig.getConfig(user, "pricing_tier")
14
  const experiment = statsig.getExperiment(user, "recommendation_algorithm")
15

16
  return {
17
    newUI: isFeatureEnabled,
18
    pricing: config.value,
19
    experiment: experiment.value,
20
  }
6 collapsed lines
21
}
22

23
// Sub-1ms evaluation, no network calls
24
const result = evaluateUserFeatures({
25
  userID: "user123",
26
  email: "user@example.com",
27
  custom: { plan: "premium" },
28
})

2 collapsed lines
1
// Pre-evaluated on Initialize Model
2
import { StatsigClient } from "@statsig/js-client"
3

4
// Initialize with user context - triggers network request
5
const client = new StatsigClient("client-key")
6
await client.initializeAsync({
7
  userID: "user123",
8
  email: "user@example.com",
9
  custom: { plan: "premium" },
10
})
11

12
// Synchronous cache lookup - the key pattern
13
function getFeatureFlags() {
14
  const isFeatureEnabled = client.checkGate("new_ui_feature")
15
  const config = client.getConfig("pricing_tier")
16
  const experiment = client.getExperiment("recommendation_algorithm")
17

18
  return {
19
    newUI: isFeatureEnabled,
20
    pricing: config.value,
21
    experiment: experiment.value,
22
  }
23
}
24

25
const result = getFeatureFlags() // Fast cache lookup, no network calls

8 collapsed lines
1
// Statsig's deterministic assignment algorithm (simplified)
2
import { createHash } from "crypto"
3

4
interface AssignmentResult {
5
  bucket: number
6
  assigned: boolean
7
  group?: string
8
}
9

10
function assignUser(userId: string, salt: string, allocation: number = 10000): AssignmentResult {
11
  // 1. Concatenate salt with user ID
12
  const input = salt + userId
13

14
  // 2. SHA-256 hash for uniform distribution
15
  const hash = createHash("sha256").update(input).digest("hex")
16

17
  // 3. Extract first 8 hex chars (32 bits) and convert to integer
18
  const first8Bytes = hash.substring(0, 8)
19
  const hashInt = parseInt(first8Bytes, 16)
20

21
  // 4. Modulo 10,000 for experiments (1,000 for layers)
22
  const bucket = hashInt % allocation
23

24
  // 5. Compare bucket to threshold for assignment
25
  const assigned = bucket < allocation * 0.1 // 10% allocation example
26

27
  return { bucket, assigned, group: assigned ? "treatment" : "control" }
28
}
29

3 collapsed lines
30
// Usage
31
const result = assignUser("user123", "experiment_salt_abc123", 10000)
32
console.log(`Bucket ${result.bucket}, group: ${result.group}`)

7 collapsed lines
1
import { Statsig } from "@statsig/statsig-node-core"
2

3
// Initialize once at startup
4
const statsig = await Statsig.initialize("secret-key", {
5
  environment: { tier: "production" },
6
  rulesetsSyncIntervalMs: 10000,
7
})
8

9
// Request handler - evaluations are synchronous, sub-1ms
10
function handleRequest(req: Request, res: Response) {
11
  const user = {
12
    userID: req.user.id,
13
    email: req.user.email,
14
    custom: { plan: req.user.plan },
15
  }
16

17
  const isFeatureEnabled = statsig.checkGate(user, "new_feature")
18
  const config = statsig.getConfig(user, "pricing_config")
19

20
  res.json({ feature: isFeatureEnabled, pricing: config.value })
21
}

2 collapsed lines
1
// Custom DataAdapter implementation for Redis
2
import { createClient, RedisClientType } from "redis"
3

4
interface DataAdapter {
5
  initialize(): Promise<void>
6
  get(key: string): Promise<string | null>
7
  set(key: string, value: string): Promise<void>
8
  shutdown(): Promise<void>
9
}
10

11
class RedisDataAdapter implements DataAdapter {
12
  private client: RedisClientType
13

14
  constructor(private config: { host: string; port: number; password?: string }) {
15
    this.client = createClient({ url: `redis://${config.host}:${config.port}` })
16
  }
17

18
  async initialize() {
19
    await this.client.connect()
20
  }
21

22
  // Cache keys follow: statsig|{path}|{format}|{hashedSDKKey}
23
  async get(key: string) {
24
    return this.client.get(key)
25
  }
26

27
  async set(key: string, value: string) {
28
    await this.client.set(key, value)
29
  }
30

31
  async shutdown() {
32
    await this.client.quit()
33
  }
34
}

4 collapsed lines
1
import { Statsig } from "@statsig/statsig-node-core"
2

3
const statsig = await Statsig.initialize("secret-key")
4

5
// Returns pre-computed evaluations for client SDK bootstrap
6
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
7
  const user = {
8
    userID: req.headers["x-user-id"] as string,
9
    email: req.headers["x-user-email"] as string,
10
  }
11

12
  const bootstrapValues = statsig.getClientInitializeResponse(user)
13
  res.json(bootstrapValues)
14
}

2 collapsed lines
1
import { StatsigClient } from '@statsig/js-client';
2

3
function MyApp({ Component, pageProps, bootstrapValues }) {
4
  const [statsig, setStatsig] = useState(null);
5

6
  useEffect(() => {
7
    const client = new StatsigClient('client-key');
8
    // Synchronous init with server-provided values - no network request
9
    client.initializeSync({ initializeValues: bootstrapValues });
10
    setStatsig(client);
11
  }, []);
12

13
  return <Component {...pageProps} statsig={statsig} />;
14
}

1
// Vercel Edge Config integration (official adapter)
2
import { EdgeConfigDataStore } from "@statsig/vercel-server"
3

4
const statsig = await Statsig.initialize("secret-key", {
5
  dataStore: new EdgeConfigDataStore(process.env.EDGE_CONFIG_ID),
6
})

1
// All services share the same Redis instance for config caching
2
const redisAdapter = new RedisDataAdapter({
3
  host: process.env.REDIS_HOST,
4
  port: parseInt(process.env.REDIS_PORT),
5
})
6

7
const statsig = await Statsig.initialize("secret-key", {
8
  dataStore: redisAdapter, // Implements DataAdapter interface
9
})

15 collapsed lines
1
// Cold start optimization: reuse SDK across invocations
2
let statsigInstance: Statsig | null = null
3

4
async function initStatsig() {
5
  if (!statsigInstance) {
6
    statsigInstance = await Statsig.initialize("secret-key", {
7
      dataStore: new RedisDataAdapter({
8
        host: process.env.REDIS_HOST,
9
        port: parseInt(process.env.REDIS_PORT),
10
      }),
11
    })
12
  }
13
  return statsigInstance
14
}
15

16
// Key pattern: SDK instance persists across Lambda invocations
17
export async function handler(event: APIGatewayEvent) {
18
  const statsig = await initStatsig() // Reuses existing instance
19
  const user = { userID: event.requestContext.authorizer.userId }
20
  const result = statsig.checkGate(user, "feature_flag")
21

22
  return { statusCode: 200, body: JSON.stringify({ feature: result }) }
23
}

2 collapsed lines
1
import { Statsig } from "@statsig/statsig-node-core"
2

3
let statsigInstance: Statsig | null = null
4

5
// Singleton pattern for Next.js server-side usage
6
export async function getStatsig() {
7
  if (!statsigInstance) {
8
    statsigInstance = await Statsig.initialize(process.env.STATSIG_SECRET_KEY!)
9
  }
10
  return statsigInstance
11
}
12

13
export async function getBootstrapValues(user: StatsigUser) {
14
  const statsig = await getStatsig()
15
  return statsig.getClientInitializeResponse(user)
16
}

4 collapsed lines
1
import { GetServerSideProps } from 'next';
2
import { StatsigClient } from '@statsig/js-client';
3
import { getBootstrapValues } from '../lib/statsig';
4

5
// Server-side: pre-compute evaluations for this user
6
export const getServerSideProps: GetServerSideProps = async (context) => {
7
  const user = {
8
    userID: context.req.headers['x-user-id'] as string || 'anonymous',
9
    custom: { source: 'web' }
10
  };
11

12
  const bootstrapValues = await getBootstrapValues(user);
13
  return { props: { bootstrapValues, user } };
14
};
15

16
// Client-side: instant initialization with no network request
17
export default function Home({ bootstrapValues, user }) {
6 collapsed lines
18
  const [statsig, setStatsig] = useState<StatsigClient | null>(null);
19

20
  useEffect(() => {
21
    const client = new StatsigClient(process.env.NEXT_PUBLIC_STATSIG_CLIENT_KEY!);
22
    client.initializeSync({ initializeValues: bootstrapValues });
23
    setStatsig(client);
24
  }, [bootstrapValues]);
25

26
  const isFeatureEnabled = statsig?.checkGate('new_feature') || false;
27

28
  return (
29
    <div>
30
      {isFeatureEnabled && <NewFeatureComponent />}
31
      <ExistingComponent />
32
    </div>
33
  );
34
}

2 collapsed lines
1
import { Statsig } from "@statsig/statsig-node-core"
2

3
export class FeatureService {
4
  private statsig: Statsig
5

6
  async initialize() {
7
    this.statsig = await Statsig.initialize(process.env.STATSIG_SECRET_KEY!)
8
  }
9

10
  // Sub-1ms synchronous evaluations
11
  evaluateFeatures(user: StatsigUser) {
12
    return {
13
      newUI: this.statsig.checkGate(user, "new_ui"),
14
      pricing: this.statsig.getConfig(user, "pricing_tier"),
15
      experiment: this.statsig.getExperiment(user, "recommendation_algorithm"),
16
    }
17
  }
18

19
  getBootstrapValues(user: StatsigUser) {
20
    return this.statsig.getClientInitializeResponse(user)
21
  }
22
}

4 collapsed lines
1
import { FeatureService } from "../services/feature-service"
2

3
const featureService = new FeatureService()
4

5
router.get("/features/:userId", async (req, res) => {
6
  const user = {
7
    userID: req.params.userId,
8
    email: req.headers["x-user-email"] as string,
9
    custom: { plan: req.headers["x-user-plan"] as string },
10
  }
11

12
  const features = featureService.evaluateFeatures(user) // Synchronous
13
  res.json(features)
14
})
15

16
router.get("/bootstrap/:userId", async (req, res) => {
17
  const user = { userID: req.params.userId }
18
  const bootstrapValues = featureService.getBootstrapValues(user)
19
  res.json(bootstrapValues)
20
})

2 collapsed lines
1
// Client SDK: graceful degradation on network failure
2
const client = new StatsigClient("client-key")
3

4
try {
5
  await client.initializeAsync(user)
6
} catch (error) {
7
  // Fallback hierarchy: cached values → defaults → graceful degradation
8
  console.warn("Statsig initialization failed:", error)
9
  client.initializeSync(user) // Uses localStorage cache if available
10
}
11

12
// All subsequent checks use cached values or return defaults
13
const isEnabled = client.checkGate("feature") // Never throws
14

15
// Server SDK: data store fallback for cold starts
16
const statsig = await Statsig.initialize("secret-key", {
6 collapsed lines
17
  dataStore: new RedisDataAdapter({
18
    host: process.env.REDIS_HOST,
19
    port: parseInt(process.env.REDIS_PORT),
20
  }),
21
  rulesetsSyncIntervalMs: 10000,
22
})

6 collapsed lines
1
const statsig = await Statsig.initialize("secret-key", {
2
  environment: { tier: "production" },
3
})
4

5
const metrics = new MetricsClient() // Your monitoring system
6

7
// Track evaluation latency (should be <1ms for server SDK)
8
function checkGateWithMetrics(user: StatsigUser, gateName: string) {
9
  const startTime = performance.now()
10
  const result = statsig.checkGate(user, gateName)
11
  const latency = performance.now() - startTime
12

13
  metrics.histogram("statsig.evaluation.latency_ms", latency)
14
  metrics.increment("statsig.evaluation.count", { gate: gateName })
15

16
  return result
17
}
18

19
// Key metrics to monitor:
20
// - Evaluation latency: <1ms for server SDK
21
// - Cache hit rate: percentage using cached configs
22
// - Sync success rate: config download success
23
// - Error rates: network failures, parsing errors

1
// Environment-specific keys - never commit secrets
2
const statsigKey = process.env.NODE_ENV === "production" ? process.env.STATSIG_SECRET_KEY : process.env.STATSIG_DEV_KEY
3

4
const statsig = await Statsig.initialize(statsigKey)

1
// Minimize PII sent to Statsig - only include attributes needed for targeting
2
const sanitizedUser = {
3
  userID: user.id, // Required for assignment
4
  custom: {
5
    plan: user.plan, // Needed for plan-based targeting
6
    region: user.region, // Needed for geo-targeting
7
    // Never include: SSN, credit card, passwords, full addresses
8
  },
9
}

1
// Shared config cache ensures consistent evaluation across instances
2
const redisAdapter = new RedisDataAdapter({
3
  host: process.env.REDIS_HOST,
4
  port: parseInt(process.env.REDIS_PORT),
5
})
6

7
const statsig = await Statsig.initialize("secret-key", {
8
  dataStore: redisAdapter,
9
  rulesetsSyncIntervalMs: 5000, // More frequent sync for consistency
10
})

7 collapsed lines
1
// Singleton pattern for centralized configuration
2
class StatsigConfig {
3
  private static instance: StatsigConfig
4
  private statsig: Statsig | null = null
5

6
  static async getInstance(): Promise<StatsigConfig> {
7
    if (!StatsigConfig.instance) {
8
      StatsigConfig.instance = new StatsigConfig()
9
      await StatsigConfig.instance.initialize()
10
    }
11
    return StatsigConfig.instance
12
  }
13

14
  private async initialize() {
15
    this.statsig = await Statsig.initialize(process.env.STATSIG_SECRET_KEY!, {
16
      environment: { tier: process.env.NODE_ENV },
17
    })
18
  }
19

20
  getStatsig(): Statsig {
21
    if (!this.statsig) throw new Error("Statsig not initialized")
22
    return this.statsig
23
  }
24
}

9 collapsed lines
1
// Unit testing with local mode - no network requests
2
describe("Feature Flag Tests", () => {
3
  let statsig: Statsig
4

5
  beforeEach(async () => {
6
    statsig = await Statsig.initialize("secret-key", {
7
      localMode: true, // Disables all network calls
8
    })
9
  })
10

11
  test("should enable feature for specific user", () => {
12
    // Override returns specified value for this user
13
    statsig.overrideGate("new_feature", true, "test-user")
14

15
    const result = statsig.checkGate({ userID: "test-user" }, "new_feature")
16
    expect(result).toBe(true)
17
  })
18
})