Should this code path be active for this request, tenant, user, environment, or integration right now?

- endpoint baru
- pricing rule baru
- catalog behavior baru
- integration route baru
- validation rule baru
- Kafka event publication baru
- downstream client baru
- tenant-specific enablement
- rollback behavior
- emergency disablement

Feature flags reduce release risk only when their lifecycle, defaults, ownership, and observability are disciplined.

Deployment = code exists in runtime.
Release    = behavior is enabled for users/tenants/traffic.

merge code
  -> deploy
  -> behavior immediately active

merge code
  -> deploy inactive or partially active
  -> enable gradually
  -> observe
  -> expand or disable

Risk can be exposed gradually.

if (flags.enabled("new-pricing")) {
    return newPricing.calculate(input);
}
return oldPricing.calculate(input);

- environment
- tenant
- market/region
- user role
- product type
- request type
- percentage rollout
- account/customer
- contract version
- API version
- operation type
- time window

What is the evaluation context?

public record FlagContext(
    String environment,
    String tenantId,
    String userId,
    String region,
    String operation,
    String apiVersion
) {}

release flag
  enables unfinished/new functionality safely

experiment flag
  compares behavior variants

ops flag
  controls runtime operational behavior

permission flag
  enables capability for customer/tenant/user

kill switch
  disables dangerous behavior quickly

migration flag
  switches between old/new implementation during migration

integration flag
  routes calls to new downstream/provider

schema/contract flag
  controls compatibility behavior during schema/API transition

Release flag should be removed after rollout.
Ops flag may be permanent.
Kill switch may be permanent but must be tested.
Migration flag should be temporary.
Permission flag may be productized.

- disable event publication
- disable expensive recalculation
- disable third-party integration
- disable non-critical validation
- disable async enrichment
- disable preview endpoint
- disable batch job
- disable optional notification

- fast to change
- safe by default
- observable
- documented
- tested
- owned
- scoped carefully

flag exists but nobody knows it
flag change needs full redeploy
flag disables too much
flag silently corrupts state
flag has never been tested

Disables non-critical external enrichment for tenant X while preserving core quote creation.

- calculate new pricing in shadow mode but return old result
- call new downstream but ignore response
- publish event to shadow topic
- validate new rule but do not reject request
- compute new catalog eligibility but do not expose it

- measure correctness
- measure performance
- compare old vs new result
- detect integration failure
- warm cache
- build confidence before release

- it still consumes resources
- it may mutate state accidentally
- it may call downstream with real side effects
- it may leak data
- it may generate confusing logs/events

Dark launch must be side-effect controlled.

QuotePrice oldPrice = oldPricing.calculate(request);

if (flags.enabled("pricing.shadow", context)) {
    QuotePrice newPrice = newPricing.calculate(request);
    comparisonRecorder.record(request.quoteId(), oldPrice, newPrice);
}

return oldPrice;

- new path must not mutate canonical state
- comparison result must be sampled or bounded
- failure in shadow path must not fail user path unless intended
- latency overhead must be measured
- sensitive data must be protected

New pricing writes final price while old pricing response is returned.

- JAX-RS resource method
- application service
- domain service
- repository/infrastructure adapter
- HTTP client wrapper
- Kafka publisher
- scheduler/job
- UI/client
- API gateway

Evaluate the flag at the layer that owns the behavioral decision.

Endpoint availability -> resource/API layer
Pricing algorithm -> application/domain service
Downstream provider switch -> integration adapter
Event publication -> event publisher boundary
Batch job enablement -> scheduler/job boundary

@POST
@Path("/quotes/preview")
public Response preview(QuotePreviewRequest request, @Context SecurityContext security) {
    FlagContext context = flagContextFactory.from(security);

    if (!flags.enabled("quote.preview.endpoint", context)) {
        return Response.status(404).build();
    }

    return Response.ok(service.preview(request)).build();
}

Return 404, 403, or 501?

404 hides endpoint existence.
403 says endpoint exists but not allowed.
501 says not implemented/supported.
409/422 may apply when business capability unavailable.

public QuoteResult createQuote(CreateQuoteCommand command) {
    FlagContext context = flagContextFactory.from(command);

    PricingResult price = flags.enabled("pricing.v2", context)
        ? pricingV2.calculate(command)
        : pricingV1.calculate(command);

    return quoteRepository.save(command, price);
}

- both paths must honor same invariant
- both paths must emit compatible response
- both paths must handle validation consistently
- both paths must be observable

