Streaming mode replaces Edge’s default polling loop with a persistent connection to upstream Unleash. Feature changes are pushed to Edge as they happen, reducing replication lag from the polling interval to near real time.
This page covers how to enable streaming, monitor the health of streaming Edge instances, and troubleshoot common issues. For the streaming configuration option, see the configuration reference.
The requirements depend on how you host Edge and Unleash.
Start Edge with streaming enabled using either the CLI flag or the environment variable.
A healthy start keeps the process running. If Edge exits immediately after starting, check the logs for startup validation errors such as an invalid token, missing license entitlement, or an upstream Unleash instance that does not support streaming. See Troubleshooting to resolve startup errors.
Once Edge is running, you can verify that flag changes propagate correctly by connecting an SDK and observing flag evaluation, or by calling the client features endpoint directly:
Make a controlled change in Unleash, such as toggling a flag or updating a strategy, then confirm the response reflects the change.
In streaming mode, Edge also enables SDK-to-Edge streaming, which is in beta. This is not available in all SDKs and is not yet recommended for production environments.
Once Edge is started with streaming enabled, it stays in streaming mode as long as the process is running. There is no automatic fallback to polling.
If the upstream connection drops, errors out, or becomes idle, Edge reconnects and resumes from the last event ID it received. While the connection is recovering, Edge keeps serving its last known state to connected SDKs. Temporary network interruptions are expected in distributed systems and normally recover without operator action.
Startup validation catches configuration issues such as missing license entitlement, invalid tokens, unsupported upstream versions, and unsupported token combinations. After a successful start, most operational checks focus on confirming that instances converge on the same revision after Unleash changes.
The following sections cover operational recommendations for self-hosted Edge deployments running in streaming mode.
Tracking the revision each instance has applied is the standard way to confirm your fleet is in sync. Every active instance serving the same environment and project scope should converge on the same revision after Unleash changes.
Revision values only advance when there are changes to the upstream feature configuration. A stable revision is expected when no feature flags, strategies, segments, or related configuration have changed.
You can inspect this in two ways.
In the Unleash Admin UI, go to Admin settings > Enterprise Edge.
The page lists each registered Edge instance, the tokens it serves, and the revision ID each token has observed. Use this view to answer questions like:
If one instance reports an older revision than the rest of the fleet for the same token scope after a feature configuration change, that instance may still be reconnecting or catching up.
For more details, see Enterprise Edge observability.
As part of your standard observability setup, you can configure an alert for when instances in your fleet report different revisions for the same token scope.
Short-lived revision differences are expected while changes propagate through a distributed system. They are usually only worth investigating when they persist beyond the normal propagation window, for example 5 to 15 minutes.
All Edge instances serving the same environment and project scope should eventually converge on the same revision, so the alert compares instances that share the same environment and projects labels. Consecutive upstream changes can extend the time where instances briefly report different revisions, because each new change gives the fleet another revision to apply.
Example alert expression:
Recommended settings:
environment and projects labels in the notificationThe following covers the cases that usually need operator attention when running Edge self-hosted with streaming enabled.
Edge validates its streaming configuration during startup. If the process exits immediately, the most useful source of information is the startup log entry that explains which validation failed.
Check:
Edge streaming is designed to reconnect and rehydrate automatically, and brief transient states normally settle without intervention.
If behavior does not match your expectations after a controlled feature configuration change, compare the affected instances in the Enterprise Edge UI or with delta_revision_id. Confirm whether the instances serving the same environment and project scope converge on the same revision.
If the issue persists, collect the affected environment and project, the latest revision reported by each instance, the client request details, and relevant Edge logs. Restarting an affected node forces a fresh upstream connection, but it may first restore feature data from its configured backup storage. If the unexpected state is also present in that backup, restarting may not resolve it. If you need to restore polling while we investigate, disable streaming and contact our support team with the data you collected.