docs: document -p mode namespace limitations for container/WSL environments

Author: swananan

docs/limitations.md

@@ -51,3 +51,9 @@ GhostScope scans `/proc/PID/maps` at startup to obtain loaded dynamic library in
 - **Shared-library targets (new processes)**: For processes that start after GhostScope, enable `--enable-sysmon-shared-lib` (or the matching config option) so globals can be resolved. This incurs extra system-wide work, so expect higher overhead on hosts with frequent process churn.
 
 > **Note**: The current sysmon pipeline still assumes the library is mapped when the exec event is handled; if a loader pulls it in much later, offsets are not retried yet.
+
+### 9. `-p <pid>` Mode inside Containers or WSL
+
+- The `-p` workflow filters events using `bpf_get_current_pid_tgid`, which returns the host kernel PID/ TGID. Inside PID namespaces (e.g., Docker, Kubernetes) or Windows Subsystem for Linux, the PID visible inside the container often differs from the host PID.
+- See [PID namespaces manual](https://www.man7.org/linux/man-pages/man7/pid_namespaces.7.html), [WSL issue #12408](https://github.com/microsoft/WSL/issues/12408), and [WSL issue #12115](https://github.com/microsoft/WSL/issues/12115) for details.
+- In these environments, either map the container/WSL PID to the host PID before using `-p`, or prefer `-t <binary>`/`-t <shared library>` where we attach uprobes by module path instead of PID.

docs/zh/limitations.md

@@ -53,3 +53,9 @@ GhostScope 启动时会扫描进程的 `/proc/PID/maps` 获取已加载的动态
 提示：`-p <pid>` 模式下仍会自动计算并下发模块偏移，全局变量始终可用。
 
 > **说明**：目前 sysmon 假设共享库在 exec 事件处理时已经映射；若动态加载发生得更晚，目前不会自动重试。
+
+### 9. 容器 / WSL 场景下 `-p <pid>` 模式的软限制
+
+- `-p` 模式依赖 `bpf_get_current_pid_tgid` 获取宿主机视角的 PID/TGID。处于 PID namespace（例如 Docker、Kubernetes 容器）或 WSL 中时，容器内部看到的 PID 往往与宿主机不一致。
+- 参考 [PID namespaces 手册](https://www.man7.org/linux/man-pages/man7/pid_namespaces.7.html)、[WSL issue #12408](https://github.com/microsoft/WSL/issues/12408) 和 [WSL issue #12115](https://github.com/microsoft/WSL/issues/12115)。
+- 在这些环境使用 `-p` 时，请先确认宿主机实际 PID；或改用 `-t <二进制>` / `-t <共享库>` 模式，通过模块路径挂载 uprobe，避免 PID 不匹配导致事件过滤失败。