Skip to content

Options and Defaults

Guide Home | Previous: 12. Operations — Runtime Metrics · Graceful Drain · Readiness | Next: 14. Picking a Sample — Start with the Example Closest to Your Problem

View in another language — C++ · C#/.NET · Java · Kotlin · Node/TypeScript

What you get from this chapter

You learn what you can set, what value applies when you do not set it, and which values can still be changed after the host has started.

Option names and defaults are the same across supported languages. What differs is the spelling and the way you set them, and the tabs in each section show that. Most options work without being set. Check the default on the line that matters when you have a reason to change it, and use it as it is until then.

1. Where Settings Are Made and What They Cover

The same value has a different scope and a different window for change depending on where you set it.

Place Scope When it can change
Root options The default for this whole process Before the host starts
Node builder That one MeshNode, channel, or STREAM node Before the host starts
Runtime option Values that can change while running While running (§9) 
// Both sides must name the mesh identically, or they never see each other
// as peers. The routing id names this node; without it the Framework assigns
// a generated one, which a caller cannot type into a URL.
//
// A caller that names a routing id in connect(...) compares the advertised
// endpoint against the endpoint it dialed. Both use 127.0.0.1 here.
ZLinkMeshNodeBuilder mesh =
        options.addRouteMesh("game")
                .listen("tcp://127.0.0.1:7501")
                .setAdvertiseHost("127.0.0.1")
                .setRoutingId(RoutingId.from("game-server-1"));

There is no surface that calls a builder again after the host has started. An invalid combination is not deferred to the first call — it ends as a configuration error during startup.

2. Root Options

Option What it sets Default
Codec registration Payload serialization format Built-in JSON
bindHost The address a listener binds 127.0.0.1
advertiseHost The address given to peers Not set — the non-wildcard bind address or wildcard loopback
defaultRequestTimeout How long a request waits for its reply 30 seconds
sessionReplacementCallbackTimeout How long a session replacement callback may run 30 seconds
Stream compression STREAM payload compression LZ4 in use
Worker MinThreads · maxThreads Thread count of the CPU worker pool 0 · twice the processor count
Worker idleTimeout How long an idle thread is kept 30 seconds
applicationVersion · maintenanceWave Version and maintenance group a rolling update compares 0 · not set
Handler discovery, filters, metadata policy What is registered and which keys may pass Only what is registered
Location store · relocation store Stores for placement and state transfer Single-node setup when absent
  • The bind address defaults to loopback. Set the bind address and the advertised address separately when a node or client on another host has to connect.
  • The listen host is where the current process binds its socket, and 0.0.0.0 accepts on every local interface. advertiseHost is the address peers actually dial and the Location Store publishes. Use 127.0.0.1 for a wildcard bind in a single-machine example. For multiple hosts, containers, NAT, or Kubernetes, set a reachable IP address or DNS name for that node, using a Pod IP or per-Pod DNS in Kubernetes. When omitted, advertiseHost advertises a non-wildcard bind host or the same-family loopback for a wildcard; an advertised host cannot be a wildcard. Channel Messaging shows each language's actual option surface in its mesh registration block.
  • STREAM compression starts enabled. Turn it off explicitly in the compression settings.
  • The CPU worker pool has no queue limit. Core HWM and Application Job Queue Limits limits intake. defaultRequestTimeout rejects values of 0 or below.

3. Core HWM and Application Job Queue Limits

Core HWM limits the bytes held by the ordinary queues, and the Application job queue limits the number of jobs waiting for a handler to start across the whole host. How both behave is covered by Backpressure.

Option What it sets Default
coreHwmMemoryLimitBytes Positive memory limit used for Core budget calculation and connection admission Not set
coreHwmBudgetBytes Manual Core budget that takes precedence over the profile Not set
CoreHwmProfile Core auto-budget profile Balanced
ApplicationJobQueueProfile Profile used to compute the job limit Balanced
maxQueuedApplicationJobs Exact job limit that replaces the profile calculation Not set
setApplicationJobQueuePauseThresholdPercent Usage at which intake pauses 80
setApplicationJobQueueResumeThresholdPercent Usage at which intake resumes 60

