Evaluation tags (user-specified flag evaluation environment constraints)

Evaluation tags provide fine-grained control over where and when your feature flags evaluate. By constraining flag evaluation to specific environments or contexts, you can reduce unnecessary evaluations, optimize costs, and better organize your feature management strategy.

What are evaluation tags?

Evaluation tags are environment constraints that determine when a feature flag should be evaluated. Unlike standard tags (which are purely organizational), evaluation tags actively filter which flags are returned during evaluation requests.

When you configure evaluation tags on a feature flag:

• The flag will only evaluate when the SDK provides matching environment tags
• Flags without evaluation tags continue to work as before (evaluating for all requests)
• At least one evaluation tag must match for the flag to be included

Why use evaluation tags?

1. Environment isolation

Prevent feature flags from accidentally affecting the wrong environment. For example:

• Marketing site flags won't affect your main application
• Documentation site flags won't impact your mobile apps
• Staging flags won't evaluate in production

2. Cost optimization

Reduce unnecessary flag evaluations and associated costs by:

• Only evaluating relevant flags per environment
• Reducing network payload sizes
• Minimizing server-side processing

3. Better organization

Group and filter flags by their intended context in the feature flags UI, for example:

• Product area (e.g., "checkout", "onboarding", "admin")
• Platform (e.g., "web", "mobile", "api")
• Team ownership (e.g., "growth", "platform", "security")

4. Improved performance

Smaller, more focused flag sets mean:

• Faster evaluation times
• Reduced memory usage in SDKs

Setting up evaluation tags

Step 1: Apply evaluation tags to flags

When creating or editing a feature flag:

1. Navigate to the tags section
2. Click the bolt icon
   to configure evaluation constraints
3. Select which tags should act as evaluation constraints
4. Selected evaluation tags will display with a green background and bolt icon

Remember: Setting tags in the PostHog app is only half the setup. Your application needs to know which environment it's in, which requires updating your SDK configuration (Step 2).

Step 2: Configure your SDKs

This step is essential - After setting evaluation tags in the PostHog app, you must update your SDK configuration to tell your application which environment it's running in. Without this, your application won't know its deployment context and evaluation tags won't work.

Update your SDK initialization to include evaluation environments:

posthog.init('YOUR_API_KEY', {
    api_host: 'https://app.posthog.com',
    evaluation_environments: ['production', 'web', 'checkout']
})

How evaluation works

When a flag evaluation request is made:

1. SDK sends environment tags: The SDK includes its configured evaluation_environments in the request
2. PostHog filters flags: Only flags matching these criteria are evaluated:
   • Flags with no evaluation tags (backward compatibility)
   • Flags with empty evaluation tags
   • Flags where at least one evaluation tag matches the provided environments
3. Results returned: Only the filtered flags are returned to the SDK

Example scenario

Consider these feature flags:

• Flag A: No evaluation tags → Evaluates for all requests
• Flag B: Evaluation tags ["production", "web"] → Only evaluates when SDK provides "production" OR "web"
• Flag C: Evaluation tags ["staging"] → Only evaluates when SDK provides "staging"

If an SDK is configured with evaluation_environments: ["production", "mobile"]:

• ✅ Flag A evaluates (no constraints)
• ✅ Flag B evaluates ("production" matches)
• ❌ Flag C does NOT evaluate (no matching tags)

Best practices

Start simple

Begin with high-level environment distinctions:

• production vs. staging vs. development
• web vs. mobile vs. api

Use consistent naming

Establish a naming convention for your organization:

• Environment: prod, staging, dev
• Platform: web, ios, android, api
• Product area: checkout, onboarding, admin

Document your tags

Maintain a list of standard evaluation tags and their purposes to ensure consistent usage across teams.

Gradual adoption

You don't need to add evaluation tags to all flags at once. Start with new flags or high-traffic flags where the benefits are most significant.

Monitor impact

Track the reduction in flag evaluations and associated cost savings after implementing evaluation tags.

Differences from evaluation runtime

While both features control where flags evaluate, they serve different purposes:

Common use cases

Multi-product organizations

If you have multiple products sharing a PostHog instance:

// Marketing site
posthog.init('KEY', { evaluation_environments: ['production', 'marketing-site'] })

// Main app
posthog.init('KEY', { evaluation_environments: ['production', 'app'] })

// Documentation
posthog.init('KEY', { evaluation_environments: ['production', 'docs'] })

Platform-specific features

Separate features by platform while maintaining a single flag source:

// iOS app
posthog.init('KEY', { evaluation_environments: ['production', 'ios'] })

// Android app
posthog.init('KEY', { evaluation_environments: ['production', 'android'] })

// Web app
posthog.init('KEY', { evaluation_environments: ['production', 'web'] })

Team-based development

Allow teams to work independently without flag conflicts:

// Growth team features
posthog.init('KEY', { evaluation_environments: ['staging', 'growth-team'] })

// Platform team features
posthog.init('KEY', { evaluation_environments: ['staging', 'platform-team'] })

Troubleshooting

Flags not evaluating

If a flag with evaluation tags isn't evaluating:

1. Check that your SDK is configured with evaluation_environments - This is the most common issue. Your application must explicitly declare its environment.
2. Verify at least one evaluation tag matches your SDK's environments
3. Ensure the evaluation tags are properly configured in PostHog
4. Confirm you've deployed the SDK configuration changes to your application

All flags evaluating

If you're still seeing all flags despite using evaluation tags:

1. Confirm your SDK version supports evaluation environments
2. Check that flags have evaluation tags configured (not just regular tags)
3. Verify your SDK is sending the evaluation_environments parameter

Performance not improved

If you don't see performance improvements:

1. Ensure you've added evaluation tags to high-traffic flags
2. Check that your environments are specific enough to filter effectively
3. Monitor the reduction in evaluated flags using PostHog analytics

Migration guide

To adopt evaluation tags in an existing PostHog setup:

1. Audit current flags: Identify which flags are used in which environments
2. Define tag taxonomy: Create a consistent naming scheme for your environments
3. Configure organization tags: Set up evaluation tags in organization settings
4. Update high-impact flags first: Start with flags that have the most evaluations
5. Update SDKs gradually: Roll out SDK changes with evaluation_environments per environment
6. Monitor and adjust: Track the impact and refine your tag strategy

SDK support

Evaluation tags are supported in the following SDKs:

• JavaScript Web (version 1.270.0+)

Note: Check your SDK documentation for the minimum version required and specific implementation details.