docs java cpu profiling

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

@@ -11,6 +11,8 @@ permalink: /features/continuous-profiling/auto-profiling
 
 # 能力和限制
 
+## eBPF Profiling
+
 支持的 eBPF Profiling 数据类型：
 
 | 类型       | 支持语言/库       | 社区版  | 企业版  |
@@ -40,7 +42,6 @@ permalink: /features/continuous-profiling/auto-profiling
 | rdma      | C/C++ `*`        |        | ✔      |
 
 说明：
-
 - `*`: features in development
 - `**`: 运行 Java 程序的 JVM 须有符号表，参考[检查方法](#jvm-符号表检查)
 - `***`: 当前支持版本为 Python 3.10
@@ -57,7 +58,7 @@ permalink: /features/continuous-profiling/auto-profiling
   - 使用 JVM 虚拟机的语言：Java
   - 解释型语言：Python
 
-获取 Profiling 数据需满足两个前提条件：
+通过通用 eBPF On-CPU/Off-CPU Profiling 获取调用栈时，需满足以下两个前提条件：
 
 - 应用进程需要开启 Frame Pointer 或启用 Agent 的 DWARF 栈回溯能力
   - 应用进程开启 Frame Pointer（帧指针寄存器）：
@@ -76,6 +77,27 @@ Off-CPU Profiling 功能**仅会**采集如下调用栈：
 - 含有**至少一个**用户态函数的调用栈
 - 等待 CPU 的时间**不超过** 1 小时的调用栈
 
+## Java Profiling
+
+支持的 Java Profiling 数据类型：
+
+| 类型 | 支持语言/库 | 社区版 | 企业版 |
+| ---- | ----------- | ------ | ------ |
+| cpu  | Java        |        | ✔      |
+
+说明：
+- 类型：
+  - cpu：Java 方法在 CPU 上消耗的时间及函数调用栈
+- 语言：
+  - 使用 JVM 虚拟机的语言：Java
+- 采集原理：通过 Java Agent 持续采集 JVM 方法调用栈，使用 HotSpot 的 AsyncGetCallTrace（AGCT）获取 Java 栈并补全 JIT 方法符号，用于定位 Java 方法的 CPU 热点。
+- 与 eBPF On-CPU Profiling 的关系：
+  - Java CPU Profiling 通过 JVM 内的 Java Agent 采集 Java 方法栈，使用 `java.profile.cpu` 选择进程，不依赖 Frame Pointer 开启。
+  - eBPF On-CPU Profiling 通过内核 eBPF/perf 采集用户态和内核态调用栈，使用 `ebpf.profile.on_cpu` 选择进程。
+  - 两者相互独立，可以同时采集同一个 Java 进程，也可以只开启其中一个。若只需要清晰的 Java 方法栈，可以只开启 Java CPU Profiling，避免同时采集两份不同来源的数据。
+
+具体配置方法请参考[配置方法](./configuration/#java-cpu-profiling)。
+
 # 常见问题
 
 ## JVM 符号表检查

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
@@ -143,3 +144,42 @@ inputs:
   - 配置该选项可以参考采集器性能统计 `deepflow_agent_ebpf_memory_profiler` 中 `time_backtracked` 指标，增大该参数使之为 0 即可。注意可能需要相应增大 `sort_length` 参数。
 - **queue_size**：内存剖析组件内部的队列大小。
   - 配置该选项可以参考采集器性能统计 `deepflow_agent_ebpf_memory_profiler` 中 `overwritten` 和 `pending` 指标，增大该配置使得前者为 0，后者不高于该配置即可。
+
+# 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。