The memory limit and the Core budget accept positive values only. The manual job limit ranges over 1..2,147,483,647, and 0 is not unlimited but a startup configuration error. The two percentages range over 1..100 and 0..99, and the resume value must be smaller than the pause value. Both profiles use the same labels but are independent values, and Balanced means 128 jobs per processor.

4. Diagnostic Recording

Option What it sets Default
Recording level off · errors · Normal · Detailed errors
TraceSampleRate Share of normal flows recorded, ranging over 0.0..1.0 1.0
includeMessageSizes Whether payload byte sizes are recorded too Not recorded

What happens to a packet that arrives with no handler is set in the same place. A request gets an error reply, while a send and a publish are recorded and dropped. The error-reply action cannot be chosen for a send or a publish because they have no reply path. This setting does not exist in C++, where only the default behavior applies. What each level records is covered by Monitoring.

5. MeshNode Options

Option What it sets Default
listen This node's own address for peers to connect to Must be set
bindHost · advertiseHost Bind and advertised address for this node alone The root value
RoutingId · routingIdPrefix This node's identifier Generated
objectRole Whether the node takes part in placement None
placementWeight Share of new placements, ranging over 0..10000 100
ActorLimit · spotLimit How many this node may hold at once 0 — no limit
ActivationConcurrency Cold activations that may proceed at once 128
instanceSpotIdleTimeout How long an idle Instance Spot is kept 0 — never removed
defaultRequestTimeout Limit for requests leaving this node The root value (30 seconds)
Peer connection Peers to connect to manually None — the location store finds them

For both limits, 0 means no limit and a positive value ranges over 1..2,147,483,647. ActivationConcurrency rejects 0 instead, because it limits the activations in progress rather than the number of objects.

6. Send Waiting and Socket Limits

Option What it sets Default
Classic fanout publisher sendTimeout How long a publish waits for room 1 second
receiveTimeout Wait limit in the receive direction Not set
sendHighWaterMark · receiveHighWaterMark Bytes held per peer. 0 is unlimited Not set — the Core computes it

A send waits until capacity recovers, with no time limit or caller cancellation. Removing its route while pending ends it with Unavailable; closing the socket or runtime ends it with ShuttingDown. Only Classic fanout publish uses the publisher sendTimeout, ending with DeadlineExceeded if capacity does not recover within that limit.

Connections between MeshNodes have no message size limit setting — that limit belongs to the STREAM node and the ClientServer listener (Backpressure).

Where a manual HWM is set differs by language

The surface for setting the per-direction byte limit directly exists only in some languages and not in C++. When it is not set, the Core computes it from the physical queues, which makes leaving the value unset the ordinary configuration. A setting that limits one execution unit's mailbox by message count or bytes has no effect in any language.

7. Location Options

Option What it sets Default
ownerLeaseRenewInterval How often ownership is renewed 5 seconds
ownerLeaseTtl When ownership without renewal expires 15 seconds
ownerLeaseRenewTimeout Limit for one renewal attempt 3 seconds
ownerLeaseFencingMargin Margin for releasing authority before expiry 5 seconds
pollingInterval How often a store without change notification is re-read 1 second
storeFailureGrace How long a store failure is tolerated 30 seconds
routeCacheMaxAge How long a resolved location is reused 15 seconds
messageFollowDuration How long the former owner forwards messages to the new owner 30 seconds
sessionRelocationSealTimeout Limit for waiting on a session route update 3 seconds
RelocationPayloadChunkLimit Size limit of one relocation payload chunk 256 KiB
RelocationInFlightPayloadBudget Chunk bytes in flight on one connection 16 MiB
RelocationNodeInFlightPayloadBudget The same limit across the whole node 0 — not applied
relocationCutoverWaitTimeout How long the cutover is awaited 1 second