public PricingResponse price(PricingRequest request) {
    FlagContext context = flagContextFactory.from(request);

    if (flags.enabled("pricing.provider.v2", context)) {
        return pricingProviderV2.price(request);
    }

    return pricingProviderV1.price(request);
}

- timeout parity
- retry policy parity
- error mapping parity
- response shape compatibility
- audit/log consistency
- idempotency behavior
- downstream side effects

environment
service name
service version
tenant ID
user ID
role/permission
region
market
operation
resource type
contract version
API version
request header
percentage bucket

tenant ID
user ID
customer ID
quote ID
order ID

Tenant A uses pricing v1.
Tenant B uses pricing v2.
Tenant C is in shadow mode.

- tenant behavior drift
- hard-to-reproduce bugs
- inconsistent support runbooks
- hidden compatibility matrix
- stale tenant exceptions
- cross-tenant leakage in flag context

Tenant-specific flag must have ownership, expiry, and observability.

boolean enabled = flagClient.getBoolean("new-order-flow", true);

For release flag: default disabled.
For kill switch: default may be safe-disabled or safe-enabled depending semantics.
For critical dependency disablement: default should preserve safest core behavior.

boolean enabled = flags.booleanFlag(
    "pricing.v2",
    context,
    Default.DISABLED_ON_ERROR
);

flag service unavailable
network timeout
stale cache
invalid flag payload
permission denied
SDK initialization failure
flag deleted unexpectedly
clock skew affects scheduled rule

- use cached value
- use default value
- fail startup
- fail request
- disable feature
- enable safety mode

flag failure -> old stable behavior

flag failure -> fail closed

- local static config
- in-memory cache
- streaming SDK update
- polling SDK update
- remote evaluation per request
- environment file/config map

Remote per request:
  + fresh
  - latency dependency
  - availability risk

Local cache:
  + fast
  + resilient
  - stale value risk

Streaming update:
  + near real-time
  - SDK/network complexity

How stale can a flag value safely be?

if (Math.random() < 0.1) enable();

same user/tenant may flip between paths per request
hard to debug
state becomes inconsistent

hash(tenantId + flagName) % 100 < rolloutPercentage

A quote/order process should not randomly switch behavior halfway through lifecycle.

flag enabled for some tenants
  -> response shape changes
  -> generated client breaks
  -> OpenAPI no longer describes behavior

- additive response fields only
- old fields remain valid
- versioned endpoint if contract changes
- explicit media type/version negotiation
- documentation of conditional behavior

1. expand schema backward-compatibly
2. deploy code that can read/write old and new if needed
3. enable flag for shadow/small scope
4. verify metrics and data correctness
5. increase rollout
6. migrate/backfill data
7. remove old code path
8. contract schema if safe

flag off but old code cannot run because schema was changed incompatibly

- publish new event
- publish old and new event
- publish to shadow topic
- change payload field population
- enable CDC/outbox publisher

- consumer does not expect new event
- event versioning unclear
- duplicate publication
- replay behavior differs by flag state
- flag value at replay time differs from original processing time

Event replay should not accidentally use today's flag state if it must reproduce historical behavior.

- flag snapshot
- event version
- processing mode
- saga state

- pricing algorithm selected
- catalog rule version selected
- discount eligibility rule selected
- tax calculation mode selected
- tenant-specific behavior selected

- flag name
- evaluated value
- rule/version
- tenant
- operation
- timestamp
- service version

- count by flag variant
- error rate by old/new path
- latency by old/new path
- fallback/default usage
- flag evaluation failure
- kill switch state change
- shadow mismatch count

flag_name
variant
environment
service

tenant_id
user_id
quote_id
order_id

old price vs new price
old validation result vs new validation result
old catalog eligibility vs new catalog eligibility
old downstream response category vs new downstream response category

- exact result when deterministic
- tolerance window for monetary calculation
- category/classification
- latency
- downstream error type
- data completeness

Use BigDecimal comparison with explicit scale/rounding policy.

- what does it disable?
- what remains functional?
- who can toggle it?
- how fast does it propagate?
- how do we verify it worked?
- what customer impact occurs?
- how do we re-enable safely?
- what metrics should be watched?

Kill switch: external-pricing-enrichment.enabled=false
Impact: quote can still be created using cached/default enrichment policy.
Risk: price enrichment may be less precise for affected tenants.
Verification: downstream call rate drops to zero, quote creation success recovers.

proposal
  -> implementation
  -> rollout
  -> full enablement
  -> stabilization
  -> cleanup
  -> deletion

- dead code remains
- tests multiply
- behavior matrix grows
- onboarding becomes harder
- production debugging becomes ambiguous

