• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""


The Relay Proxy

Read time: 5 minutes
Last edited: Oct 20, 2021


This topic explains what the Relay Proxy is and how to use it.

The Relay Proxy is a small Go application that connects to the LaunchDarkly streaming API and proxies that connection to clients within an organization's network.

The Relay Proxy lets multiple servers connect to a local stream instead of making a large number of outbound connections to LaunchDarkly's streaming service (stream.launchdarkly.com). You can configure the Relay Proxy to carry multiple environment streams from multiple projects.

The Relay Proxy is an open-source project supported by LaunchDarkly. The full source is in a GitHub repository. There's also a Docker image on Docker Hub.

Should I use the Relay Proxy?

We recommend using the Relay Proxy if you have certain specific configuration requirements, which are explained below. If you don't meet those requirements, using the Relay Proxy is optional.

Some customers may find operating the Relay Proxy cost-prohibitive for their use case, especially customers on Pro or Starter plans.

Determining if your configuration is a good use case for the Relay Proxy

Adding the Relay Proxy to your LaunchDarkly configuration introduces architectural complexity that may not be necessary for smaller deployments.

The LaunchDarkly client-side and server-side SDKs you use also impacts whether you should use the Relay Proxy. The Relay Proxy provides performance and resilience improvements for all server-side SDKs and for SDKs configured to poll. To learn more, read Understanding the different types of SDKs.

The Relay Proxy works best with the default SDK configurations for all server-side SDKs and for the client-side JavaScript SDK. It does not scale well when it has to maintain streaming connections with a large number of client-side SDKs, including mobile SDKs. If you're utilizing LaunchDarkly's streaming architecture in a heavily-used client-side or mobile application, connecting directly to LaunchDarkly's main service may give you the best performance.

The Relay Proxy was developed to address specific scenarios, and it works best when you use it for those purposes.

Those scenarios are:

  • You use PHP: PHP's shared-nothing architecture prevents LaunchDarkly from re-using the streaming API connection across requests. You can use PHP without the Relay Proxy, but we strongly recommend using the Relay Proxy in daemon mode if you are using PHP in a high-throughput setting. This makes the Relay Proxy receive feature flag updates. To learn more, read Using the Relay Proxy in different modes.
  • You want to reduce outbound connections to LaunchDarkly: A large number of servers, such as thousands or tens of thousands, can present too many outbound persistent connections to LaunchDarkly's streaming API for a proxy or firewall to realistically handle. Use the Relay Proxy in proxy mode so your servers can connect directly to hosts in your own datacenter, instead of connecting directly to LaunchDarkly's streaming API. On an appropriately configured host, each Relay Proxy can handle tens of thousands of concurrent connections. This dramatically reduces the number of outbound connections to the LaunchDarkly streaming API.
  • You want to reduce redundant database traffic: If you use a persistent data store and you have a large number of servers connected to LaunchDarkly, each server attempts to update the data store when a flag update occurs. This behavior is safe, but inefficient. Deploy the Relay Proxy in daemon mode and set your LaunchDarkly SDKs to daemon mode. By doing this, you can delegate flag updates to a small number of Relay Proxy instances and reduce the number of redundant update calls to your data store. To learn more, read Persistent data stores.
  • You want to use Big Segments or sync segments from Amplitude with server-side SDKs: If you want to use Big Segments or sync segments from Amplitude with server-side SDKs, you must use the Relay Proxy. To learn more,read Big Segments and Syncing segments from Amplitude cohorts.

Understanding the cost of using the Relay Proxy

The Relay Proxy has certain features that are available to customers on an Enterprise plan, including automatic configuration and offline mode. Access to these features may make using the Relay Proxy more beneficial than it would be with only its out-of-the-box feature set. To learn more, read Relay Proxy Enterprise.

In general, customers on Enterprise plans may be more tolerant of the infrastructural costs associated with using the Relay Proxy's Enterprise features than customers with more limited budgets. If you're on LaunchDarkly's Starter or Pro plan, you can use the Relay Proxy but the operating costs associated with onboarding it may be prohibitive. To learn more, read Best practices for using the Relay Proxy.

Best practices for using the Relay Proxy

This section includes some guidelines for positioning and using the Relay Proxy successfully. These guidelines are not exhaustive or required. The most effective practices for your organization may be different based on your configuration and deployment requirements.

To learn more about performance expectations once the Relay Proxy is running, read Monitoring the Relay Proxy.

Scaling guidelines

If you want to size or scale your Relay Proxy, the most important thing to consider is the amount of dedicated network bandwidth available to it. The Relay Proxy is not CPU or memory intensive, so these are unlikely to be performance bottlenecks. However, the Relay Proxy does require a significant amount of network bandwidth, because it makes many small requests, very frequently.

We have tested and developed the Relay Proxy to work with an AWS m4.xlarge instance, but you can use the Relay Proxy with any technical equivalent. The m4.xlarge instances we test against have 4 vCPUs and 16GiB of memory, but that is not a hard requirement. In fact, the Relay Proxy may use significantly less memory and CPU than the m4.xlarge instance offers. More importantly, the m4.xlarge instance has sufficient networking performance that the Relay Proxy should perform well.

To learn more about instance sizing, read Amazon's documentation on EC2 instance types.

The Relay Proxy works best with LaunchDarkly's server-side SDKs and with SDKs configured for polling. It does not handle streaming connections from client-side SDKs efficiently. When you use LaunchDarkly's streaming architecture in a heavily-used client-side or mobile application, be sure to monitor and scale the Relay Proxy accordingly.

To learn more, read Monitoring the Relay Proxy.

Architectural guidelines

If you choose to use the Relay Proxy, position it effectively within your network architecture. Your application must be able to access the Relay Proxy for it to work, and that architecture varies based on the type of app you have.

For example, do not put the Relay Proxy inside a firewall if you intend to connect it to any client-side apps.

If you have deployed your application to multiple regions, consider running one or more Relay Proxy instances in each of those regions in close proximity to your application. This limits latency between your application and the Relay Proxy.

If you have security requirements, such as enforcing the use of a particular authentication scheme, place the Relay Proxy behind a general purpose proxy so traffic from LaunchDarkly SDKs flows through the general purpose proxy before it reaches the Relay Proxy. The Relay Proxy does not replicate the functionality of a general purpose proxy. Do not use it as a replacement for a general purpose proxy.

Caching guidelines

We do not recommend relying solely on the Relay Proxy's in-memory caching in a production environment. Instead, we recommend that you cache flag data in a persistent feature store.

To learn more, read Persistent data stores and Persistent storage.

Whether or not you utilize a persistent feature store impacts how the Relay Proxy handles inbound feature flag requests on initialization, before it establishes a connection to LaunchDarkly.

If you use a persistent feature store, Relay Proxy uses previously known-good values as stored in the persistent feature store. Without a persistent feature store, however, Relay Proxy doesn't know anything about any feature flags yet. SDKs use default flag values until the Relay Proxy establishes a connection to LaunchDarkly.