The lease values move together. max(OwnerLeaseRenewInterval, OwnerLeaseRenewTimeout) + OwnerLeaseRenewTimeout must be smaller than OwnerLeaseTtl - OwnerLeaseFencingMargin. The defaults satisfy this at 8 seconds against 10 seconds. routeCacheMaxAge must be at least five seconds shorter than messageFollowDuration, and 0 for either turns off the route cache and message forwarding respectively. Placement and transfer behavior are covered by Location and Relocation.

8. STREAM Node Options

Option What it sets Default
bind The address clients connect to Must be set
bindHost · advertiseHost Bind and advertised address The root value
Session registration The session type created per connection Must be set
maxMessageSize Byte limit of one message sent by a client 64 KiB
TLS settings Server certificate and whether a client certificate is required Plaintext, no client certificate required
Actor dispatch Forwarding an incoming packet to the bound Actor Off

maxMessageSize applies only in the client-to-server direction, and 0 means no limit is imposed. A message over the limit does not reach the handler even in part, and the server closes the connection. Actor dispatch is enabled once per STREAM node, and a second call is an error. Which mesh the Actor is found in is decided by the global ActorId rather than an argument, so no mesh name is given alongside. The registration code is covered by STREAM and Session and Actor.

9. Values That Can Change While Running

The values that can change after startup are the selection weights. The rest are fixed when the host starts.

Value What it is for
Channel weight Share of new requests and sends this node is selected for
Placement weight Share of new Spots and Actors placed on this node 
// Weight is the one value this node can change while running. 0 keeps the
// socket open and finishes in-flight work, but other nodes stop choosing this
// one for new calls. 100 is the normal value.
//
// ZLinkRouteMeshRuntimeOptions is a bean the Framework registers; ask for it in
// the constructor. The one-argument channel(...) resolves the mesh itself, and
// fails if two meshes register the same channel name.
@RestController
class ChannelWeightController {

    private final ZLinkRouteMeshRuntimeOptions mesh;

    ChannelWeightController(ZLinkRouteMeshRuntimeOptions mesh) {
        this.mesh = mesh;
    }

    @PostMapping("/admin/channels/{channel}/weight")
    WeightChanged weight(@PathVariable String channel, @RequestParam int value) {
        mesh.channel(channel).weight(value);
        return new WeightChanged(channel, value);
    }

    record WeightChanged(String channel, int weight) {}
}

Both values range over 0..10000 and default to 100. Setting 0 stops new assignments only — existing objects and connections are kept. In a zero-downtime rollout, use it to keep new traffic away from this node before starting a relocation (Operations and Lifecycle).

10. Values That Must Be Set

These have no default, and leaving them out either fails startup or produces behavior other than the one intended.

Value When it is missing
The MeshNode listen address Configuration error at startup
At least one channel role or object role on the MeshNode Configuration error at startup
The STREAM node bind address and session type Configuration error at startup
Exactly one relocation policy per Spot or Actor factory Configuration error at startup
A relocation store when a state-carrying factory or an Instance Spot exists Configuration error at startup
A location store when several nodes are used Peers cannot be found
Metadata keys passed between a connection and an Actor The value is dropped without an error

11. Common Problems

  • A setting was changed but has no effect — most options are fixed when the host starts. The values that can change while running are listed in §9.
  • A node on another host cannot connect — the bind address defaults to loopback. Set the bind address and the advertised address separately.
  • Memory keeps growing after a value was set to 0 — 0 on a byte limit is unlimited. Leave the value unset to let the Core compute it.
  • Ownership keeps being lost — the larger of the renewal interval and the renewal timeout, plus the renewal timeout, is larger than the lifetime minus the margin.
  • The connection drops on a large message from a client — the STREAM size limit is 64 KiB. Raise it on a node that receives large payloads.
  • A weight of 0 was expected to drop existing connections — a weight stops new assignments only, and existing objects and connections are kept.