doc(flags): Document local eval in distributed envs (#14136)

* doc(flags): Document local eval in distributed envs

This change expands upon the Node.js external caching guide to provide
general information regarding Node.js and Python clients in distributed
/ stateless environments.

* doc: Drop redundant note

* docs: Fix missing link

Author: dustinbyrne

contents/docs/feature-flags/local-evaluation/_snippets/distributed-environments-common-patterns.mdx

@@ -0,0 +1,31 @@
+## Common patterns
+
+### Shared caches with locking
+
+When running multiple server instances with a shared cache like Redis, coordinate fetching so only one instance polls PostHog at a time.
+
+The recommended pattern:
+
+- One instance owns the lock for its entire lifetime, not just during a single fetch
+- Refresh the lock TTL each polling cycle to maintain ownership
+- Release on shutdown, but only if you own the lock
+- Let locks expire if a process crashes, so another instance can take over
+
+#### Redis example
+
+A complete working example written in Python using Redis with distributed locking is available in the [posthog-python repository](https://github.com/PostHog/posthog-python/blob/master/examples/redis_flag_cache.py). It implements the locking pattern described above.
+
+### Caches without locking
+
+Some storage backends like Cloudflare KV don't support atomic locking operations. In these cases, use a split read/write pattern:
+
+1. A scheduled job (cron) periodically fetches flag definitions and writes to the cache
+2. Request handlers read from the cache and evaluate flags locally, with no API calls
+
+This separates the concerns entirely. One process writes, all others read.
+
+#### Cloudflare Workers example
+
+A complete working example written in TypeScript is available in the [posthog-js repository](https://github.com/PostHog/posthog-js/tree/main/examples/example-cloudflare-kv-cache). It uses the split read/write pattern described above. The worker's scheduled job writes flag definitions to KV, and request handlers read from it.
+
+This pattern is ideal for high-traffic edge applications where flag evaluation must be extremely fast and you can tolerate flag updates being slightly delayed.

contents/docs/feature-flags/local-evaluation/_snippets/distributed-environments-intro.mdx

@@ -0,0 +1,21 @@
+When using [local evaluation](/docs/feature-flags/local-evaluation), the SDK fetches feature flag definitions and stores them in memory. This works well for single-instance applications, but in distributed or stateless environments (multiple servers, edge workers, lambdas), each instance fetches its own copy, wasting API calls and adding latency on cold starts.
+
+An **external cache provider** lets you store flag definitions in shared storage (Redis, database, Cloudflare KV, etc.) so all instances can read from a single source.
+
+This enables you to:
+
+- Share flag definitions across workers to reduce API calls
+- Coordinate fetching so only one worker polls at a time
+- Pre-cache definitions for ultra-low-latency flag evaluation
+
+> **Note:** External cache providers are currently available in Node.js and Python SDKs only. This feature is experimental and may change in minor versions.
+
+## When to use an external cache
+
+| Scenario | Recommendation |
+| :------- | :------------- |
+| Single server instance | SDK's built-in memory cache is sufficient |
+| Multiple workers (same process) | SDK's built-in memory cache is sufficient |
+| Multiple servers/containers | Use Redis or database caching with distributed locks |
+| Edge workers (Cloudflare, Vercel Edge) | Use KV storage with split read/write pattern |
+

contents/docs/feature-flags/local-evaluation/_snippets/distributed-environments-node.mdx

@@ -0,0 +1,64 @@
+## Installation
+
+Import the interface from the SDK:
+
+```typescript
+import { FlagDefinitionCacheProvider, FlagDefinitionCacheData } from 'posthog-node/experimental'
+```
+
+## The interface
+
+To create a custom cache, implement the `FlagDefinitionCacheProvider` interface:
+
+```typescript
+interface FlagDefinitionCacheProvider {
+  // Retrieve cached flag definitions
+  getFlagDefinitions(): Promise<FlagDefinitionCacheData | undefined> | FlagDefinitionCacheData | undefined
+
+  // Determine if this instance should fetch new definitions
+  shouldFetchFlagDefinitions(): Promise<boolean> | boolean
+
+  // Store definitions after a successful fetch
+  onFlagDefinitionsReceived(data: FlagDefinitionCacheData): Promise<void> | void
+
+  // Clean up resources on shutdown
+  shutdown(): Promise<void> | void
+}
+```
+
+When the SDK fetches flag definitions from the API, it passes a `FlagDefinitionCacheData` object to `onFlagDefinitionsReceived()` for you to store:
+
+```typescript
+interface FlagDefinitionCacheData {
+  flags: PostHogFeatureFlag[]               // Feature flag definitions
+  groupTypeMapping: Record<string, string>  // Group type index to name mapping
+  cohorts: Record<string, PropertyGroup>    // Cohort definitions for local evaluation
+}
+```
+
+### Method details
+
+| Method | Purpose | Return value |
+| :----- | :------ | :----------- |
+| `getFlagDefinitions()` | Retrieve cached definitions. Called when the poller refreshes. | Cached data, or `undefined` if cache is empty |
+| `shouldFetchFlagDefinitions()` | Decide if this instance should fetch. Use for distributed coordination (e.g., locks). | `true` to fetch, `false` to skip |
+| `onFlagDefinitionsReceived(data)` | Store definitions after a successful API fetch. | void |
+| `shutdown()` | Release locks, close connections, clean up resources. | void |
+
+> **Note:** All methods may throw errors. The SDK catches and logs them gracefully, ensuring cache provider errors never break flag evaluation.
+
+## Using your cache provider
+
+Pass your cache provider when initializing PostHog:
+
+```typescript
+import { PostHog } from 'posthog-node'
+
+const cache = new YourCacheProvider()
+
+const posthog = new PostHog('<ph_project_api_key>', {
+  personalApiKey: '<ph_personal_api_key>',
+  enableLocalEvaluation: true,
+  flagDefinitionCacheProvider: cache,
+})
+```

contents/docs/feature-flags/local-evaluation/_snippets/distributed-environments-python.mdx

@@ -0,0 +1,66 @@
+## Installation
+
+Import the interface from the SDK:
+
+```python
+from posthog import FlagDefinitionCacheProvider, FlagDefinitionCacheData
+```
+
+## The interface
+
+To create a custom cache, implement the `FlagDefinitionCacheProvider` protocol:
+
+```python
+class FlagDefinitionCacheProvider(Protocol):
+    def get_flag_definitions(self) -> Optional[FlagDefinitionCacheData]:
+        """Retrieve cached flag definitions."""
+        ...
+
+    def should_fetch_flag_definitions(self) -> bool:
+        """Determine if this instance should fetch new definitions."""
+        ...
+
+    def on_flag_definitions_received(self, data: FlagDefinitionCacheData) -> None:
+        """Store definitions after a successful fetch."""
+        ...
+
+    def shutdown(self) -> None:
+        """Clean up resources on shutdown."""
+        ...
+```
+
+When the SDK fetches flag definitions from the API, it passes a `FlagDefinitionCacheData` object to `on_flag_definitions_received()` for you to store:
+
+```python
+class FlagDefinitionCacheData(TypedDict):
+    flags: List[Dict[str, Any]]           # Feature flag definitions
+    group_type_mapping: Dict[str, str]    # Group type index to name mapping
+    cohorts: Dict[str, Any]               # Cohort definitions for local evaluation
+```
+
+### Method details
+
+| Method | Purpose | Return value |
+| :----- | :------ | :----------- |
+| `get_flag_definitions()` | Retrieve cached definitions. Called when the poller refreshes. | Cached data, or `None` if cache is empty |
+| `should_fetch_flag_definitions()` | Decide if this instance should fetch. Use for distributed coordination (e.g., locks). | `True` to fetch, `False` to skip |
+| `on_flag_definitions_received(data)` | Store definitions after a successful API fetch. | None |
+| `shutdown()` | Release locks, close connections, clean up resources. | None |
+
+> **Note:** All methods may throw errors. The SDK catches and logs them gracefully, ensuring cache provider errors never break flag evaluation.
+
+## Using your cache provider
+
+Pass your cache provider when initializing PostHog:
+
+```python
+from posthog import Posthog
+
+cache = YourCacheProvider()
+
+posthog = Posthog(
+    '<ph_project_api_key>',
+    personal_api_key='<ph_personal_api_key>',
+    flag_definition_cache_provider=cache,
+)
+```

contents/docs/feature-flags/local-evaluation/distributed-environments.mdx

@@ -0,0 +1,34 @@
+---
+title: Local evaluation in distributed or stateless environments
+sidebar: Docs
+showTitle: true
+availability:
+    free: full
+    selfServe: full
+    enterprise: full
+---
+
+import Tab from "components/Tab"
+import LocalEvalDistributedEnvIntro from "./_snippets/distributed-environments-intro.mdx"
+import LocalEvalDistributedEnvCommonPatterns from "./_snippets/distributed-environments-common-patterns.mdx"
+import LocalEvalDistributedEnvNodeContent from "./_snippets/distributed-environments-node.mdx"
+import LocalEvalDistributedEnvPythonContent from "./_snippets/distributed-environments-python.mdx"
+
+<LocalEvalDistributedEnvIntro />
+
+<Tab.Group tabs={['Node.js', 'Python']}>
+    <Tab.List>
+        <Tab>Node.js</Tab>
+        <Tab>Python</Tab>
+    </Tab.List>
+    <Tab.Panels>
+        <Tab.Panel>
+            <LocalEvalDistributedEnvNodeContent />
+        </Tab.Panel>
+        <Tab.Panel>
+            <LocalEvalDistributedEnvPythonContent />
+        </Tab.Panel>
+    </Tab.Panels>
+</Tab.Group>
+
+<LocalEvalDistributedEnvCommonPatterns />

…/docs/feature-flags/local-evaluation.mdx …feature-flags/local-evaluation/index.mdxcontents/docs/feature-flags/local-evaluation.mdx renamed to contents/docs/feature-flags/local-evaluation/index.mdx contents/docs/feature-flags/local-evaluation.mdx renamed to contents/docs/feature-flags/local-evaluation/index.mdx

@@ -10,7 +10,7 @@ availability:
 
 > **Note:** Local evaluation is only available in the [Node](/docs/libraries/node), [Ruby](/docs/libraries/ruby), [Go](/docs/libraries/go), [Python](/docs/libraries/python), [C#/.NET](/docs/libraries/dotnet), [PHP](/docs/libraries/php), and [Java](/docs/libraries/java) SDKs.
 
-> **Note:** Do not use local evaluation in edge/lambda environments and stateless PHP applications, as per-request initialization causes performance issues and unnecessarily inflated costs. Use regular flag evaluation instead.
+> **Note:** In edge/lambda environments and stateless PHP applications, local evaluation with the default in-memory cache causes performance issues and inflated costs due to per-request initialization. For these environments, use an [external cache provider](/docs/feature-flags/local-evaluation/distributed-environments) to share flag definitions across requests, or use regular flag evaluation instead.
 
 Evaluating feature flags requires making a request to PostHog for each flag. However, you can improve performance by evaluating flags locally. Instead of making a request for each flag, PostHog will periodically request and store feature flag definitions locally, enabling you to evaluate flags without making additional requests.
 
@@ -20,7 +20,7 @@ There are 3 steps to enable local evaluation:
 
 ## Step 1: Find your feature flags secure API key
 
-import ObtainFeatureFlagsSecureAPIKey from "../integrate/_snippets/obtain-flags-secure-key.mdx"
+import ObtainFeatureFlagsSecureAPIKey from "../../integrate/_snippets/obtain-flags-secure-key.mdx"
 
 <ObtainFeatureFlagsSecureAPIKey />
 
@@ -30,21 +30,21 @@ When you initialize PostHog with your feature flags secure API key, PostHog will
 
 By default, PostHog fetches these definitions every 30 seconds (or 5 minutes in the Go SDK). However, you can change this frequency by specifying a different value in the polling interval argument.
 
-> **Note:** For billing purposes, we count the request to fetch the feature flag definitions as being equivalent to `10 flags` requests. 
-> 
-> This is because one of these requests can compute feature flags for hundreds or thousands of users. It ensures local evaluation is priced fairly while remaining the most cost-effective option (by far!). 
+> **Note:** For billing purposes, we count the request to fetch the feature flag definitions as being equivalent to `10 flags` requests.
+>
+> This is because one of these requests can compute feature flags for hundreds or thousands of users. It ensures local evaluation is priced fairly while remaining the most cost-effective option (by far!).
 
-import ConfigureFlagsSecureKey from "../integrate/_snippets/configure-flags-secure-key.mdx"
+import ConfigureFlagsSecureKey from "../../integrate/_snippets/configure-flags-secure-key.mdx"
 
 <ConfigureFlagsSecureKey />
 
 ## Step 3: Evaluate your feature flag
 
 To evaluate the feature flag, call any of the flag related methods, like `getFeatureFlag` or `getAllFlags`, as you normally would. The only difference is that you must provide any `person properties`, `groups` or `group properties` used to evaluate the [release conditions](/docs/feature-flags/creating-feature-flags#release-conditions) of the flag.
 
-Then, by default, PostHog attempts to evaluate the flag locally using definitions it loads on initialization and at the `poll interval`. If this fails, PostHog then makes a server request to fetch the flag value. 
+Then, by default, PostHog attempts to evaluate the flag locally using definitions it loads on initialization and at the `poll interval`. If this fails, PostHog then makes a server request to fetch the flag value.
 
-You can disable this behavior by setting `onlyEvaluateLocally` to `true`. In this case, PostHog will **only** attempt to evaluate the flag locally, and return `undefined` / `None` / `nil` if it was unable to. 
+You can disable this behavior by setting `onlyEvaluateLocally` to `true`. In this case, PostHog will **only** attempt to evaluate the flag locally, and return `undefined` / `None` / `nil` if it was unable to.
 
 <MultiLanguage>
 
@@ -67,7 +67,7 @@ await client.getFeatureFlag(
             },
             'another_group_type': {
                 'group_property_name': 'another value'
-            } 
+            }
         },
         onlyEvaluateLocally: false, // Optional. Defaults to false. Set to true if you don't want PostHog to make a server request if it can't evaluate locally
     }
@@ -92,7 +92,7 @@ posthog.get_feature_flag(
         }
         'another_group_type': {
             'group_property_name': 'another value'
-        } 
+        }
     },
     only_evaluate_locally: False # Optional. Defaults to False. Set to True if you don't want PostHog to make a server request if it can't evaluate locally
 )
