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

      public static boolean useEpoll()
      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.

    • 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.

      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 value has effect only if a user did not specify a worker group.

      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 value has effect only if a user did not specify a blocking task executor.

      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 value has effect only if a user did not specify it.

      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 value has effect only if a user did not specify it.

      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 value has effect only if a user did not specify it.

      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 value has effect only if a user did not specify it.

      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 value has effect only if a user did not specify it.

      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 value has effect only if a user did not specify it.

      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 value has effect only if a user did not specify it.

      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 value has effect only if a user did not specify it.

      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 response initial line. Note that this value has effect only if a user did not specify it.

      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 headers in an HTTP/1 response. Note that this value has effect only if a user did not specify it.

      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 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 value has effect only if a user did not specify it.

      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. Note that this value has effect only if a user did not specify it.

      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 value has effect only if a user did not specify it.

      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 value has effect only if a user did not specify it.

      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 value has effect only if a user did not specify it.

      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 value has effect only if a user did not specify it.

      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 value has effect only if a user did not specify it.

      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 value has effect only if a user did not specify it.

      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 default value of the backoffSpec parameter when instantiating a Backoff using Backoff.of(String). Note that this value has effect only if a user did not specify the defaultBackoffSpec in the constructor call.

      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 value has effect only if a user did not specify it 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 value of the routeCache parameter. It would be used to create a Caffeine Cache instance using CaffeineSpec for routing a request. The Cache would hold the mappings of RoutingContext and the designated ServiceConfig for a request to improve server performance.

      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 value of the routeDecoratorCache parameter. It would be used to create a Caffeine Cache instance using CaffeineSpec for mapping a route to decorator. The Cache would hold the mappings of RoutingContext and the designated dispatcher Services for a request to improve server performance.

      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 value of the parsedPathCache parameter. It would be used to create a Caffeine Cache instance using CaffeineSpec for mapping raw HTTP paths to parsed pair of path and query, after validation.

      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 value of the headerValueCache parameter. It would be used to create a Caffeine Cache instance using CaffeineSpec for mapping raw HTTP ASCII header values to String.

      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.

    • fileServiceCacheSpec

      @Nullable public static String fileServiceCacheSpec()
      Returns the value of the fileServiceCache parameter. It would be used to create a Caffeine Cache instance using CaffeineSpec for caching file entries.

      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.

    • cachedHeaders

      public static List<String> cachedHeaders()
      Returns the value of the cachedHeaders parameter which contains a comma-separated list of headers whose values are cached using headerValueCache.

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

    • compositeServiceCacheSpec

      @Nullable public static String compositeServiceCacheSpec()
      Returns the value of the compositeServiceCache parameter. It would be used to create a Caffeine Cache instance using CaffeineSpec for routing a request. The Cache would hold the mappings of RoutingContext and the designated ServiceConfig for a request to improve server performance.

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

    • 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.

    • useLegacyMeterNames

      public static boolean useLegacyMeterNames()
      Returns whether to switch back to Armeria's legacy Meter and Tag naming convention that is not compliant with Micrometer's default NamingConvention.

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