Forked-JVM CPU and Heap Sizing

Where per_fork_slice ≥ 2:

The parent JVM (the one running tika-app in Tika Pipes mode) is light on CPU — it just serializes requests, deserializes responses, and runs the heartbeat — but it must not be CPU-starved. A starved parent shows up as pathological tail latency on small operations like socket.write(), because the calling thread gets preempted between clock reads. We reserve 2 cores for the parent by default.

If slice ≥ 2, Tika injects -XX:ActiveProcessorCount=<slice> into each forked JVM. If slice < 2, the auto-cap is skipped and a WARN is logged advising the operator to lower numClients. Skipping is intentional: at slice=1 the fork’s only CPU is fully consumed by parsing, so its socket-reader thread cannot run and the parent’s writes block on receiver-side back-pressure — measurably worse than no cap at all.

For typical cloud-VM core counts:

The general rule is: pick the largest numClients that satisfies numClients × 2 + 2 ≤ hostCores. Beyond that point, adding forks starts hurting throughput.

numClients is a ceiling on concurrent forks, not a resident count:

Together these make the resident fork count track recent concurrency rather than numClients, so over-sizing numClients costs little at idle. Per-fork CPU and heap slices are still computed statically from numClients (a lone warm fork does not inherit its idle siblings' shares) — capacity planning above is unchanged.

Every PipesParser startup emits a one-shot summary line on its main logger so operators can see what was decided:

The autoCap field is one of:

Two WARN-level messages call out clearly-bad provisioning:

grep pipes-cpu-sizing on the parent’s logs surfaces all sizing-related output.

Everything above describes sizing for one PipesParser — one pipes config section, one set of forks. The auto-sizer has no visibility into anything else running in the same JVM.

This matters concretely for tika-server: /tika`/rmeta`/unpack`/meta`/detect+ /pipes and /async are backed by two independent groups when both are enabled in the same server — the first six endpoints share one PipesParser instance, and /async manages its own fork pool directly (not via PipesParser at all, though it uses the same underlying auto-sizer). Each group’s auto-sizer computes its slice from Runtime.availableProcessors() as if it were the only consumer on the host — it does not know the sibling group in the same process is about to start its own numClients forks too. The result: with numClients=2 on both, you get 4 total forked JVMs, each capped assuming exclusive access to the whole host. Whether that’s actually oversubscribed depends on your host’s real core count relative to those combined numClients values — it’s not automatic, but the auto-sizer also won’t warn you, because each group looks correctly sized from its own perspective alone. See Endpoints and Forked-Process Groups for the tika-server-specific guidance.

The same applies to any application embedding PipesForkParser/PipesParser directly and constructing more than one instance in a single JVM — the auto-sizer will size each independently, with the same caveat.

There is no automatic fix for this today: unlike the single-group case, where Tika detects and warns about bad provisioning, each group has no way to learn what its siblings already claimed. Mitigate it explicitly — either run fewer groups per process, or set -XX:ActiveProcessorCount yourself (next section) with the combined total in mind.

If you want to manage ActiveProcessorCount yourself (e.g., to allocate a different slice based on workload knowledge), just include it in your config:

When Tika sees an explicit -XX:ActiveProcessorCount in forkedJvmArgs, it respects your value and skips the auto-injection — the sizing summary will report autoCap=user-set in forkedJvmArgs.

Heap is auto-sized the same way CPU is. Left to itself, every forked JVM takes its own default max heap — a fixed fraction of host or container memory — so numClients forks have a combined ceiling well above what the host actually has. When you have not set -Xmx (or -XX:MaxRAMPercentage/-XX:MaxRAMFraction) yourself, Tika injects -XX:MaxRAMPercentage=75/numClients, leaving the remainder for the parent JVM and the OS. A single fork gets 60. The parent claims the JVM default (about 25% of the container) on top of whatever the forks take, and metaspace, thread stacks and page cache come out of what is left; committing the whole container between the two JVMs trades a clean per-document OOM for an OOM-kill that takes both down. The pipes-cpu-sizing summary line reports the decision as heap=…​.

Set -Xmx explicitly when you know your workload: the auto-slice is a safe default, not a tuned one, and a fork that legitimately needs more than its slice will OOM where an untuned JVM might have grown into spare memory.

A reasonable starting point is ~2 GB of heap per fork (passed via -Xmx2g in forkedJvmArgs). The number falls out of three independent constraints any of which can dominate:

This is a default — not a tuning recommendation. To right-size for your specific corpus:

The pod-level heap budget is numClients × per-fork-Xmx + parent-overhead. On a 16 GB node running numClients=4, that’s about 4 × 2 GB + 1 GB ≈ 9 GB — comfortably below the node limit, leaving room for kernel, IO buffers, and a non-saturated pod.

The formula uses Runtime.availableProcessors() for the host CPU count, which on JDK 17+ honors cgroup CPU limits. So in Kubernetes:

This document only covers per-client (forked-JVM) mode, which is the default. In shared-server mode (useSharedServer=true) all clients use a single forked JVM, so the multi-process thread-blowup problem doesn’t apply and the auto-cap is not applied. See Shared Server Mode for that mode’s trade-offs.