AcTrail 故障排查常见问题与解决方案完全手册 【免费下载链接】AcTrailAcTrail is a system-level observability system to capture the actual action trails for AI agents项目地址: https://gitcode.com/openeuler/AcTrail前往项目官网免费下载https://ar.openeuler.org/ar/AcTrail是一个强大的系统级可观测性工具用于捕获AI代理的实际行为轨迹。但在使用过程中您可能会遇到各种问题。本手册将为您提供完整的故障排查指南帮助您快速解决AcTrail部署和运行中的常见问题。快速诊断AcTrail系统检查清单 ✅在深入具体问题之前先运行以下命令进行快速系统检查# 1. 运行平台预检 python3 docs/preflight/platform_preflight.py --color always # 2. 检查构建状态 cargo build --release # 3. 验证eBPF支持 ./target/release/ebpf_probe verify-live --config docs/examples/03.extended-observation-e2e/observation.conf核心问题分类与解决方案 1. 启动失败Daemon无法启动症状actraild start命令失败显示权限错误或端口占用常见原因权限不足需要root或CAP_SYS_ADMIN端口或socket路径被占用配置文件路径错误解决方案# 检查权限 sudo id -u # 应该返回 0 # 检查socket路径占用 ls -la /run/actrail/ # 如果存在残留文件清理后重试 sudo rm -f /run/actrail/control.sock sudo rm -f /run/actrail/actraild.pid # 使用自定义路径启动 sudo ./target/release/actraild --config /path/to/your.conf start配置文件路径docs/examples/01.quick-start/README.md2. eBPF采集失败内核兼容性问题症状ebpf_probe verify-live失败或显示 kernel BTF is missing常见原因内核缺少BTF支持tracefs未挂载或不可写perf_event_open权限不足解决方案# 检查BTF支持 test -r /sys/kernel/btf/vmlinux echo BTF available || echo BTF missing # 检查tracefs grep -w tracefs /proc/self/mountinfo test -w /sys/kernel/tracing || test -w /sys/kernel/debug/tracing # 调整内核参数临时 sudo sysctl kernel.perf_event_paranoid-1 # 使用无eBPF模式 # 在配置文件中设置 ebpf_enabled false详细文档docs/platform-requirements.md3. TLS同步失败GLIBC版本不匹配症状actrailctl launch在容器中失败显示 GLIBC_2.39 not found常见原因主机编译的二进制文件与容器glibc版本不兼容TLS同步运行时库路径错误解决方案# 在容器内重新编译 docker exec -it container bash -c apt-get update apt-get install -y build-essential clang llvm libelf-dev zlib1g-dev pkg-config libssl-dev cd /path/to/AcTrail cargo build --release # 或者使用容器内编译的二进制文件 # 确保使用正确的libactrail_tls_payload_probe_sync.so路径配置示例docs/examples/container-agent-restricted/manual-test-walkthrough.md4. Seccomp降级容器权限限制症状actrailctl launch degraded: pidfd_getfd seccomp listener: Operation not permitted常见原因Docker默认seccomp配置文件阻止pidfd_getfd容器缺少必要的capabilities解决方案# 使用降级模式默认 actrailctl launch --name demo -- command # 会自动降级为tls-sync-only模式 # 或者放宽容器权限 docker run --security-opt seccompunconfined --cap-addSYS_ADMIN ... # 或者明确跳过seccomp actrailctl launch --seccomp-mode skip --name demo -- command相关配置在docs/examples/container-agent-restricted/operator.conf中设置process_seccomp_enabled false5. 存储空间不足Payload保留限制症状Payload采集失败显示 retention_max_bytes_per_trace exceeded常见原因单个trace的payload数据超过配置限制SQLite存储空间不足解决方案# 调整配置文件中的限制 [payload.tls] retention_max_bytes_per_trace 104857600 # 增加到100MB [payload.socket] retention_max_bytes_per_trace 52428800 # 50MB [payload.stdio] retention_max_bytes_per_trace 26214400 # 25MB6. Web界面无法访问端口绑定失败症状actrailweb启动失败显示 bind failed常见原因端口已被占用监听地址配置错误解决方案# 检查端口占用 sudo netstat -tlnp | grep :18080 # 使用不同端口启动 sudo ./target/release/actrailweb --config /etc/actrail/actraild.conf --addr 127.0.0.1 --port 18081 # 或者停止占用进程 sudo kill pid7. 语义动作缺失LLM调用未识别症状只有llm.response没有llm.request或llm.call常见原因TLS/HTTP捕获存在但语义分析失败请求未被完整投影解决方案# 检查payload捕获 sudo ./target/release/actrailviewer payloads --trace-id ID --head 40 # 检查事件 sudo ./target/release/actrailviewer events --trace-id ID --tail 80 # 验证配置是否包含语义分析 grep semantic_action /etc/actrail/actraild.conf诊断提示查看docs/examples/08.full-monitor-validation/README.md了解完整的语义验证流程8. 构建失败依赖项缺失症状cargo build --release失败常见原因缺少系统依赖包Rust工具链问题Java JDK版本不兼容解决方案# 安装系统依赖 # openEuler/Fedora/RHEL sudo dnf install -y clang llvm elfutils-devel zlib-devel pkgconf-pkg-config openssl-devel java-17-openjdk-devel # Debian/Ubuntu sudo apt-get install -y clang llvm libelf-dev zlib1g-dev pkg-config libssl-dev openjdk-17-jdk # 设置Java路径 export PATH/path/to/jdk-17/bin:$PATH # 跳过Java代理构建可选 ACTRAIL_SKIP_JAVA_AGENT_BUILD1 cargo build --release高级故障排查技巧 ️启用详细日志# 修改配置文件 diagnostic_log_level debug # 或者运行时指定 sudo ./target/release/actraild --config /etc/actrail/actraild.conf start --log-level debug使用预检脚本# 完整运行时验证 python3 docs/preflight/platform_preflight.py --run-smoke --color always # 检查特定功能 python3 docs/preflight/platform_preflight.py --check ebpf --color always python3 docs/preflight/platform_preflight.py --check tls-sync --color always python3 docs/preflight/platform_preflight.py --check fanotify --color always容器环境特殊处理在容器环境中特别注意glibc版本兼容性在容器内编译二进制文件内核功能限制可能需要--privileged或特定capabilities文件系统权限确保挂载点可写网络命名空间TLS同步需要Unix socket通信性能问题诊断# 启用工作负载诊断 workload_diagnostics_enabled true workload_diagnostics_interval_ms 1000 # 检查存储性能 sudo ./target/release/actrailviewer diagnostics --trace-id ID常见错误代码速查表 错误信息可能原因解决方案kernel BTF is missing内核未启用BTF升级内核或启用BTF编译选项tracefs mount is missingtracefs未挂载mount -t tracefs nodev /sys/kernel/tracingperf_event_open: Operation not permitted权限不足调整kernel.perf_event_paranoid或使用rootGLIBC_2.39 not foundglibc版本不匹配在容器内重新编译pidfd_getfd seccomp listener: Operation not permitted容器seccomp限制使用--seccomp-mode auto或skipsocket already in usesocket路径被占用清理残留文件或使用新路径retention_max_bytes_per_trace exceededpayload数据过多增加限制或减少采集范围最佳实践与预防措施 ️1. 环境准备检查清单在部署前确保内核版本 5.4推荐 5.10BTF支持已启用tracefs已挂载且可写系统依赖包已安装Rust工具链已更新Java JDK 17如需Java TLS捕获2. 配置验证# 验证配置文件 sudo ./target/release/actraild --config /path/to/config.conf init --dry-run # 检查daemon状态 sudo ./target/release/actraild status3. 逐步测试流程基础功能测试docs/examples/01.quick-start/TLS捕获测试docs/examples/02.llm-http-payload-capture/完整监控验证docs/examples/08.full-monitor-validation/容器环境测试docs/examples/container-agent-restricted/4. 监控与维护定期检查日志文件/var/log/actrail/actraild.log监控存储空间使用定期清理完成的trace更新配置以适应工作负载变化获取更多帮助 如果以上解决方案未能解决您的问题查看详细文档docs/usage.md - 日常命令参考docs/deployment.md - 部署指南docs/platform-requirements.md - 平台要求运行示例测试# 运行完整测试套件 python3 tests/regression/test_all.py检查测试用例tests/agent-trace/ - 真实代理测试tests/plugins/ - 插件测试tests/performance/ - 性能测试记住AcTrail采用fail-fast设计原则遇到问题时会明确报告错误而不是静默降级。仔细阅读错误信息通常是解决问题的关键核心关键词AcTrail故障排查、AI代理监控、系统级可观测性、eBPF采集问题、TLS同步失败、容器环境配置、权限问题解决、性能优化指南【免费下载链接】AcTrailAcTrail is a system-level observability system to capture the actual action trails for AI agents项目地址: https://gitcode.com/openeuler/AcTrail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考