Skip to content

Java provider



Configuration and Usage

The flagd provider can operate in two modes: RPC (evaluation takes place in flagd, via gRPC calls) or in-process (evaluation takes place in-process, with the provider getting a ruleset from a compliant sync-source).

Remote resolver (RPC)

This is the default mode of operation of the provider. In this mode, FlagdProvider communicates with flagd via the gRPC protocol. Flag evaluations take place remotely at the connected flagd instance.

Instantiate a new FlagdProvider instance and configure the OpenFeature SDK to use it:

// Create a flagd instance with default options
FlagdProvider flagd = new FlagdProvider();
// Set flagd as the OpenFeature Provider

In-process resolver

This mode performs flag evaluations locally (in-process). Flag configurations for evaluation are obtained via gRPC protocol using sync protobuf schema service definition.

Consider the following example to create a FlagdProvider with in-process evaluations,

FlagdProvider flagdProvider = new FlagdProvider(

In the above example, in-process handlers attempt to connect to a sync service on address localhost:8013 to obtain flag definitions.

Offline mode

In-process resolvers can also work in an offline mode. To enable this mode, you should provide a valid flag configuration file with the option offlineFlagSourcePath.

FlagdProvider flagdProvider = new FlagdProvider(

Provider will attempt to detect file changes using polling. Polling happens at 5 second intervals and this is currently unconfigurable. This mode is useful for local development, tests and offline applications.

[!IMPORTANT] Note that you can only use a single flag source (either gRPC or offline file) for the in-process resolver. If both sources are configured, offline mode will be selected.

Configuration options

Options can be defined in the constructor or as environment variables, with constructor options having the highest precedence. Default options can be overridden through a FlagdOptions based constructor or set to be picked up from the environment variables.

Given below are the supported configurations:

Option name Environment variable name Type & Values Default Compatible resolver
resolver FLAGD_RESOLVER String - rpc, in-process rpc
host FLAGD_HOST String localhost rpc & in-process
port FLAGD_PORT int 8013 rpc & in-process
tls FLAGD_TLS boolean false rpc & in-process
socketPath FLAGD_SOCKET_PATH String null rpc & in-process
certPath FLAGD_SERVER_CERT_PATH String null rpc & in-process
deadline FLAGD_DEADLINE_MS int 500 rpc & in-process
selector FLAGD_SOURCE_SELECTOR String null in-process
cache FLAGD_CACHE String - lru, disabled lru rpc
maxCacheSize FLAGD_MAX_CACHE_SIZE int 1000 rpc
maxEventStreamRetries FLAGD_MAX_EVENT_STREAM_RETRIES int 5 rpc
retryBackoffMs FLAGD_RETRY_BACKOFF_MS int 1000 rpc
offlineFlagSourcePath FLAGD_OFFLINE_FLAG_SOURCE_PATH String null in-process

Some configurations are only applicable for RPC resolver.

Unix socket support

Unix socket communication with flagd is facilitated by usaging of the linux-native epoll library on linux-x86_64 only (ARM support is pending the release of netty-transport-native-epoll v5). Unix sockets are not supported on other platforms or architectures.


Reconnection is supported by the underlying GRPCBlockingStub. If the connection to flagd is lost, it will reconnect automatically.

Deadline (gRPC call timeout)

The deadline for an individual flag evaluation can be configured by calling setDeadline(myDeadlineMillis). If the gRPC call is not completed within this deadline, the gRPC call is terminated with the error DEADLINE_EXCEEDED and the evaluation will default. The default deadline is 500ms, though evaluations typically take on the order of 10ms. For the in-process provider, the deadline is used when establishing the initial streaming connection. A failure to connect within this timeout will result in an error event from the provider, though it will attempt to reconnect indefinitely.


TLS is available in situations where flagd is running on another host. You may optionally supply an X.509 certificate in PEM format. Otherwise, the default certificate store will be used.

FlagdProvider flagdProvider = new FlagdProvider(
                .tls(true)                      // use TLS
                .certPath("etc/cert/ca.crt")    // PEM cert

There's a vulnerability in netty, a transitive dependency of the underlying gRPC libraries used in the flagd-provider that fails to correctly validate certificates. This will be addressed in netty v5.

Caching (RPC only)

The in-process resolver does not benefit from caching since all evaluations are done locally and do not involve I/O.

The provider attempts to establish a connection to flagd's event stream (up to 5 times by default). If the connection is successful and caching is enabled, each flag returned with the reason STATIC is cached until an event is received concerning the cached flag (at which point it is removed from the cache).

On invocation of a flag evaluation (if caching is available), an attempt is made to retrieve the entry from the cache, if found the flag is returned with the reason CACHED.

By default, the provider is configured to use least recently used (lru) caching with up to 1000 entries.

OpenTelemetry tracing (RPC only)

flagd provider support OpenTelemetry traces for gRPC-backed remote evaluations.

There are two ways you can configure OpenTelemetry for the provider,

When using automatic instrumentation, traces for gRPC will be automatically added by the OpenTelemetry Java library. These traces, however will not include extra attributes added when using manual instrumentation.

When using manual instrumentation, you have two options to construct flagd provider to enable traces.

The first(preferred) option is to construct the provider with an OpenTelemetry instance,

FlagdOptions options = 

FlagdProvider flagdProvider = new FlagdProvider(options);

The second option is useful if you have set up a GlobalOpenTelemetry in your runtime. You can allow flagd to derive the OpenTelemetry instance by enabling withGlobalTelemetry option.

FlagdOptions options =

FlagdProvider flagdProvider = new FlagdProvider(options);

Please refer OpenTelemetry example for best practice guidelines.

Provider telemetry combined with flagd OpenTelemetry allows you to have distributed traces.