- owner
- purpose
- type
- default
- creation date
- expected removal date
- cleanup issue/link

newFlow
v2
enableThing
fastMode

quote.pricing.algorithm.v2.enabled
order.submission.async-validation.enabled
catalog.eligibility.shadow.enabled
integration.crm.v2.route.enabled
notification.email.kill-switch.disabled

- domain/component
- behavior
- variant/version
- enabled/disabled semantics

disableNewPricing=false

pricing.v2.enabled=true

pricing.external-enrichment.disabled=true

- flag enabled
- flag disabled
- flag service failure
- default behavior
- tenant-specific behavior
- rollout bucket stability
- kill switch behavior
- shadow mode failure isolation

pricing.v2 disabled -> old pricing called
pricing.v2 enabled  -> new pricing called
flag failure        -> old pricing called + metric emitted

- use fake flag provider
- make flag context explicit
- avoid tests depending on external flag service
- assert telemetry if critical

- local YAML/properties flag file
- fake flag service
- environment variable override
- dev UI
- test fixture flag provider

How do I enable pricing.v2 locally?
How do I simulate flag service down?
How do I test tenant-specific flag?
How do I inspect effective flag values safely?

local dev always enables everything

if feature flag enabled -> allow user action

if feature enabled for tenant
  and user authorized
  and operation allowed
  then proceed

If entitlement flag cannot be evaluated, do not grant capability by default.

- per-request remote calls
- cache hit rate
- SDK initialization
- lock contention
- context construction overhead
- JSON parsing per request
- high-cardinality telemetry

- cache locally
- precompute context
- avoid blocking remote call
- bound timeout tightly
- default safely on error

flag default unsafe
flag service unavailable
stale flag value
flag deleted while code still depends on it
wrong tenant context
wrong environment config
percentage rollout unstable
kill switch too slow
shadow path mutates state
flagged response breaks contract
flagged event breaks consumer
flag remains forever
flag value not observable

- no ownership
- no cleanup policy
- no evaluation context standard
- no observability
- no compatibility discipline
- no runbook
- no test matrix

1. Identify request/tenant/user/environment.
2. Identify relevant flag names.
3. Check evaluated flag value, not only configured value.
4. Check evaluation context.
5. Check flag default/fallback used or not.
6. Check flag service/cache health.
7. Check recent flag changes.
8. Check service version.
9. Check whether DB/event/API contract is compatible.
10. Check telemetry by old/new path.

configured flag value != evaluated flag value

[ ] Is the flag type clear: release, ops, kill switch, migration, permission, experiment?
[ ] Is default behavior safe?
[ ] Is failure behavior defined?
[ ] Is evaluation context explicit?
[ ] Is tenant targeting safe if used?
[ ] Is authorization still enforced separately?
[ ] Is contract compatibility preserved?
[ ] Is DB migration compatible with flag rollback?
[ ] Is event publication compatible?
[ ] Is telemetry added for old/new path?
[ ] Is kill switch runbook documented if applicable?
[ ] Are tests covering enabled/disabled/failure/default cases?
[ ] Is owner and cleanup date documented?
[ ] Is stale flag cleanup planned?

[ ] Apakah ada feature flag platform/library internal.
[ ] Apakah memakai LaunchDarkly, Unleash, ConfigCat, FF4J, Togglz, custom config, atau lainnya.
[ ] Apakah flag dievaluasi lokal, remote, polling, streaming, atau config file.
[ ] Apakah ada standard flag naming.
[ ] Apakah ada standard default-on-error.
[ ] Apakah ada kill switch untuk downstream integration kritikal.
[ ] Apakah ada runbook untuk kill switch.
[ ] Apakah tenant-specific flag didukung.
[ ] Apakah flag context memasukkan tenant/user/region/market.
[ ] Apakah flag decision muncul di logs/traces/metrics secara aman.
[ ] Apakah ada cleanup policy untuk temporary flags.
[ ] Apakah flag perubahan diaudit.
[ ] Apakah flag dapat diubah tanpa redeploy.
[ ] Apakah flag propagation delay diketahui.
[ ] Apakah flag service dependency punya timeout/cache.
[ ] Apakah feature flag digunakan untuk migration database/API/event.
[ ] Apakah rollback strategy bergantung pada flag.

What behavior does this change?
Who owns it?
What is the safe default?
What happens if flag evaluation fails?
Who/tenant/environment is affected?
Does it preserve API, DB, and event compatibility?
How do we observe old vs new behavior?
How do we disable it during incident?
When will we delete it?

Feature flags are powerful because they add runtime control.
They are dangerous because they add runtime ambiguity.