Netty: Document available system properties

[micfra]

The _Netty user guide_ should contain a short list along with some description of the available system properties -Dio.netty.*.

A fast scan through the source showed they are spread all across the project resolved by using the io.netty.util.internal.SystemPropertyUtil.getXX(key) methods.

I'd like to help if somebody tells where the correct place in the wiki pages is.

[normanmaurer]

@micfra I wonder if we should provide some kind of a registry for all of them that can be queried somehow just in case these change or new ones are added.

[Scottmitch]

For 5.0 I wonder if we should move away from system properties. Static state can be brittle, introduces many entry points for configuration, and can be difficult to reconcile if there are libraries which use Netty that want a certain configuration which may conflict with the end application's configuration.

[micfra]

Its a matter what the project wants to support. I would suggest Configuration classes evaluating system properties first and use explicit values if present falling back to default values if necessary. So each component might document its properties configurable by system properties itself. Support for a kind of global properties is necessary as well (like io.netty.noUnsafe). You might thing about all this for 5.x.

But is there a way to extract the available properties for 4.x and describe what happens if used?

[rockwotj]

I checked out the source code for the latest 4.1 release and ran ag -Q '"io.netty' this gave me this list:

buffer/src/main/java/io/netty/buffer/AbstractByteBuf.java
46:    private static final String PROP_MODE = "io.netty.buffer.bytebuf.checkAccessible";

buffer/src/main/java/io/netty/buffer/AdvancedLeakAwareByteBuf.java
37:    private static final String PROP_ACQUIRE_AND_RELEASE_ONLY = "io.netty.leakDetection.acquireAndReleaseOnly";

buffer/src/main/java/io/netty/buffer/ByteBufUtil.java
71:                "io.netty.allocator.type", PlatformDependent.isAndroid() ? "unpooled" : "pooled");
88:        THREAD_LOCAL_BUFFER_SIZE = SystemPropertyUtil.getInt("io.netty.threadLocalDirectBufferSize", 64 * 1024);
91:        MAX_CHAR_BUFFER_SIZE = SystemPropertyUtil.getInt("io.netty.maxThreadLocalCharBufferSize", 16 * 1024);

buffer/src/main/java/io/netty/buffer/PooledByteBufAllocator.java
53:        int defaultPageSize = SystemPropertyUtil.getInt("io.netty.allocator.pageSize", 8192);
63:        int defaultMaxOrder = SystemPropertyUtil.getInt("io.netty.allocator.maxOrder", 11);
88:                        "io.netty.allocator.numHeapArenas",
94:                        "io.netty.allocator.numDirectArenas",
100:        DEFAULT_TINY_CACHE_SIZE = SystemPropertyUtil.getInt("io.netty.allocator.tinyCacheSize", 512);
101:        DEFAULT_SMALL_CACHE_SIZE = SystemPropertyUtil.getInt("io.netty.allocator.smallCacheSize", 256);
102:        DEFAULT_NORMAL_CACHE_SIZE = SystemPropertyUtil.getInt("io.netty.allocator.normalCacheSize", 64);
107:                "io.netty.allocator.maxCachedBufferCapacity", 32 * 1024);
111:                "io.netty.allocator.cacheTrimInterval", 8192);
114:                "io.netty.allocator.useCacheForAllThreads", true);
117:                "io.netty.allocator.directMemoryCacheAlignment", 0);

buffer/src/test/java/io/netty/buffer/PooledByteBufAllocatorTest.java
387:                "io.netty.buffer.PooledByteBufAllocatorTest.testConcurrentUsageTime", 15000));

codec/src/main/java/io/netty/handler/codec/compression/ZlibCodecFactory.java
37:        noJdkZlibDecoder = SystemPropertyUtil.getBoolean("io.netty.noJdkZlibDecoder",
41:        noJdkZlibEncoder = SystemPropertyUtil.getBoolean("io.netty.noJdkZlibEncoder", false);

codec-http2/src/main/java/io/netty/handler/codec/http2/WeightedFairQueueByteDistributor.java
67:            max(1, SystemPropertyUtil.getInt("io.netty.http2.childrenMapSize", 2));

common/src/main/java/io/netty/util/concurrent/DefaultPromise.java
39:            SystemPropertyUtil.getInt("io.netty.defaultPromise.maxListenerStackDepth", 8));

common/src/main/java/io/netty/util/concurrent/SingleThreadEventExecutor.java
51:            SystemPropertyUtil.getInt("io.netty.eventexecutor.maxPendingTasks", Integer.MAX_VALUE));

