Package com.linecorp.armeria.common

Class Flags

java.lang.Object
com.linecorp.armeria.common.Flags
public final class Flags
extends Object
The system properties that affect Armeria's runtime behavior.

  • Method Details

    • verboseExceptionSampler

      public static Sampler<Class<? extends Throwable>> verboseExceptionSampler()
      Returns the Sampler that determines whether to retain the stack trace of the exceptions that are thrown frequently by Armeria.
      See Also:
      verboseExceptionSamplerSpec()

    • verboseExceptionSamplerSpec

      public static String verboseExceptionSamplerSpec()
      Returns the specification string of the Sampler that determines whether to retain the stack trace of the exceptions that are thrown frequently by Armeria. A sampled exception will have the stack trace while the others will have an empty stack trace to eliminate the cost of capturing the stack trace.

      The default value of this flag is "rate-limit=10", which retains the stack trace of the exceptions at the maximum rate of 10 exceptions/sec. Specify the -Dcom.linecorp.armeria.verboseExceptions=<specification> JVM option to override the default. See Sampler.of(String) for the specification string format.

    • verboseSocketExceptions

      public static boolean verboseSocketExceptions()
      Returns whether to log the socket exceptions which are mostly harmless. If enabled, the following exceptions will be logged:

      It is recommended to keep this flag disabled, because it increases the amount of log messages for the errors you usually do not have control over, e.g. unexpected socket disconnection due to network or remote peer issues.

      This flag is disabled by default. Specify the -Dcom.linecorp.armeria.verboseSocketExceptions=true JVM option to enable it.

      See Also:
      Exceptions.isExpected(Throwable)

    • verboseResponses

      public static boolean verboseResponses()
      Returns whether the verbose response mode is enabled. When enabled, the server responses will contain the exception type and its full stack trace, which may be useful for debugging while potentially insecure. When disabled, the server responses will not expose such server-side details to the client.

      This flag is disabled by default. Specify the -Dcom.linecorp.armeria.verboseResponses=true JVM option or use ServerBuilder.verboseResponses(boolean) to enable it.

    • requestContextStorageProvider

      @Nullable public static String requestContextStorageProvider()
      Returns the fully qualified class name of RequestContextStorageProvider that is used to choose when multiple RequestContextStorageProviders exist.

      The default value of this flag is null, which means only one RequestContextStorageProvider must be found via Java SPI. If there are more than one, you must specify the -Dcom.linecorp.armeria.requestContextStorageProvider=<FQCN> JVM option to choose the RequestContextStorageProvider.

    • useEpoll

      @Deprecated public static boolean useEpoll()
      Deprecated.
      Use transportType() and -Dcom.linecorp.armeria.transportType=epoll.
      Returns whether the JNI-based /dev/epoll socket I/O is enabled. When enabled on Linux, Armeria uses /dev/epoll directly for socket I/O. When disabled, java.nio socket API is used instead.

      This flag is enabled by default for supported platforms. Specify the -Dcom.linecorp.armeria.useEpoll=false JVM option to disable it.

    • transportType

      public static TransportType transportType()
      Returns the TransportType that will be used for socket I/O in Armeria.

      The default value of this flag is "epoll" in Linux and "nio" for other operations systems. Specify the -Dcom.linecorp.armeria.transportType=<nio|epoll|io_uring> JVM option to override the default.

    • useOpenSsl

      public static boolean useOpenSsl()
      Returns whether the JNI-based TLS support with OpenSSL is enabled. When enabled, Armeria uses OpenSSL for processing TLS connections. When disabled, the current JVM's default SSLEngine is used instead.

      This flag is enabled by default for supported platforms. Specify the -Dcom.linecorp.armeria.useOpenSsl=false JVM option to disable it.

    • dumpOpenSslInfo

      public static boolean dumpOpenSslInfo()
      Returns whether information about the OpenSSL environment should be dumped when first starting the application, including supported ciphers.

      This flag is disabled by default. Specify the -Dcom.linecorp.armeria.dumpOpenSslInfo=true JVM option to enable it.

      If useOpenSsl() returns false, this also returns false no matter you specified the JVM option.

    • maxNumConnections

      public static int maxNumConnections()
      Returns the default server-side maximum number of connections. Note that this flag has no effect if a user specified the value explicitly via ServerBuilder.maxNumConnections(int).

      The default value of this flag is 2147483647. Specify the -Dcom.linecorp.armeria.maxNumConnections=<integer> JVM option to override the default value.

    • numCommonWorkers

      public static int numCommonWorkers()
      Returns the default number of common worker group threads. Note that this flag has no effect if a user specified the worker group explicitly via ServerBuilder.workerGroup(EventLoopGroup, boolean) or ClientFactoryBuilder.workerGroup(EventLoopGroup, boolean).

      The default value of this flag is 2 * <numCpuCores>. Specify the -Dcom.linecorp.armeria.numCommonWorkers=<integer> JVM option to override the default value.

    • numCommonBlockingTaskThreads

      public static int numCommonBlockingTaskThreads()
      Returns the default number of blocking task executor threads. Note that this flag has no effect if a user specified the blocking task executor explicitly via ServerBuilder.blockingTaskExecutor(ScheduledExecutorService, boolean).

      The default value of this flag is 200. Specify the -Dcom.linecorp.armeria.numCommonBlockingTaskThreads=<integer> JVM option to override the default value.

    • defaultMaxRequestLength

      public static long defaultMaxRequestLength()
      Returns the default server-side maximum length of a request. Note that this flag has no effect if a user specified the value explicitly via ServerBuilder.maxRequestLength(long).

      The default value of this flag is 10485760L. Specify the -Dcom.linecorp.armeria.defaultMaxRequestLength=<long> to override the default value. 0 disables the length limit.

    • defaultMaxResponseLength

      public static long defaultMaxResponseLength()
      Returns the default client-side maximum length of a response. Note that this flag has no effect if a user specified the value explicitly via ClientBuilder.maxResponseLength(long).

      The default value of this flag is 10485760L. Specify the -Dcom.linecorp.armeria.defaultMaxResponseLength=<long> to override the default value. 0 disables the length limit.

    • defaultRequestTimeoutMillis

      public static long defaultRequestTimeoutMillis()
      Returns the default server-side timeout of a request in milliseconds. Note that this flag has no effect if a user specified the value explicitly via ServerBuilder.requestTimeout(Duration).

      The default value of this flag is 10000L. Specify the -Dcom.linecorp.armeria.defaultRequestTimeoutMillis=<long> to override the default value. 0 disables the timeout.

    • defaultResponseTimeoutMillis

      public static long defaultResponseTimeoutMillis()
      Returns the default client-side timeout of a response in milliseconds. Note that this flag has no effect if a user specified the value explicitly via ClientBuilder.responseTimeout(Duration).

      The default value of this flag is 15000L. Specify the -Dcom.linecorp.armeria.defaultResponseTimeoutMillis=<long> to override the default value. 0 disables the timeout.

    • defaultConnectTimeoutMillis

      public static long defaultConnectTimeoutMillis()
      Returns the default client-side timeout of a socket connection attempt in milliseconds. Note that this flag has no effect if a user specified the value explicitly via ClientFactoryBuilder.channelOption(ChannelOption, Object).

      The default value of this flag is 3200L. Specify the -Dcom.linecorp.armeria.defaultConnectTimeoutMillis=<integer> JVM option to override the default value.

    • defaultWriteTimeoutMillis

      public static long defaultWriteTimeoutMillis()
      Returns the default client-side timeout of a socket write attempt in milliseconds. Note that this flag has no effect if a user specified the value explicitly via ClientBuilder.writeTimeout(Duration).

      The default value of this flag is 1000L. Specify the -Dcom.linecorp.armeria.defaultWriteTimeoutMillis=<integer> JVM option to override the default value. 0 disables the timeout.

    • defaultServerIdleTimeoutMillis

      public static long defaultServerIdleTimeoutMillis()
      Returns the default server-side idle timeout of a connection for keep-alive in milliseconds. Note that this flag has no effect if a user specified the value explicitly via ServerBuilder.idleTimeout(Duration).

      The default value of this flag is 15000L. Specify the -Dcom.linecorp.armeria.defaultServerIdleTimeoutMillis=<integer> JVM option to override the default value.

    • defaultClientIdleTimeoutMillis

      public static long defaultClientIdleTimeoutMillis()
      Returns the default client-side idle timeout of a connection for keep-alive in milliseconds. Note that this flag has no effect if a user specified the value explicitly via ClientFactoryBuilder.idleTimeout(Duration).

      This default value of this flag is 10000L. Specify the -Dcom.linecorp.armeria.defaultClientIdleTimeoutMillis=<integer> JVM option to override the default value.

    • defaultHttp1MaxInitialLineLength

      public static int defaultHttp1MaxInitialLineLength()
      Returns the default maximum length of an HTTP/1 initial line. Note that this flag has no effect if a user specified the value explicitly via ServerBuilder.http1MaxInitialLineLength(int) or ClientFactoryBuilder.http1MaxInitialLineLength(int).

      This default value of this flag is 4096. Specify the -Dcom.linecorp.armeria.defaultHttp1MaxInitialLineLength=<integer> JVM option to override the default value.

    • defaultHttp1MaxHeaderSize

      public static int defaultHttp1MaxHeaderSize()
      Returns the default maximum length of all HTTP/1 headers in a request or response. Note that this flag has no effect if a user specified the value explicitly via ServerBuilder.http1MaxHeaderSize(int) or ClientFactoryBuilder.http1MaxHeaderSize(int).

      This default value of this flag is 8192. Specify the -Dcom.linecorp.armeria.defaultHttp1MaxHeaderSize=<integer> JVM option to override the default value.

    • defaultHttp1MaxChunkSize

      public static int defaultHttp1MaxChunkSize()
      Returns the default maximum length of each chunk in an HTTP/1 request or response content. The content or a chunk longer than this value will be split into smaller chunks so that their lengths never exceed it. Note that this flag has no effect if a user specified the value explicitly via ServerBuilder.http1MaxChunkSize(int) or ClientFactoryBuilder.http1MaxChunkSize(int).

      The default value of this flag is 8192. Specify the -Dcom.linecorp.armeria.defaultHttp1MaxChunkSize=<integer> JVM option to override the default value.

    • defaultUseHttp2Preface

      public static boolean defaultUseHttp2Preface()
      Returns the default value of the ClientFactoryBuilder.useHttp2Preface(boolean) option. If enabled, the HTTP/2 connection preface is sent immediately for a cleartext HTTP/2 connection, reducing an extra round trip incurred by the OPTIONS * HTTP/1.1 upgrade request. If disabled, the OPTIONS * HTTP/1.1 request with "Upgrade: h2c" header is sent for a cleartext HTTP/2 connection. Consider disabling this flag if your HTTP servers have issues handling or rejecting the HTTP/2 connection preface without a upgrade request. Note that this option does not affect ciphertext HTTP/2 connections, which use ALPN for protocol negotiation, and it has no effect if a user specified the value explicitly via ClientFactoryBuilder.useHttp2Preface(boolean).

      This flag is enabled by default. Specify the -Dcom.linecorp.armeria.defaultUseHttp2Preface=false JVM option to disable it.

    • defaultUseHttp1Pipelining

      public static boolean defaultUseHttp1Pipelining()
      Returns the default value of the ClientFactoryBuilder.useHttp1Pipelining(boolean) option. Note that this flag has no effect if a user specified the value explicitly via ClientFactoryBuilder.useHttp1Pipelining(boolean).

      This flag is disabled by default. Specify the -Dcom.linecorp.armeria.defaultUseHttp1Pipelining=true JVM option to enable it.

    • defaultPingIntervalMillis

      public static long defaultPingIntervalMillis()
      Returns the default value for the PING interval. A PING frame is sent for HTTP/2 server and client or an OPTIONS request with an asterisk ("*") is sent for HTTP/1 client.

      Note that this flag is only in effect when defaultServerIdleTimeoutMillis() for server and defaultClientIdleTimeoutMillis() for client are greater than the value of this flag.

      The default value of this flag is 0L milliseconds. Specify the -Dcom.linecorp.armeria.defaultPingIntervalMillis=<integer> JVM option to override the default value. If the specified value was smaller than 10 seconds, bumps PING interval to 10 seconds.

    • defaultMaxServerConnectionAgeMillis

      public static long defaultMaxServerConnectionAgeMillis()
      Returns the default server-side max age of a connection for keep-alive in milliseconds. If the value of this flag is greater than 0, a connection is disconnected after the specified amount of the time since the connection was established.

      The default value of this flag is 0L. Specify the -Dcom.linecorp.armeria.defaultMaxServerConnectionAgeMillis=<integer> JVM option to override the default value. If the specified value was smaller than 1 second, bumps the max connection age to 1 second.

      See Also:
      ServerBuilder.maxConnectionAgeMillis(long)

    • defaultHttp2InitialConnectionWindowSize

      public static int defaultHttp2InitialConnectionWindowSize()
      Returns the default value of the ServerBuilder.http2InitialConnectionWindowSize(int) and ClientFactoryBuilder.http2InitialConnectionWindowSize(int) option. Note that this flag has no effect if a user specified the value explicitly via ServerBuilder.http2InitialConnectionWindowSize(int) or ClientFactoryBuilder.http2InitialConnectionWindowSize(int).

      The default value of this flag is 1048576. Specify the -Dcom.linecorp.armeria.defaultHttp2InitialConnectionWindowSize=<integer> JVM option to override the default value.

    • defaultHttp2InitialStreamWindowSize

      public static int defaultHttp2InitialStreamWindowSize()
      Returns the default value of the ServerBuilder.http2InitialStreamWindowSize(int) and ClientFactoryBuilder.http2InitialStreamWindowSize(int) option. Note that this flag has no effect if a user specified the value explicitly via ServerBuilder.http2InitialStreamWindowSize(int) or ClientFactoryBuilder.http2InitialStreamWindowSize(int).

      The default value of this flag is 1048576. Specify the -Dcom.linecorp.armeria.defaultHttp2InitialStreamWindowSize=<integer> JVM option to override the default value.

    • defaultHttp2MaxFrameSize

      public static int defaultHttp2MaxFrameSize()
      Returns the default value of the ServerBuilder.http2MaxFrameSize(int) and ClientFactoryBuilder.http2MaxFrameSize(int) option. Note that this flag has no effect if a user specified the value explicitly via ServerBuilder.http2MaxFrameSize(int) or ClientFactoryBuilder.http2MaxFrameSize(int).

      The default value of this flag is 16384. Specify the -Dcom.linecorp.armeria.defaultHttp2MaxFrameSize=<integer> JVM option to override the default value.

    • defaultHttp2MaxStreamsPerConnection

      public static long defaultHttp2MaxStreamsPerConnection()
      Returns the default value of the ServerBuilder.http2MaxStreamsPerConnection(long) option. Note that this flag has no effect if a user specified the value explicitly via ServerBuilder.http2MaxStreamsPerConnection(long).

      The default value of this flag is 2147483647L. Specify the -Dcom.linecorp.armeria.defaultHttp2MaxStreamsPerConnection=<integer> JVM option to override the default value.

    • defaultHttp2MaxHeaderListSize

      public static long defaultHttp2MaxHeaderListSize()
      Returns the default value of the ServerBuilder.http2MaxHeaderListSize(long) and ClientFactoryBuilder.http2MaxHeaderListSize(long) option. Note that this flag has no effect if a user specified the value explicitly via ServerBuilder.http2MaxHeaderListSize(long) or ClientFactoryBuilder.http2MaxHeaderListSize(long).

      The default value of this flag is 8192L. Specify the -Dcom.linecorp.armeria.defaultHttp2MaxHeaderListSize=<integer> JVM option to override the default value.

    • defaultBackoffSpec

      public static String defaultBackoffSpec()
      Returns the Backoff specification string of the default Backoff returned by Backoff.ofDefault(). Note that this flag has no effect if a user specified the Backoff explicitly.

      The default value of this flag is "exponential=200:10000,jitter=0.2". Specify the -Dcom.linecorp.armeria.defaultBackoffSpec=<spec> JVM option to override the default value.

    • defaultMaxTotalAttempts

      public static int defaultMaxTotalAttempts()
      Returns the default maximum number of total attempts. Note that this flag has no effect if a user specified the value explicitly when creating a RetryingClient or a RetryingRpcClient.

      The default value of this flag is 10. Specify the -Dcom.linecorp.armeria.defaultMaxTotalAttempts=<integer> JVM option to override the default value.

    • routeCacheSpec

      @Nullable public static String routeCacheSpec()
      Returns the Caffeine specification string of the cache that stores the recent request routing history for all Services.

      The default value of this flag is "maximumSize=4096". Specify the -Dcom.linecorp.armeria.routeCache=<spec> JVM option to override the default value. For example, -Dcom.linecorp.armeria.routeCache=maximumSize=4096,expireAfterAccess=600s. Also, specify -Dcom.linecorp.armeria.routeCache=off JVM option to disable it.

    • routeDecoratorCacheSpec

      @Nullable public static String routeDecoratorCacheSpec()
      Returns the Caffeine specification string of the cache that stores the recent request routing history for all route decorators.

      The default value of this flag is "maximumSize=4096". Specify the -Dcom.linecorp.armeria.routeDecoratorCache=<spec> JVM option to override the default value. For example, -Dcom.linecorp.armeria.routeDecoratorCache=maximumSize=4096,expireAfterAccess=600s. Also, specify -Dcom.linecorp.armeria.routeDecoratorCache=off JVM option to disable it.

    • parsedPathCacheSpec

      @Nullable public static String parsedPathCacheSpec()
      Returns the Caffeine specification string of the cache that stores the recent results for parsing a raw HTTP path into a decoded pair of path and query string.

      The default value of this flag is "maximumSize=4096". Specify the -Dcom.linecorp.armeria.parsedPathCache=<spec> JVM option to override the default value. For example, -Dcom.linecorp.armeria.parsedPathCache=maximumSize=4096,expireAfterAccess=600s. Also, specify -Dcom.linecorp.armeria.parsedPathCache=off JVM option to disable it.

    • headerValueCacheSpec

      @Nullable public static String headerValueCacheSpec()
      Returns the Caffeine specification string of the cache that stores the recent results for converting a raw HTTP ASCII header value into a String. Only the header values whose corresponding header name is listed in cachedHeaders() will be cached.

      The default value of this flag is "maximumSize=4096". Specify the -Dcom.linecorp.armeria.headerValueCache=<spec> JVM option to override the default value. For example, -Dcom.linecorp.armeria.headerValueCache=maximumSize=4096,expireAfterAccess=600s. Also, specify -Dcom.linecorp.armeria.headerValueCache=off JVM option to disable it.

    • cachedHeaders

      public static List<String> cachedHeaders()
      Returns the list of HTTP header names whose corresponding values will be cached, as specified in headerValueCacheSpec(). Only the header value whose corresponding header name is listed in this flag will be cached. It is not recommended to specify a header with high cardinality, which will defeat the purpose of caching.

      The default value of this flag is ":authority,:scheme,:method,accept-encoding,content-type". Specify the -Dcom.linecorp.armeria.cachedHeaders=<comma separated list> JVM option to override the default.

    • fileServiceCacheSpec

      @Nullable public static String fileServiceCacheSpec()
      Returns the Caffeine specification string of the cache that stores the content of the HttpFiles read by a FileService. This value is used as the default of FileServiceBuilder.entryCacheSpec(String).

      The default value of this flag is "maximumSize=1024". Specify the -Dcom.linecorp.armeria.fileServiceCache=<spec> JVM option to override the default value. For example, -Dcom.linecorp.armeria.fileServiceCache=maximumSize=1024,expireAfterAccess=600s. Also, specify -Dcom.linecorp.armeria.fileServiceCache=off JVM option to disable it.

    • dnsCacheSpec

      public static String dnsCacheSpec()
      Returns the Caffeine specification string of the cache that stores the domain names and their resolved addresses. This value is used as the default of DnsResolverGroupBuilder.cacheSpec(String).

      The default value of this flag is "maximumSize=4096". Specify the -Dcom.linecorp.armeria.dnsCacheSpec=<spec> JVM option to override the default value. For example, -Dcom.linecorp.armeria.dnsCacheSpec=maximumSize=1024,expireAfterAccess=600s.

      This cache cannot be disabled with "off" unlike other cache specification flags.

    • annotatedServiceExceptionVerbosity

      public static ExceptionVerbosity annotatedServiceExceptionVerbosity()
      Returns the verbosity of exceptions logged by annotated HTTP services. The value of this property is one of the following: A log message would be written at WARN level.

      The default value of this flag is "unhandled". Specify the -Dcom.linecorp.armeria.annotatedServiceExceptionVerbosity=<all|unhandled|none> JVM option to override the default value.

      See Also:
      ExceptionVerbosity

    • preferredIpV4Addresses

      @Nullable public static Predicate<InetAddress> preferredIpV4Addresses()
      Returns the Predicate that is used to choose the non-loopback IP v4 address in SystemInfo.defaultNonLoopbackIpV4Address().

      The default value of this flag is null, which means all valid IPv4 addresses are preferred. Specify the -Dcom.linecorp.armeria.preferredIpV4Addresses=<csv> JVM option to override the default value. The csv should be Classless Inter-domain Routing(CIDR)s or exact IP addresses separated by commas. For example, -Dcom.linecorp.armeria.preferredIpV4Addresses=211.111.111.111,10.0.0.0/8,192.168.1.0/24.

    • useJdkDnsResolver

      public static boolean useJdkDnsResolver()
      Enables DefaultAddressResolverGroup that resolves domain name using JDK's built-in domain name lookup mechanism. Note that JDK's built-in resolver performs a blocking name lookup from the caller thread, and thus this flag should be enabled only when the default asynchronous resolver does not work as expected, for example by always throwing a DnsNameResolverTimeoutException.

      This flag is disabled by default. Specify the -Dcom.linecorp.armeria.useJdkDnsResolver=true JVM option to enable it.

    • reportBlockedEventLoop

      public static boolean reportBlockedEventLoop()
      Returns whether CompletableFutures returned by Armeria methods log a warning if CompletableFuture.join() or CompletableFuture.get() are called from an event loop thread. Blocking an event loop thread in this manner reduces performance significantly, possibly causing deadlocks, so it should be avoided at all costs (e.g. using thenApply() type methods to execute asynchronously or running the logic using ServiceRequestContext.blockingTaskExecutor().

      This flag is enabled by default. Specify the -Dcom.linecorp.armeria.reportBlockedEventLoop=false JVM option to disable it.

    • validateHeaders

      public static boolean validateHeaders()
      Enables validation of HTTP headers for dangerous characters like newlines - such characters can be used for injecting arbitrary content into HTTP responses.

      DISCLAIMER: Do not disable this unless you know what you are doing. It is recommended to keep this validation enabled to ensure the sanity of responses. However, you may wish to disable the validation to improve performance when you are sure responses are always safe, for example when only HTTP/2 is used, or when you populate headers with known values, and have no chance of using untrusted ones.

      See CWE-113 for more details on the security implications of this flag.

      This flag is enabled by default. Specify the -Dcom.linecorp.armeria.validateHeaders=false JVM option to disable it.

    • tlsAllowUnsafeCiphers

      public static boolean tlsAllowUnsafeCiphers()
      Returns whether to allow the bad cipher suites listed in RFC7540 for TLS handshake. Note that this flag has no effect if a user specified the value explicitly via ClientFactoryBuilder.tlsAllowUnsafeCiphers(boolean).

      This flag is disabled by default. Specify the -Dcom.linecorp.armeria.tlsAllowUnsafeCiphers=true JVM option to enable it.

    • transientServiceOptions

      public static Set<TransientServiceOption> transientServiceOptions()
      Returns the Set of TransientServiceOptions that are enabled for a TransientService.

      The default value of this flag is an empty string, which means all TransientServiceOptions are disabled. Specify the -Dcom.linecorp.armeria.transientServiceOptions=<csv> JVM option to override the default value. For example, -Dcom.linecorp.armeria.transientServiceOptions=WITH_METRIC_COLLECTION,WITH_ACCESS_LOGGING.