Finagle features that cannot be turned on/off on a per client/server basis are usually controlled via global command line flags. This document lists such flags along with their default values.

Finagle’s global flags could be either passed as Java application flags (when run within Twitter Server) or as JVM properties.

-com.twitter.finagle.foo=bar  // Java application argument
-Dcom.twitter.finagle.foo=bar // JVM arg/property


com.twitter.finagle.client.useNackAdmissionFilter bool
A global on/off switch for client-side nack admission control (default: true, which opts clients into using nack admission control). This controller is designed to allow backends to recover when they overloaded. See com.twitter.finagle.filter.NackAdmissionFilter for more details. This value can also be set on per-client with $Client.configured(NackAdmissionFilter.Param).
com.twitter.finagle.loadbalancer.defaultBalancer choice|heap|aperture|random_aperture
The default load balancer used in clients (default: choice). random_aperture should only be used in situations where subsetting is a firm requirement. An example of that is in a testing situation where p2c behavior isn’t acceptable. In other cases aperture will select between random aperture and deterministic aperture when appropriate.
com.twitter.finagle.loadbalancer.perHostStats bool
Enable/disable per-host granularity for stats (default: false). When enabled,the configured stats receiver will be used, or the loaded stats receiver if none given.
com.twitter.finagle.socks.socksProxyHost string
When non empty, enables SOCKS proxy on each Finagle client (default: empty string).
com.twitter.finagle.socks.socksProxyPort int
A port number for a SOCKS proxy (default: 0).
com.twitter.finagle.socks.socksUsername string
A username for a SOCKS proxy (default: empty string).
com.twitter.finagle.socks.socksPassword string
A cleartext password for a SOCKS proxy (default: empty string).
com.twitter.finagle.tracing.enabled bool
When false, disables any tracing for this process (default: true). Note: it’s never recommended to disable tracing in production applications.
com.twitter.finagle.tracing.traceId128Bit bool
When true, new root spans will have 128-bit trace IDs (default: false, 64-bit IDs).
com.twitter.finagle.util.defaultTimerProbeSlowTasks bool
Enable reporting of slow timer tasks executing in the default timer (default: false).
com.twitter.finagle.util.defaultTimerSlowTaskMaxRuntime duration
Maximum runtime allowed for tasks before they are reported (default: 2.seconds).
com.twitter.finagle.util.defaultTimerSlowTaskLogMinInterval duration
Minimum interval between recording stack traces for slow tasks (default: 20.seconds).
com.twitter.finagle.offload.numWorkers int
Experimental flag. Enables the offload filter using a thread pool with the specified number of threads. When this flag is greater than zero, the execution of application code happens in an isolated pool and the netty threads are used only to handle the network channels. This behavior changes the assumptions regarding the scheduling of tasks in finagle applications. Traditionally, the recommendation is to execute CPU-intensive tasks using a FuturePool but, when this flag is enabled, CPU-intensive tasks don’t require a FuturePool. Important: Blocking tasks should still use a FuturePool. It’s important to review the allocation of thread pools when this flag is enabled otherwise the application might create too many threads, which leads to more GC pressure and increases the risk of CPU throttling.

Netty 4

com.twitter.finagle.netty4.numWorkers int
The number of Netty 4 worker threads in the shared even pool (default: CPUs * 2)
com.twitter.finagle.netty4.trackReferenceLeaks bool
Enable reference leak tracking in Netty 4 and export a counter at finagle/netty4/reference_leaks (default: false).
com.twitter.finagle.netty4.timerTicksPerWheel int
Netty 4 timer ticks per wheel (default: 512).
com.twitter.finagle.netty4.timerTickDuration duration
Netty 4 timer tick duration (default: 10.milliseconds).
com.twitter.finagle.netty4.useNativeEpoll bool
When available, use Linux’s native epoll transport directly instead of bouncing through JDK (default: true).
com.twitter.finagle.netty4.http.revalidateInboundHeaders bool
Validate headers when converting from Netty to Finagle. (default: false).


com.twitter.finagle.stats.statsFilter string
Comma-separated list of regexes that indicate which metrics to filter out (default: empty string).
com.twitter.finagle.stats.statsFilterFile list of files
Comma-separated list of files of newline-separated regexes that indicate which metrics to filter out (default: empty list).
com.twitter.finagle.stats.useCounterDeltas bool
When true, export deltas for counters instead of absolute values (default: false).
com.twitter.finagle.stats.debugLoggedStatNames list of strings
Comma-separated stat names for logging observed values (default: empty list).
com.twitter.finagle.stats.scopeSeparator string
Override the default scope separator (default: /).
com.twitter.finagle.stats.format commonsmetrics|commonsstats|ostrich
Format style for stat names (default: commonmetrics).
com.twitter.finagle.stats.includeEmptyHistograms bool
Include full histogram details when there are no data points (default: false).
com.twitter.finagle.stats.verbose string
Comma-separated list of *-wildcard expressions to allowlist debug metrics that are not exported by default (default: undefined). A tunable, com.twitter.finagle.stats.verbose has a higher priority if defined.


com.twitter.finagle.http.serverErrorsAsFailures bool
Treat responses with status codes in the 500s as failures (default: true).