docs: add Java CPU profiling configuration

Author: yinjiping

docs/zh/05-features/04-continuous-profiling/01-auto-profiling.md

@@ -57,7 +57,21 @@ permalink: /features/continuous-profiling/auto-profiling
   - 使用 JVM 虚拟机的语言：Java
   - 解释型语言：Python
 
-获取 Profiling 数据需满足两个前提条件：
+## Java CPU Profiling
+
+除通用的 eBPF On-CPU Profiling 外，DeepFlow 还支持通过 Java Agent 持续采集 JVM 方法调用栈。该功能使用 HotSpot 的 AsyncGetCallTrace（AGCT）获取 Java 栈并补全 JIT 方法符号，可用于定位 Java 方法的 CPU 热点。
+
+Java CPU Profiling 与 eBPF On-CPU Profiling 是两个相互独立的功能：
+
+- Java CPU Profiling 通过 JVM 内的 Java Agent 采集 Java 方法栈，使用 `java.profile.cpu` 选择进程；
+- eBPF On-CPU Profiling 通过内核 eBPF/perf 采集用户态和内核态调用栈，使用 `ebpf.profile.on_cpu` 选择进程；
+- 两者可以同时采集同一个 Java 进程，也可以只开启其中一个。若只需要清晰的 Java 方法栈，可以只开启 Java CPU Profiling，避免同时采集两份不同来源的数据。
+
+Java CPU Profiling 当前主要支持 HotSpot JVM。使用前需确保 Agent 与目标 JVM 位于同一台宿主机，并且 Agent 具备读取目标进程 `/proc/<pid>`、进入目标 Namespace、执行 Attach 和创建 Perf Event 所需的权限。该功能不要求目标 JVM 配置 `-XX:+PreserveFramePointer`；该参数仅用于通过 eBPF On-CPU Profiling 回溯 Java 进程调用栈。
+
+具体配置方法请参考[配置方法](./02-configuration.md#java-cpu-profiling)。
+
+通过通用 eBPF On-CPU/Off-CPU Profiling 获取调用栈时，需满足以下两个前提条件；Java CPU Profiling 不受这些条件限制：
 
 - 应用进程需要开启 Frame Pointer 或启用 Agent 的 DWARF 栈回溯能力
   - 应用进程开启 Frame Pointer（帧指针寄存器）：

docs/zh/05-features/04-continuous-profiling/02-configuration.md

@@ -44,6 +44,7 @@ inputs:
 - **only_in_container**: 是否仅匹配容器内的进程
 - **rewrite_name**: 重写进程名的规则，支持正则表达式捕获组引用
 - **enabled_features**: 为匹配的进程启用的功能列表:
+  - `java.profile.cpu`: 开启 Java CPU 剖析，需要配置 `inputs.java.profile.cpu.enabled: true`，不依赖 `ebpf.profile.on_cpu`
   - `ebpf.profile.on_cpu`: 开启 On-CPU 剖析，需要配置 `inputs.ebpf.profile.on_cpu.disabled: false`
   - `ebpf.profile.off_cpu`: 开启 Off-CPU 剖析，需要配置 `inputs.ebpf.profile.off_cpu.disabled: false`
   - `ebpf.profile.memory`: 开启内存剖析，需要配置 `inputs.ebpf.profile.memory.disabled: false`
@@ -62,7 +63,7 @@ inputs:
 
 ```yaml
 inputs:
-  ebpf:
+  proc:
     symbol_table:
       golang_specific:
         enabled: false
@@ -76,6 +77,47 @@ inputs:
 - **refresh_defer_duration**: Java 符号表的刷新延迟，避免高频刷新。
 - **max_symbol_file_size**: Java 符号表占用的最大空间大小，单位为 GB，避免占用过大的 `/tmp` 空间。
 
+# Java CPU Profiling
+
+Java CPU Profiling 通过 Java Agent 的 AsyncGetCallTrace（AGCT）持续采集 JVM 方法调用栈，并补全 Java JIT 方法符号。该功能独立于 eBPF On-CPU Profiling，必须同时满足以下两个条件才会采集目标进程：
+
+- 配置 `inputs.java.profile.cpu.enabled: true`，开启 Java CPU Profiler 基础能力；
+- `inputs.proc.process_matcher` 命中目标进程，并且 `enabled_features` 中包含 `java.profile.cpu`。
+
+推荐先按 JAR 包或完整命令行精确匹配少量业务进程，验证资源开销后再扩大范围。以下配置需要合并到现有采集器组配置中，请勿直接覆盖已有的 Process Matcher 和其他配置：
+
+```yaml
+inputs:
+  proc:
+    process_matcher:
+      - match_regex: '.*my-order-service\.jar.*'
+        match_type: cmdline_with_args
+        only_in_container: false
+        enabled_features:
+          - java.profile.cpu
+          - proc.gprocess_info
+  java:
+    profile:
+      cpu:
+        enabled: true
+        frequency: 99
+        max_depth: 98
+        sample_ring_size: 512
+        method_cache_size: 256
+```
+
+如果同一进程还需要普通 eBPF On-CPU Profiling，可在 `enabled_features` 中同时保留 `ebpf.profile.on_cpu`，并确保 `inputs.ebpf.profile.on_cpu.disabled: false`。两个功能使用独立的采样链路和进程名单，任何一个都不是另一个的前置条件。
+
+配置参数说明：
+
+- **enabled**：默认为 false。设置为 true 后，Agent 在启动时准备 Java CPU Profiler 基础能力；修改后需重启 Agent 生效。
+- **frequency**：采样频率，单位为 Hz，默认为 99，范围为 1～1000。资源敏感场景可从 49 开始；199 仅建议用于短时诊断，并应先进行压测。
+- **max_depth**：单条 Java 调用栈最多保留的栈帧数，默认为 98，范围为 1～128。增大该值可保留更深的调用路径，但会增加样本大小和处理开销。
+- **sample_ring_size**：每个 JVM 中的样本环形队列容量，默认为 512，范围为 64～8192。增大该值可以缓解突发采样或发送端短时背压造成的样本丢弃，但会增加 JVM 内存占用。
+- **method_cache_size**：每个 JVM 中的方法缓存容量，默认为 256，范围为 64～8192。方法数量较多、符号反复解析时可适当调大，但会增加 JVM 内存占用。
+
+`enabled` 和上述采样参数修改后需重启 Agent；Process Matcher 支持热更新，增删 `java.profile.cpu` 不需要重启目标 JVM。关闭采样不会卸载已经加载到 JVM 中的 Agent SO；如需彻底释放其占用的资源，需要在维护窗口重启目标 JVM。
+
 # eBPF On-CPU Profiling
 
 eBPF On-CPU Profiling 是默认开启的，但需要修改 `inputs.proc.process_matcher` 来指定进程列表。Agent 支持的配置参数如下：