common/src/main/java/io/netty/util/internal/InternalThreadLocalMap.java
50:                SystemPropertyUtil.getInt("io.netty.threadLocalMap.stringBuilder.initialSize", 1024);
53:        STRING_BUILDER_MAX_SIZE = SystemPropertyUtil.getInt("io.netty.threadLocalMap.stringBuilder.maxSize", 1024 * 4);

common/src/main/java/io/netty/util/internal/NativeLibraryLoader.java
50:        String workdir = SystemPropertyUtil.get("io.netty.native.workdir");
69:                "io.netty.native.deleteLibAfterLoading", true);

common/src/main/java/io/netty/util/internal/PlatformDependent.java
83:            HAS_UNSAFE && !SystemPropertyUtil.getBoolean("io.netty.noPreferDirect", false);
153:        long maxDirectMemory = SystemPropertyUtil.getLong("io.netty.maxDirectMemory", -1);
175:                SystemPropertyUtil.getInt("io.netty.uninitializedArrayAllocationThreshold", 1024);
1055:            f = toDirectory(SystemPropertyUtil.get("io.netty.tmpdir"));
1133:        int bitMode = SystemPropertyUtil.getInt("io.netty.bitMode", 0);

common/src/main/java/io/netty/util/internal/PlatformDependent0.java
368:        final boolean noUnsafe = SystemPropertyUtil.getBoolean("io.netty.noUnsafe", false);
378:        if (SystemPropertyUtil.contains("io.netty.tryUnsafe")) {
379:            tryUnsafe = SystemPropertyUtil.getBoolean("io.netty.tryUnsafe", true);

common/src/main/java/io/netty/util/internal/ThreadLocalRandom.java
75:        initialSeedUniquifier = SystemPropertyUtil.getLong("io.netty.initialSeedUniquifier", 0);

common/src/main/java/io/netty/util/NettyRuntime.java
58:         * This can be overridden by setting the system property "io.netty.availableProcessors" or by invoking
68:                                "io.netty.availableProcessors",
92:     * can be overridden by setting the system property "io.netty.availableProcessors" or by invoking

common/src/main/java/io/netty/util/NetUtil.java
274:                        if (SystemPropertyUtil.getBoolean("io.netty.net.somaxconn.trySysctl", false)) {

common/src/main/java/io/netty/util/Recycler.java
64:        int maxCapacityPerThread = SystemPropertyUtil.getInt("io.netty.recycler.maxCapacityPerThread",
65:                SystemPropertyUtil.getInt("io.netty.recycler.maxCapacity", DEFAULT_INITIAL_MAX_CAPACITY_PER_THREAD));
73:                SystemPropertyUtil.getInt("io.netty.recycler.maxSharedCapacityFactor",
77:                SystemPropertyUtil.getInt("io.netty.recycler.maxDelayedQueuesPerThread",
82:                max(SystemPropertyUtil.getInt("io.netty.recycler.linkCapacity", 16), 16));
87:        RATIO = safeFindNextPositivePowerOfTwo(SystemPropertyUtil.getInt("io.netty.recycler.ratio", 8));

common/src/main/java/io/netty/util/ResourceLeakDetector.java
36:    private static final String PROP_LEVEL_OLD = "io.netty.leakDetectionLevel";
37:    private static final String PROP_LEVEL = "io.netty.leakDetection.level";
40:    private static final String PROP_MAX_RECORDS = "io.netty.leakDetection.maxRecords";
42:    private static final String PROP_MAX_SAMPLED_RECORDS = "io.netty.leakDetection.maxSampledRecords";
94:        if (SystemPropertyUtil.get("io.netty.noResourceLeakDetection") != null) {
95:            disabled = SystemPropertyUtil.getBoolean("io.netty.noResourceLeakDetection", false);
513:            STACK_TRACE_ELEMENT_EXCLUSIONS.add("io.netty.util.ReferenceCountUtil.touch");
514:            STACK_TRACE_ELEMENT_EXCLUSIONS.add("io.netty.buffer.AdvancedLeakAwareByteBuf.touch");
515:            STACK_TRACE_ELEMENT_EXCLUSIONS.add("io.netty.buffer.AbstractByteBufAllocator.toLeakAwareBuffer");
517:                    "io.netty.buffer.AdvancedLeakAwareByteBuf.recordLeakNonRefCountingOperation");

common/src/main/java/io/netty/util/ResourceLeakDetectorFactory.java
109:                        return SystemPropertyUtil.get("io.netty.customResourceLeakDetector");

common/src/main/java/io/netty/util/ThreadDeathWatcher.java
56:        String serviceThreadPrefix = SystemPropertyUtil.get("io.netty.serviceThreadPrefix");

common/src/test/java/io/netty/util/NettyRuntimeTests.java
166:        final String availableProcessorsSystemProperty = SystemPropertyUtil.get("io.netty.availableProcessors");
168:            System.setProperty("io.netty.availableProcessors", "2048");
173:                System.setProperty("io.netty.availableProcessors", availableProcessorsSystemProperty);
175:                System.clearProperty("io.netty.availableProcessors");
183:        final String availableProcessorsSystemProperty = SystemPropertyUtil.get("io.netty.availableProcessors");
185:            System.clearProperty("io.netty.availableProcessors");
190:                System.setProperty("io.netty.availableProcessors", availableProcessorsSystemProperty);
192:                System.clearProperty("io.netty.availableProcessors");

handler/src/main/java/io/netty/handler/ssl/ConscryptAlpnSslEngine.java
45:            "io.netty.handler.ssl.conscrypt.useBufferAllocator", true);

handler/src/main/java/io/netty/handler/ssl/OpenSsl.java
77:            Class.forName("io.netty.internal.tcnative.SSL", false, OpenSsl.class.getClassLoader());
159:                                                "io.netty.handler.ssl.openssl.useKeyManagerFactory", true);

handler/src/main/java/io/netty/handler/ssl/ReferenceCountedOpenSslContext.java
99:                            SystemPropertyUtil.getInt("io.netty.handler.ssl.openssl.bioNonApplicationBufferSize",

handler/src/main/java/io/netty/handler/ssl/SslHandler.java
1028:                if (classname.startsWith("io.netty.")) {

handler/src/main/java/io/netty/handler/ssl/util/SelfSignedCertificate.java
65:            "io.netty.selfSignedCertificate.defaultNotBefore", System.currentTimeMillis() - 86400000L * 365));
68:            "io.netty.selfSignedCertificate.defaultNotAfter", 253402300799000L));

