> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/linux-jvm-method-latency.md).

# Linux JVM method latency

Linux JVM method latency is a chaos fault that uses Byteman to add `LATENCY` milliseconds of delay to every invocation of `CLASS.METHOD` in the target Java process for `DURATION`, then removes the rule. The target Java process is selected by `PID`, by `STARTUP_COMMAND`, or by attaching to a running Byteman agent on `PORT`. The fault runs through the Linux Chaos Infrastructure (LCI) systemd service installed on the target VM.

Use this fault to test how a Java workload behaves when a hot method gets slow: whether the caller honors its own timeout, whether thread-pool exhaustion appears, whether circuit breakers fire, and whether monitoring detects the in-JVM slowdown within the alerting SLA.

{% hint style="info" %}
**RUN YOUR FIRST EXPERIMENT**

If you have not installed the Linux Chaos Infrastructure yet, go to [Linux Chaos Infrastructure](/resilience-testing/chaos-engineering/use-chaos-engineering/infrastructure/types/legacy-infra/linux.md) to install the agent and connect the VM to the control plane.
{% endhint %}

***

### Use cases <a href="#use-cases" id="use-cases"></a>

Run this fault when you want to answer concrete questions like:

* **Method slowdown tolerance:** When `CLASS.METHOD` slows by `LATENCY` milliseconds, do request handlers stay inside their p99 SLA?
* **Thread-pool starvation:** Do worker pools or async executors back up when a hot method blocks?
* **Caller timeouts:** Do callers honor their own timeouts, or do they hold the thread until the method returns?
* **Monitoring fidelity:** Do alerts on method-level latency, queue depth, and request latency fire within the alerting SLA?

***

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* **Linux Chaos Infrastructure installed:** The `linux-chaos-infrastructure` systemd service is `active` on the target VM and the infrastructure is in `CONNECTED` state. Go to [Linux Chaos Infrastructure](/resilience-testing/chaos-engineering/use-chaos-engineering/infrastructure/types/legacy-infra/linux.md) to install it.
* **Target JVM identifiable:** Provide one of `PID` or `STARTUP_COMMAND`, or ensure a Byteman agent is already listening on `PORT`.
* **`JAVA_HOME` reachable:** Set `JAVA_HOME` if it is not on the LCI service environment.
* **Target class loaded:** The JVM must have `CLASS` loaded and the matching `METHOD` defined.

***

### Supported environments <a href="#supported-environments" id="supported-environments"></a>

The fault has been tested on the following Linux distributions. Go to [Linux fault requirements](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/permissions.md) to see the full compatibility matrix.

| Platform                                        | Support status                                          |
| ----------------------------------------------- | ------------------------------------------------------- |
| Ubuntu 16+, Debian 10+                          | Supported                                               |
| CentOS 7+, RHEL 7+, Fedora 30+                  | Supported                                               |
| openSUSE LEAP 15.4+ / SUSE Linux Enterprise 15+ | Supported                                               |
| JVM versions                                    | OpenJDK 8, 11, 17, 21 (any JVM compatible with Byteman) |

***

### Permissions required <a href="#permissions-required" id="permissions-required"></a>

This fault is classified as a **Basic** Linux fault. It runs with the privileges of the Linux Chaos Infrastructure systemd service (root user and root user group) on the target VM. The LCI service must have permission to attach to the target Java process. No cloud credentials are needed.

***

### Fault tunables <a href="#fault-tunables" id="fault-tunables"></a>

Configure the following fault parameters when you add Linux JVM method latency to an experiment in Chaos Studio. Defaults are shown for reference.

**Required parameters**

| Tunable  | Description                                              | Default    |
| -------- | -------------------------------------------------------- | ---------- |
| `CLASS`  | Fully qualified class name containing the target method. | (required) |
| `METHOD` | Method name within `CLASS` to delay.                     | (required) |

**JVM selectors (provide one or rely on `PORT`)**

| Tunable           | Description                                                                             | Default |
| ----------------- | --------------------------------------------------------------------------------------- | ------- |
| `PID`             | PID of the target Java process. Set to `0` to fall back to `STARTUP_COMMAND` or `PORT`. | `0`     |
| `STARTUP_COMMAND` | Substring of the Java process command line used to identify the target.                 | `""`    |
| `PORT`            | Port of the Byteman agent.                                                              | `9091`  |
| `JAVA_HOME`       | Path to the JDK used by the target JVM.                                                 | `""`    |

**Chaos parameters**

