diff --git a/docs/sources/configure-client/grafana-agent/java/_index.md b/docs/sources/configure-client/grafana-agent/java/_index.md
index f1d5241a13..a0f48fc760 100644
--- a/docs/sources/configure-client/grafana-agent/java/_index.md
+++ b/docs/sources/configure-client/grafana-agent/java/_index.md
@@ -78,6 +78,27 @@ see [profiler-options](https://github.com/async-profiler/async-profiler?tab=read
 You must run the collector, either Grafana Alloy (recommended) or Agent (legacy), as root and inside host `pid` namespace for the `pyroscope.java`
 and `discover.process` components to work.
 
+### Additional configuration for Linux capabilities
+If your Kubernetes environment has Linux capabilities enabled, configure the following in the Helm values to ensure `pyroscope.java` functions properly:
+
+```yaml
+alloy:
+  securityContext:
+    runAsUser: 0
+    runAsNonRoot: false
+    capabilities:
+      add:
+        - PERFMON
+        - SYS_PTRACE
+        - SYS_RESOURCE
+        - SYS_ADMIN
+```
+These capabilities enable Alloy to access performance monitoring subsystems, trace processes, override resource limits, and perform necessary system administration tasks for profiling.
+
+{{< admonition type="note" >}}
+Adjust capabilities based on your specific security requirements and environment, following the principle of least privilege.
+{{< /admonition >}}
+
 ### Start the collector
 
 To start Grafana Alloy v1.2: Replace `configuration.alloy` with your configuration file name:
diff --git a/examples/grafana-agent-auto-instrumentation/java/README.md b/examples/grafana-agent-auto-instrumentation/java/README.md
index 604d8138da..9713ea0dd0 100644
--- a/examples/grafana-agent-auto-instrumentation/java/README.md
+++ b/examples/grafana-agent-auto-instrumentation/java/README.md
@@ -40,6 +40,27 @@ After the container is operational, the Grafana Agent profiles the Java applicat
 
 You need root privileges to run the Grafana Agent for profiling. The Agent must be executed within the host's PID namespace.
 
+## Additional Configuration for Linux Capabilities
+
+If your Kubernetes environment has Linux capabilities enabled, configure the following in your Helm values to ensure `pyroscope.java` functions properly:
+
+```yaml
+alloy:
+  securityContext:
+    runAsUser: 0
+    runAsNonRoot: false
+    capabilities:
+      add:
+        - PERFMON
+        - SYS_PTRACE
+        - SYS_RESOURCE
+        - SYS_ADMIN
+```
+These capabilities enable Alloy to access performance monitoring subsystems, trace processes, override resource limits, and perform necessary system administration tasks for profiling.
+{{< admonition type="note" >}}
+Adjust capabilities based on your specific security requirements and environment, following the principle of least privilege.
+{{< /admonition >}}
+
 ## Documentation
 
 Refer to the [official documentation](https://grafana.com/docs/pyroscope/latest/configure-client/grafana-agent/java/) for an in-depth understanding and additional configuration options for Java profiling with the Grafana Agent.