重要

本文中含有需要您注意的重要提示信息，忽略该信息可能对您的业务造成影响，请务必仔细阅读。

通过SkyWalking为应用埋点并上报链路数据至可观测链路 OpenTelemetry 版后，可观测链路 OpenTelemetry 版即可开始监控应用，您可以查看应用拓扑、调用链路、异常事务、慢事务和SQL分析等一系列监控数据。本文介绍如何使用SkyWalking Java Agent进行自动埋点，以及SkyWalking Java Agent可配置属性的相关信息。

前提条件

• 打开SkyWalking下载页面，下载SkyWalking 6.X.X或以上版本（建议下载最新稳定版本），并将解压后的Agent文件夹放至Java进程有访问权限的目录。

• 插件均放置在/plugins目录中。在启动阶段将新的插件放进该目录，即可令插件生效。将插件从该目录删除，即可令其失效。另外，日志文件默认输出到/logs目录中。

警告

日志、插件和配置文件都在Agent文件夹中，请不要改变文件夹结构。

获取接入点信息

背景信息

SkyWalking是一款广受欢迎的国产APM（Application Performance Monitoring，应用性能监控）产品，主要针对微服务、Cloud Native和容器化（Docker、Kubernetes、Mesos）架构的应用。SkyWalking的核心是一个分布式追踪系统。

要通过SkyWalking将Java应用数据上报至可观测链路 OpenTelemetry 版控制台，首先需要完成埋点工作。SkyWalking既支持自动探针（Dubbo、gRPC、JDBC、OkHttp、Spring、Tomcat、Struts、Jedis等），也支持手动埋点（OpenTracing）。本文介绍自动埋点方法。

示例Demo

示例代码仓库地址：SkyWalking Demo

用SkyWalking为Java应用自动埋点

1. 打开config/agent.config，配置接入点和令牌。

   说明

   请将<endpoint>和<auth-token>分别替换成控制台集群配置 > 接入点信息页面上SkyWalking客户端在相应地域的接入点和鉴权令牌。关于获取方法，请参见前提条件。

   collector.backend_service=<endpoint>
   agent.authentication=<auth-token>

2. 采用以下方法之一配置应用名称（Service Name）。

   重要

   请将<ServiceName>替换为您的应用名称。如果同时采用以下两种方法，则仅第二种方法（在启动命令行中添加参数）生效。

   • 打开config/agent.config，配置应用名称。

     agent.service_name=<ServiceName>

   • 在应用程序的启动命令行中添加-Dskywalking.agent.service_name参数。

     java -javaagent:<skywalking-agent-path> -Dskywalking.agent.service_name=<ServiceName> -jar yourApp.jar

3. 根据应用的运行环境，选择相应的方法来指定SkyWalking Agent的路径。

   说明

   请将以下示例代码中的<skywalking-agent-path>替换为Agent文件夹中的skywalking-agent.jar的绝对路径。

   • Linux Tomcat 7 / Tomcat 8

     在tomcat/bin/catalina.sh第一行添加以下内容：

     CATALINA_OPTS="$CATALINA_OPTS -javaagent:<skywalking-agent-path>"; export CATALINA_OPTS

   • Windows Tomcat 7 / Tomcat 8

     在tomcat/bin/catalina.bat第一行添加以下内容：

     set "CATALINA_OPTS=-javaagent:<skywalking-agent-path>"

   • JAR File或Spring Boot

     在应用程序的启动命令行中添加-javaagent参数。

     重要

     -javaagent参数一定要在-jar参数之前。

     java -javaagent:<skywalking-agent-path> -jar yourApp.jar

   • Jetty

     在{JETTY_HOME}/start.ini配置文件中添加以下内容：

     --exec    # 去掉前面的井号取消注释。
     -javaagent:<skywalking-agent-path>

4. 重新启动应用。

Java Agent可配置属性

SkyWalking Java Agent支持丰富的用户可配置属性。完整的属性配置详情，请参见示例Demo的config/agent.config文件。

属性列表（部分）

以下属性以apache-skywalking-java-agent-8.16.0为准。

展开查看属性列表

配置方式

系统属性

使用-Dskywalking. + agent.config配置文件的key。例如：

# 通过系统属性配置agent.service_name
java -javaagent:/path/to/skywalking-agent.jar -Dskywalking.agent.service_name=<your_service_name> -jar your-project.jar

代理选项

在JVM参数中的代理路径之后添加属性即可。

# 模版
-javaagent:/path/to/skywalking-agent.jar=[key1]=[value1],[key2]=[value2]# 举例
java -javaagent:/path/to/skywalking-agent.jar=agent.service_name=<your-service-name>,agent.authentication=<your-token> -jar your-project.jar

系统环境变量

将属性配置成系统环境变量，skywalking-agent会自动获取。可以在config/agent.config文件中查询具体属性对应的系统环境变量，例如agent.service_name的系统环境变量为SW_AGENT_NAME。

agent.service_name=${SW_AGENT_NAME:default_name}# 配置环境变量
export SW_AGENT_NAME=<your_service_name>

优先级

以上配置方式的优先级从高到低依次为代理选项、系统属性、系统环境变量、配置文件。

Java Agent插件

SkyWalking Java Agent支持多种中间件、框架和库。支持的所有插件可在示例Demo的/plugins文件夹下查看。

激活插件

所有在/plugins文件夹下的插件都是已被激活的插件。若从/plugins中移除某个插件的jar包，则表示插件不可用。

官方已支持插件

官方支持的插件都已在/plugins文件夹下。

可选插件

Java Agent的插件支持可插拔。在Agent或第三方仓库的optional-plugins文件夹下提供了可选的插件。 想要使用可选插件，可以将对应插件移动到/plugins文件夹下。

Bootstrap类插件

由于意外风险，所有Bootstrap插件都是可选的。Bootstrap插件在bootstrap-plugins文件夹中。若需要使用这些插件，可以将目标插件的jar文件放入/plugins文件夹下。

支持插件列表

关于下面的插件，官方认为可能存在性能影响或者使用限制，所以只在第三方仓库发布。更多信息请参见SkyAPM Java插件扩展仓库。

展开查看插件列表

插件开发

您可以参考官方文档自定义开发一个SkyWalking Java Agent Plugin。

可观测链路 OpenTelemetry 版支持Trace上报，您可以参考官方文档开发一个自定义的Trace Plugin。

常见问题

问：SkyWalking正常连接服务端后，无法创建应用？

答：可能是由于链路追踪的数据未上报。您需要检查是否有链路追踪的数据上报，可以查看{skywalking agent path}/logs/skywalking-api.log内容。如果有数据上报，则显示如下图所示。

如果未产生数据上报，则可能原因是：开启采样、设置过滤或未触发生成链路追踪的请求。

相关文档

• SkyWalking官网

• 下载SkyWalking

• 部署SkyWalking Java Agent