| Tunable     | Description                                                                                                                                                                                                      | Default |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `DURATION`  | Total duration of the fault. Accepts `[hours]h[minutes]m[seconds]s` format.                                                                                                                                      | `30s`   |
| `LATENCY`   | Latency to inject per method call, in milliseconds.                                                                                                                                                              | `2000`  |
| `RAMP_TIME` | Wait period in seconds before and after the fault. Go to [ramp time](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/common-tunables-for-all-faults.md#ramp-time) to read how it is applied. | `0`     |

Tunables that apply to every fault are documented in [common tunables for all faults](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/common-tunables-for-all-faults.md).

***

### Fault execution in brief <a href="#fault-execution-in-brief" id="fault-execution-in-brief"></a>

Attaches Byteman to the target JVM on `PORT`, installs a rule that sleeps `LATENCY` milliseconds before `CLASS.METHOD` executes (per invocation) for `DURATION`, then removes the rule.

***

### Expected behavior during fault execution <a href="#expected-behavior-during-fault-execution" id="expected-behavior-during-fault-execution"></a>

* Every invocation of `CLASS.METHOD` takes `LATENCY` milliseconds longer than usual for the duration of the fault.
* Request handlers that depend on the method are delayed; thread-pool occupancy rises.
* Tail latency (`p99`) for endpoints exercising the method shifts upward by approximately `LATENCY`.
* Callers that have shorter timeouts than `LATENCY` see clean timeout errors.
* After the duration ends, the Byteman rule is removed and the method runs at baseline speed.

{% hint style="info" %}
**WHEN THE FAULT ENDS**

The chaos pod removes the Byteman rule. The next invocation of the method runs at baseline speed; in-flight invocations complete after their delay.
{% endhint %}

#### Signals to watch <a href="#signals-to-watch" id="signals-to-watch"></a>

Attach [resilience probes](/resilience-testing/chaos-engineering/use-chaos-engineering/probes.md) to assert each layer:

* **Method latency:** Use a [Prometheus probe](/resilience-testing/chaos-engineering/use-chaos-engineering/probes/apm-probes.md) on application method-level latency metrics.
* **Request latency:** Use an [HTTP probe](/resilience-testing/chaos-engineering/use-chaos-engineering/probes/http-probe.md) on a user-visible endpoint that exercises the method.
* **Thread-pool occupancy:** Use a Prometheus probe on `jvm_threads_state` or a custom thread-pool gauge.

***

### Verify the fault execution effect <a href="#verify-the-fault-execution-effect" id="verify-the-fault-execution-effect"></a>

1. **Trigger the method via a user-visible endpoint.**

   ```bash
   curl -w '%{time_total}\n' -o /dev/null -s https://<app>/<endpoint>
   ```

   Latency for the endpoint should rise by approximately `LATENCY` (per method call) during the chaos window.
2. **Inspect Byteman state.**

   ```bash
   sudo $JAVA_HOME/bin/bmtool -p <PORT> -l
   ```
3. **Inspect Linux Chaos Infrastructure logs.**

   ```bash
   sudo journalctl -u linux-chaos-infrastructure -n 100 --no-pager
   ```

***

### Recovery and cleanup <a href="#recovery-and-cleanup" id="recovery-and-cleanup"></a>

* **End of duration:** The chaos pod removes the Byteman rule when `DURATION` elapses.
* **Abort the experiment:** Stopping the experiment from Chaos Studio also removes the rule.
* **Manual recovery:** If the rule survives an abort, remove it with `sudo $JAVA_HOME/bin/bmtool -p <PORT> -u <rule>`.

***

### Limitations <a href="#limitations" id="limitations"></a>

* **Per-invocation delay:** `LATENCY` is added per invocation; methods called in tight loops will accumulate large delays.
* **Method visibility:** The target method must be defined on a loaded class; lazy-loaded classes are not affected until first use.
* **Overload resolution:** Byteman matches on method name; all overloads are delayed.
* **Byteman dependency:** The target JVM must allow Byteman attachment.
* **Single JVM scope:** Each fault run targets one Java process.

***

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>Linux JVM method latency fault did not slow the method in Harness Chaos Engineering</summary>

Confirm CLASS is the fully qualified name and that METHOD is defined on a loaded class. Trigger the method explicitly and measure the response time with curl. Verify Byteman attached with sudo bmtool -p -l.

</details>

<details>

<summary>Latency accumulated faster than expected</summary>

LATENCY is added per invocation. If the method is called many times per request, total request latency is approximately N x LATENCY. Reduce LATENCY or instrument the call site to see the actual invocation count.

</details>

<details>

<summary>Latency persisted after the experiment ended</summary>

If the Byteman rule was not removed, list with sudo bmtool -p -l and remove with -u . If the rule cannot be removed, restart the target JVM to clear injected rules.

</details>

***

### Related faults <a href="#related-faults" id="related-faults"></a>

* [Linux JVM method exception](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/linux-jvm-method-exception.md): Throw an exception from the method instead of delaying it.
* [Linux JVM modify return](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/linux-jvm-modify-return.md): Override the return value instead of delaying.
* [Linux network latency](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/linux-network-latency.md): Add latency at the network layer instead of inside the JVM.