Intermediate
How to use server-side flag evaluation on PostHog
Quick Answer
Server-side flag evaluation in PostHog allows you to evaluate feature flags on your server without making API calls for each request. This involves installing a PostHog SDK, initializing it with your project API key, and using the evaluate flag methods to check feature flag states programmatically.
Prerequisites
- PostHog account with project access
- Server-side SDK installed (Python, Node.js, PHP, etc.)
- Basic understanding of feature flags
- API access token or personal API key
1
Install PostHog Server-Side SDK
Install the appropriate PostHog SDK for your server environment. For Python:
pip install posthog, for Node.js: npm install posthog-node, for PHP: composer require posthog/posthog-php. Choose the SDK that matches your backend technology stack.Tip
Always use the latest version of the SDK to ensure compatibility with the newest flag evaluation features.
2
Initialize PostHog Client
Set up your PostHog client with your project API key. In Python:
import posthog
posthog.api_key = 'your-project-api-key'
posthog.host = 'https://app.posthog.com'const PostHog = require('posthog-node')
const client = new PostHog('your-project-api-key')Tip
Store your API key securely as an environment variable rather than hardcoding it in your source code.
3
Enable Local Evaluation
Configure your PostHog client to enable local flag evaluation by setting
personal_api_key parameter. This allows the SDK to fetch flag definitions and evaluate them locally: posthog.personal_api_key = 'your-personal-api-key'
posthog.poll_interval = 30 # secondsTip
Set an appropriate poll interval to balance between fresh flag data and API rate limits.
4
Create Feature Flag in PostHog Dashboard
Navigate to Feature Flags in your PostHog dashboard. Click New Feature Flag, enter a flag key (e.g., 'new-checkout-flow'), set release conditions, and click Save. Ensure the flag is set to Active status for server-side evaluation.
5
Evaluate Feature Flag in Code
Use the
is_feature_enabled method to check if a feature flag is enabled for a specific user. Example: is_enabled = posthog.is_feature_enabled(
'new-checkout-flow',
'user-123',
person_properties={'email': 'user@example.com'}
)Tip
Always provide user identification and relevant properties to ensure accurate flag evaluation based on your targeting rules.
6
Handle Flag Variants
For multivariate flags, use
get_feature_flag to retrieve the specific variant value: variant = posthog.get_feature_flag(
'checkout-button-color',
'user-123',
person_properties={'plan': 'premium'}
)
if variant == 'red':
# Show red buttonTip
Always include a fallback value in case flag evaluation fails or returns None.
7
Implement Error Handling
Wrap flag evaluation in try-catch blocks to handle network issues or SDK errors gracefully:
try:
is_enabled = posthog.is_feature_enabled('feature-key', user_id)
except Exception as e:
# Log error and use default behavior
is_enabled = FalseTip
Never let feature flag evaluation failures break your application's core functionality.
8
Monitor Flag Performance
Check the Feature Flags section in PostHog to monitor evaluation metrics, user distribution, and flag performance. Use the Insights tab to analyze how flag changes affect user behavior and key metrics.
Tip
Set up alerts for significant changes in flag evaluation patterns to catch potential issues early.
Troubleshooting
Feature flag always returns false or None
Verify your personal API key is correct and has proper permissions. Check that the flag is Active in the PostHog dashboard and that your user meets the targeting conditions.
SDK throws authentication errors
Ensure both
api_key (project key) and personal_api_key are set correctly. Verify the keys haven't expired and have appropriate permissions in Project Settings → API Keys.Flag evaluation is slow or timing out
Reduce the
poll_interval setting and check your network connectivity to PostHog servers. Consider implementing caching mechanisms and ensure you're not making excessive API calls.Flag changes not reflecting immediately
Local evaluation caches flag definitions based on your
poll_interval setting. Wait for the next poll cycle or restart your application. For immediate updates, consider using posthog.reload_feature_flags() method.Ready to get started with PostHog?
Put this tutorial into practice. Visit PostHog and follow the steps above.
Visit PostHog →