
Arthas Spring Boot Starter 实战指南应用内嵌诊断、Tunnel 远程管理与非 Spring Boot 应用接入【免费下载链接】arthasAlibaba Java Diagnostic Tool Arthas/Alibaba Java诊断利器Arthas项目地址: https://gitcode.com/gh_mirrors/ar/arthas本文基于仓库 site/docs/en/doc/spring-boot-starter.md 编写并结合作者仓库源码进行纵深讲解。导读Arthas Spring Boot Starter 是 Arthas 为 Spring Boot 应用提供的零成本接入方案只要在 pom 中引入一个依赖应用启动时 Spring 就会自动拉起 Arthas 并 attach 到自身进程开箱即用地获得在线诊断能力。本文将以 starter 的引入、配置、Endpoint 监控为核心讲解如何在 Spring Boot 2/3 应用中内嵌 Arthas、通过 Tunnel Server 实现远程管理、加载外部命令并给出非 Spring Boot 应用使用ArthasAgent.attach()的等价方案。为什么需要 Arthas Spring Boot Starter传统使用 Arthas 的方式是下载 arthas 包后用as.sh或as.bat连接目标 Java 进程这对于本地开发、测试环境非常方便。但在生产集群、容器化部署或无法人工登录的场景下人工 attach 成本高、难自动化。Spring Boot Starter 则把 attach 动作完全自动化应用启动时Spring 容器初始化 Arthas并 attach 自身进程。这样应用一启动就处于可诊断状态配合 Arthas Properties 中的 Tunnel Server 配置还能把本地 Arthas 注册到远程管理端实现无人值守的远程诊断。::: tip Arthas 3.7.2 及以后版本同时支持 Spring Boot 2 和 Spring Boot 3。仓库源码 pom.xml 中的 profile 也印证了这一点JDK 8~16 时仅集成测试 Spring Boot 2 示例Spring Boot 3 示例的集成测试需要 JDK 17 及以上。 :::快速开始引入 Maven 依赖在 Spring Boot 应用的pom.xml中添加如下依赖dependency groupIdcom.taobao.arthas/groupId artifactIdarthas-spring-boot-starter/artifactId version${arthas.version}/version /dependency其中${arthas.version}需要替换为实际使用的版本号。引入后应用启动时 Spring 会启动 Arthas并 attach 自身进程无需任何额外代码。从源码看starter 本身只做了薄薄一层的 Spring 集成真正干活的组件都在它的依赖里arthas-agent-attach负责把 Arthas agent 挂载到当前 JVMarthas-packaging提供打包好的 arthas 运行资源如arthas-core.jar、arthas-bin.zip。同时starter 以provided/optional方式依赖spring-boot-starter-actuator和spring-boot-starter-web见 pom.xml即不强制你的应用引入 Web/Actuator 能力只有想通过 HTTP Endpoint 查看 Arthas 状态时才需要它们。工作原理从 Spring Bean 到 Arthas AgentStarter 的核心自动化逻辑集中在 ArthasConfiguration.java它通过 Spring Boot 的自动装配完成以下链路条件装配ConditionalOnProperty(name spring.arthas.enabled, matchIfMissing true)默认开启可通过spring.arthas.enabledfalse一键关闭。配置收集ConfigurationProperties(prefix arthas)将所有以arthas.*开头的配置项收集进arthasConfigMap。源码注释特别说明之所以用一个独立的 Map 而不是只依赖ArthasProperties是为了避免某些新版本才支持的配置项在ArthasProperties类里尚未定义。配置归一化StringUtils.removeDashKey()把-风格的配置键如agent-id转成驼峰如agentId详见 StringUtils.java。补全默认值ArthasProperties.updateArthasConfigMapDefaultValue()为未配置的disabledCommands注入默认值stop。注入应用名如果配置中没有appName自动取spring.application.name的值。启动 Agent给所有配置加上arthas.前缀后new ArthasAgent(mapWithPrefix, arthasProperties.getHome(), arthasProperties.isSlientInit(), null)然后调用arthasAgent.init()真正完成 attach。init()的底层实现在 ArthasAgent.java先通过Class.forName(java.arthas.SpyAPI)SpyAPI.isInited()判断 Arthas 是否已在运行避免重复 attach通过ByteBuddyAgent.install()获取当前 JVM 的Instrumentation若未显式指定arthasHome则从 classpath 解压arthas-bin.zip到临时目录加载arthas-core.jar中的com.taobao.arthas.core.server.ArthasBootstrap调用getInstance(inst, configMap)完成初始化检查isBind()端口绑定失败则记录错误信息slientInittrue时只记录错误不抛异常否则抛出IllegalStateException。配置属性详解官方示例通过 Tunnel Server 远程管理application.properties或application.yml中的核心配置示例如下arthas.agent-idhsehdfsfghhwertyfad arthas.tunnel-serverws://47.75.156.201:7777/ws arthas.command-locations/opt/arthas/ext-command.jar,/opt/arthas/ext-commands三个配置项分别解决三个问题配置项作用说明arthas.agent-id设置 agent 的唯一标识用于在 Tunnel Server 端唯一标识该应用实例arthas.tunnel-server指定 Tunnel Server 地址Arthas 启动后通过 WebSocket 连接到该服务端等待远程指令arthas.command-locations指定外部命令的加载路径可配置 jar 文件路径或目录路径多个用逗号分隔Spring Boot 的 relaxed binding 机制同时支持arthas.command-locations和arthas.commandLocations两种写法在 Spring Boot 配置文件中推荐使用arthas.command-locations-风格。全部受支持配置项来自源码Starter 支持的所有配置项完整定义在 ArthasProperties.javaConfigurationProperties(prefix arthas)意味着所有键都以arthas.开头配置键properties 风格字段驼峰类型说明arthas.ipipStringArthas 服务监听 IParthas.telnet-port/arthas.telnetPorttelnetPortintTelnet 端口默认 3658arthas.http-port/arthas.httpPorthttpPortintHTTP 端口默认 8563arthas.tunnel-server/arthas.tunnelServertunnelServerStringTunnel Server 地址arthas.agent-id/arthas.agentIdagentIdStringagent 唯一标识arthas.app-name/arthas.appNameappNameString应用名未配置时自动取spring.application.namearthas.stat-url/arthas.statUrlstatUrlString上报已执行命令的统计地址arthas.session-timeout/arthas.sessionTimeoutsessionTimeoutlong会话超时时间秒arthas.usernameusernameString认证用户名arthas.passwordpasswordString认证密码arthas.homehomeString指定 arthas 安装目录arthas.slient-init/arthas.slientInitslientInitbooleanagent 初始化出错时是否静默默认 false抛异常arthas.disabled-commands/arthas.disabledCommandsdisabledCommandsString禁用的命令列表默认stoparthas.command-locations/arthas.commandLocationscommandLocationsString外部命令加载路径端口与远程管理的细节参考 Arthas Properties 中的说明arthas.telnetPort配置为-1时不监听 telnet 端口arthas.httpPort同理配置为0时随机监听端口随机端口号会记录在~/logs/arthas/arthas.log中如果一台机器上部署多个应用怕端口冲突可以都配置为随机端口或-1然后统一通过 Tunnel Server 使用 Arthas——这正是上面arthas.tunnel-server示例的典型场景。默认禁用 stop 命令::: tip 默认情况下arthas-spring-boot-starter会禁用stop命令。 :::这一行为在源码中有明确实现ArthasProperties中DEFAULT_DISABLEDCOMMANDS stopArthasProperties.javaupdateArthasConfigMapDefaultValue()在用户未配置disabledCommands时写入该默认值。原因是starter 将 Arthas 内嵌在业务应用进程内若允许stop命令等于允许远程/在线把 Arthas 服务停掉从而失去诊断能力。如需调整可以显式配置arthas.disabled-commandsstop,dump关于disabledCommands与外部命令加载的完整说明可参考 Arthas Properties 中的 disable specify commands 与 Load external commands 两节。加载外部命令command-locationsarthas.command-locations用于在 Arthas 启动时加载自定义外部命令arthas.command-locations/opt/arthas/ext-command.jar,/opt/arthas/ext-commands关键约束来自 Arthas Properties每个条目可以是 jar 文件路径或目录路径多个条目用逗号分隔目录条目只扫描当前目录下的*.jar不会递归如果${arthas.home}/commands目录存在Arthas 启动时也会尝试加载其中的*.jar显式配置的commandLocations先加载默认目录后加载外部 jar 需要通过META-INF/services/com.taobao.arthas.core.shell.command.CommandResolver暴露CommandResolver实现Arthas 内置命令优先外部命令与内置命令同名时外部命令被跳过并写入日志。命令行方式等价配置--command-locations /opt/arthas/ext-command.jar,/opt/arthas/ext-commands。仓库还提供了完整的外部命令开发示例arthas-demo-external-command 模块包含DemoExternalCommand.java与DemoExternalCommandResolver.java以及对应的集成测试 arthas-external-command-integration-test详细开发流程参见 Load External Commands。通过 Actuator Endpoint 查看 Arthas 状态Starter 内置了一个 Actuator Endpoint 用于查看 Arthas 的配置与初始化状态。::: tip 使用该 Endpoint 需要应用引入并暴露 Actuator Endpoint。Spring Boot 中可通过management.endpoints.web.exposure.includearthas或*等配置暴露具体以 Spring Boot 官方 Production-ready Features 文档为准。 :::假定应用端口是 8080访问http://localhost:8080/actuator/arthas返回示例{ arthasConfigMap: { agent-id: hsehdfsfghhwertyfad, tunnel-server: ws://47.75.156.201:7777/ws, } }Endpoint 的实现位于 ArthasEndPoint.javaEndpoint(id arthas)定义 Endpoint idReadOperation的invoke()返回arthasConfigMap即实际注入给 Arthas 的配置以及初始化错误信息errorMessage当 agent 初始化失败时装配逻辑在 ArthasEndPointAutoConfiguration.java同样受spring.arthas.enabled开关控制并且仅当 Endpoint 被 Spring Boot 暴露时才创建ConditionalOnAvailableEndpoint。这个 Endpoint 的价值在于应用启动后即可通过 HTTP 确认 Arthas 是否成功挂载、配置是否按预期生效、以及失败时的错误原因非常适合接入监控探活或诊断系统的自检环节。非 Spring Boot 应用的使用方式如果你的应用不是 Spring Boot例如普通 Spring、Servlet、自研框架、甚至非 Spring 的 Java 应用无法使用 starter可以改用arthas-agent-attacharthas-packaging两个依赖在代码里显式调用ArthasAgent.attach()。Maven 依赖dependency groupIdcom.taobao.arthas/groupId artifactIdarthas-agent-attach/artifactId version${arthas.version}/version /dependency dependency groupIdcom.taobao.arthas/groupId artifactIdarthas-packaging/artifactId version${arthas.version}/version /dependency一行代码完成 attachimport com.taobao.arthas.agent.attach.ArthasAgent; public class ArthasAttachExample { public static void main(String[] args) { ArthasAgent.attach(); } }带配置的 attachHashMapString, String configMap new HashMapString, String(); configMap.put(arthas.appName, demo); configMap.put(arthas.tunnelServer, ws://127.0.0.1:7777/ws); ArthasAgent.attach(configMap);::: warning 非 Spring Boot 方式下配置键必须是驼峰风格如appName、tunnelServer这与 Spring Boot 的-风格不同。只有 Spring Boot 应用才同时支持驼峰和-两种风格——因为-到驼峰的转换StringUtils.removeDashKey是由 starter 完成的裸用ArthasAgent时没有这一步。 :::ArthasAgent还提供了其他静态方法attach(String arthasHome)可指定 Arthas 安装目录当 classpath 中没有arthas-bin.zip资源时例如以-javaagent之外的隔离类加载方式运行需要显式指定 arthas 目录详见 ArthasAgent.java。配置风格与优先级小结风格Spring Boot 应用推荐-风格arthas.tunnel-server也兼容驼峰非 Spring Boot 的ArthasAgent.attach(configMap)只能使用驼峰。优先级来自 Arthas Properties命令行参数 System Env System Properties arthas.properties若希望arthas.properties拥有最高优先级可配置arthas.config.overrideAlltrue。开关通过spring.arthas.enabledfalse可整体关闭 starter 的自动 attach 与 Endpoint 装配两个自动配置类都带有ConditionalOnProperty(name spring.arthas.enabled, matchIfMissing true)。参考文档Arthas Properties完整配置项、禁用命令、外部命令加载与配置优先级说明Load External Commands外部命令开发与加载完整示例核心源码ArthasProperties.java、ArthasConfiguration.java、ArthasEndPoint.java、ArthasAgent.java集成测试示例arthas-spring-boot-starter-exampleSpring Boot 2与 arthas-spring-boot3-starter-exampleSpring Boot 3【免费下载链接】arthasAlibaba Java Diagnostic Tool Arthas/Alibaba Java诊断利器Arthas项目地址: https://gitcode.com/gh_mirrors/ar/arthas创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考