microbench/src/main/java/io/netty/microbench/buffer/ByteBufBenchmark.java
30:        System.setProperty("io.netty.buffer.bytebuf.checkAccessible", "false");

microbench/src/main/java/io/netty/microbench/buffer/HeapByteBufBenchmark.java
42:        unsafeBuffer = newBuffer("io.netty.buffer.UnpooledUnsafeHeapByteBuf");
43:        buffer = newBuffer("io.netty.buffer.UnpooledHeapByteBuf");

microbench/src/main/java/io/netty/microbench/headers/ReadOnlyHttp2HeadersBenchmark.java
57:    private final AsciiString authority = new AsciiString("io.netty");

testsuite/src/main/java/io/netty/testsuite/transport/socket/SocketTestPermutation.java
47:    static final String BAD_HOST = SystemPropertyUtil.get("io.netty.testsuite.badHost", "netty.io");
48:    static final int BAD_PORT = SystemPropertyUtil.getInt("io.netty.testsuite.badPort", 65535);

testsuite-osgi/src/test/java/io/netty/osgitests/OsgiBundleTest.java
46:    private static final String GROUP = "io.netty";

transport/src/main/java/io/netty/channel/AbstractChannelHandlerContext.java
1032:                SystemPropertyUtil.getBoolean("io.netty.transport.estimateSizeOnSubmit", true);
1036:                SystemPropertyUtil.getInt("io.netty.transport.writeTaskSizeOverhead", 48);

transport/src/main/java/io/netty/channel/ChannelOutboundBuffer.java
59:            SystemPropertyUtil.getInt("io.netty.transport.outboundBufferEntrySizeOverhead", 96);

transport/src/main/java/io/netty/channel/DefaultChannelId.java
60:        String customProcessId = SystemPropertyUtil.get("io.netty.processId");
86:        String customMachineId = SystemPropertyUtil.get("io.netty.machineId");

transport/src/main/java/io/netty/channel/MultithreadEventLoopGroup.java
41:                "io.netty.eventLoopThreads", NettyRuntime.availableProcessors() * 2));

transport/src/main/java/io/netty/channel/nio/NioEventLoop.java
63:            SystemPropertyUtil.getBoolean("io.netty.noKeySetOptimization", false);
103:        int selectorAutoRebuildThreshold = SystemPropertyUtil.getInt("io.netty.selectorAutoRebuildThreshold", 512);

transport/src/main/java/io/netty/channel/PendingWriteQueue.java
38:            SystemPropertyUtil.getInt("io.netty.transport.pendingWriteSizeOverhead", 64);

transport/src/main/java/io/netty/channel/SingleThreadEventLoop.java
36:            SystemPropertyUtil.getInt("io.netty.eventLoop.maxPendingTasks", Integer.MAX_VALUE));

Even without documentation this is a pretty good start.