@@ -151,7 +151,7 @@ PostHog::getFeatureFlag(
     ], // groups
     ['property_name' => 'value'], // person properties
     [
-        'your_group_type' => ['group_property_name' => 'value'], 
+        'your_group_type' => ['group_property_name' => 'value'],
         'another_group_type' => ['group_property_name' => 'another value']
     ], // group properties
     false, // only_evaluate_locally, Optional. Defaults to false. Set to true if you don't want PostHog to make a server request if it can't evaluate locally

contents/docs/libraries/node/index.mdx

@@ -247,9 +247,9 @@ await client.reloadFeatureFlags()
 // Do something with feature flags here
 ```
 
-#### External caching
+#### Distributed environments
 
-In multi-worker or edge environments, you can implement custom caching for flag definitions using Redis, Cloudflare KV, or other storage backends. This enables sharing definitions across workers and coordinating fetches. See the [external caching guide](/tutorials/node-external-cache) for details.
+In multi-worker or edge environments, you can implement custom caching for flag definitions using Redis, Cloudflare KV, or other storage backends. This enables sharing definitions across workers and coordinating fetches. See our guide for [local evaluation in distributed environments](/docs/feature-flags/local-evaluation/distributed-environments?tab=Node.js) for details.
 
 ## Experiments (A/B tests)
 

contents/docs/libraries/python/index.mdx

@@ -131,6 +131,10 @@ import LocalEvaluationIntro from "../../feature-flags/snippets/local-evaluation-
 
 For details on how to implement local evaluation, see our [local evaluation guide](/docs/feature-flags/local-evaluation).
 
+#### Distributed environments
+
+In multi-worker or edge environments, you can implement custom caching for flag definitions using Redis, Cloudflare KV, or other storage backends. This enables sharing definitions across workers and coordinating fetches. See our guide for [local evaluation in distributed environments](/docs/feature-flags/local-evaluation/distributed-environments?tab=Python) for details.
+
 ## Experiments (A/B tests)
 
 Since [experiments](/docs/experiments/manual) use feature flags, the code for running an experiment is very similar to the feature flags code: