SkyWalking链路追踪使用教程三：支持的插件及插件开发必看

0 安装Java agent

• 7.x版本中代理支持 JDK 8 - 14， 6.x版本支持JDK 1.6 - JDK 12 NOTICE¹
• 在SkyWalking发行包中找到agent文件夹
• 配置config/agent.config中的agent.service_name。可以是任意的英文字符串。
• 配置config/agent.config中的collector.backend_service。默认指向127.0.0.1:11800，表示仅作用于本地后端。
• JVM参数中添加-javaagent:/path/to/skywalking-package/agent/skywalking-agent.jar，并且确保这个参数在-jar参数之前。

#可参考(SkyWalking链路监控使用教程一：windows下环境搭建并启动springboot应用 )

agent发行包包含在Apache官方发行版中。最新的agent包结构如下。

+-- agent
    +-- activations
         apm-toolkit-log4j-1.x-activation.jar
         apm-toolkit-log4j-2.x-activation.jar
         apm-toolkit-logback-1.x-activation.jar
         ...
    +-- config
         agent.config  
    +-- plugins
         apm-dubbo-plugin.jar
         apm-feign-default-http-9.x.jar
         apm-httpClient-4.x-plugin.jar
         .....
    +-- optional-plugins
         apm-gson-2.x-plugin.jar
         .....
    +-- bootstrap-plugins
         jdk-http-plugin.jar
         .....
    +-- logs
    skywalking-agent.jar

 

1 支持的中间件、框架和库

SkyWalking agent已经对多种中间件、框架和库进行了支持。 通过支持列表可以了解对哪些进行了支持以及支持了哪些版本。 如果插件被标注为可选²，请到可选的插件 章节去学习如何激活插件。

1.1 可选的插件

Java agent的所有插件都是可插拔的。在agent或第三方仓库的optional-plugins 文件夹下提供了可选的插件。 想要使用可选插件，你需要将对应插件移动到/plugins文件夹下。

• 追踪Spring注解的bean

这个插件可以实现对被@Bean, @Service, @Component and @Repository注解标注的bean的所有方法的追踪。

为什么这个插件是可选的？

追踪bean的所有方法会创建大量的span，这会导致耗费更多的CPU、内存和网络带宽。 当前如果你想追踪尽可能多的方法，请确保系统负载可以支撑更多的请求。

• 追踪Oracle和Resin

        由于Oracle和Resin许可的原因，没有在Apache发行包中提供这些插件。 如果你想了解细节，请阅读Apache许可法律文件

       由于许可的限制或不兼容，这些插件发布在第三方仓库中。可以到SkyAPM java插件扩展仓库获得这些插件。

• 通过指定endpoint模式来过滤trace

       

      文件中的配置说明。

配置	说明
class_name	要被增强的类
method	类的拦截器方法
operation_name	如果进行了配置，将用它替代默认的operation_name
operation_name_suffix	表示在operation_name后添加动态数据
static	方法是否为静态方法
tag	将在local span中添加一个tag。key的值需要在XML节点上表示。
log	将在local span中添加一个log。key的值需要在XML节点上表示。
arg[x]	表示输入的参数值。比如args[0]表示第一个参数。
.[x]	当正在被解析的对象是Array或List，你可以用这个表达式得到对应index上的对象。
.['key']	当正在被解析的对象是Map, 你可以用这个表达式得到map的key。

• Gson序列化库
• Lettuce 5.x(JRE1.8+)
• Zookeeper 3.4.x。 将此插件定为可选插件的原因在于：会生成大量的业务不相关的trace，对agent和后端产生了额外的负载。并且，这些trace数据可能仅仅是心跳数据。
• 自定义增强 基于描述文件对方法进行追踪，而不是通过写插件或修改源代码。

apm-customize-enhance-plugin为可选插件

#介绍
SkyWalking提供了Java agent插件开发指南帮助开发者们构建新的插件。

这个插件不是为替代某个插件而设计，而是为了用户使用方便。这个插件的行为跟@Trace toolkit(见SkyWalking使用教程二：自定义监控指定方法trace等高级特性 

https://blog.csdn.net/wabiaozia/article/details/115033431)很相似， 但是不需要对代码进行修改，而且功能更强大，比如提供了tag和log。

#如何配置
实现对类的自定义增强需要以下几步。

激活插件，将插件从optional-plugins/apm-customize-enhance-plugin.jar移动到plugin/apm-customize-enhance-plugin.jar。
在agent.config中配置plugin.customize.enhance_file，指明增强规则文件，比如/absolute/path/to/customize_enhance.xml。
在customize_enhance.xml中配置增强规则。



    
        
        
            arg[0]
            arg[1]
            arg[3].[0]
            arg[2].['k1']
            arg[4].[1]
            arg[4].[2]
        
        
        
            arg[0]
            arg[0]
            arg[1]
        
        
            arg[0].id
            arg[0].model1.name
            arg[0].model1.getId()
            arg[0].os.[1]
            arg[0].getM().['k1']
        
    
    
        
            arg[0]
            arg[1]
        
        
            arg[0].[0]
        
        
            arg[0].[0]
            arg[1]
        
    

• Spring Cloud Gateway 2.1.x 插件. 只有当你在 Spring Gateway 端安装了插件时才开启此插件.

1.2 Bootstrap 类插件

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

现在，我们有以下已知的 Bootstrap 插件.

• JDK HttpURLConnection 插件. Agent 兼容 JDK 1.6+
• JDK Callable and Runnable 插件. Agent 兼容 1.6+

 

2 高级特性

所有的插件都在/plugins文件夹下。当某个插件的jar包在此文件夹下，表示此插件已被激活；从这个文件夹下移除后，表示插件不可用.
默认的日志输出文件夹为/logs。

• 可通过设置系统属性覆盖配置文件中的配置。请见配置覆盖.
• 可使用gRPC TLS将后端连接起来。请见open TLS
• 通过不同的SkyWalking服务实现对大集群的监控。使用命名空间隔离上下文传播。
• 如果后端开启了token鉴权，客户端可设置token。
• 应用工具包。应用工具包，是Skywalking提供的一些库的集合。通过这些库，可以将你的应用同Skywalking agent联系起来。
  • 1 如果你想使用OpenTracing的Java API，可以试试兼容OpenTracing的Skywalking tracer. 更多细节可以查看http://opentracing.io
  • 2 如果你想在你的日志中打印trace上下文（比如traceId），选择你使用的日志框架log4j, log4j2, logback
  • 3 如果你想使用注解或者SkyWalking本地API读取trace上下文，试一下SkyWalking manual APIs吧。

SkyWalking manual APIs介绍

#@Trace @Tag
SkyWalking使用教程二：自定义监控指定方法trace等高级特性

#使用 TraceContext.putCorrelation() API将自定义数据放入跟踪上下文。
Optional previous = TraceContext.putCorrelation("customKey", "customValue");
当值为null或为空时，CorrelationContext将删除该项目。

#使用 TraceContext.getCorrelation() 获取自定义数据的API。
Optional value = TraceContext.getCorrelation("customKey");
可以在代理配置（https://skyapm.github.io/document-cn-translation-of-skywalking/zh/8.0.0/setup/service-agent/java-agent/#table-of-agent-configuration-properties）
文件中找到CorrelationContext配置描述，前缀为correlation.。

• • 4 如果你想通过手动的方式实现trace跨线程传递，可以使用跨线程传递API。

跨线程追踪介绍

#使用maven或gradle引入toolkit依赖。
   
      org.apache.skywalking
      apm-toolkit-trace
      ${skywalking.version}
   

#用法1
    @TraceCrossThread
    public static class MyCallable implements Callable {
        @Override
        public String call() throws Exception {
            return null;
        }
    }
...
    ExecutorService executorService = Executors.newFixedThreadPool(1);
    executorService.submit(new MyCallable());
#用法2
    ExecutorService executorService = Executors.newFixedThreadPool(1);
    executorService.submit(CallableWrapper.of(new Callable() {
        @Override public String call() throws Exception {
            return null;
        }
    }));
或者

    ExecutorService executorService = Executors.newFixedThreadPool(1);
    executorService.execute(RunnableWrapper.of(new Runnable() {
        @Override public void run() {
            //your code
        }
    }));
# 用法 3.
    @TraceCrossThread
    public class MySupplier implements Supplier {
        @Override
        public String get() {
            return null;
        }
    }
CompletableFuture.supplyAsync(new MySupplier());
或者

    CompletableFuture.supplyAsync(SupplierWrapper.of(()->{
            return "SupplierWrapper";
    })).thenAccept(System.out::println);

 

• 如果你想指定你的agent.config文件的路径，请见通过系统属性设置配置文件路径

 

3 Agent的可配置属性列表

agent/config/agent.config中支持的属性列表。

属性名	描述	默认值
agent.namespace	命名空间，用于隔离跨进程传播的header。如果进行了配置，header将为HeaderName:Namespace.	未设置
agent.service_name	在SkyWalking UI中展示的服务名。5.x版本对应Application，6.x版本对应Service。 建议：为每个服务设置个唯一的名字，服务的多个服务实例为同样的服务名	Your_ApplicationName
agent.sample_n_per_3_secs	负数或0表示不采样，默认不采样。SAMPLE_N_PER_3_SECS表示每3秒采样N条。	未设置
agent.authentication	鉴权是否开启取决于后端的配置，可查看application.yml的详细描述。对于大多数的场景，需要后端对鉴权进行扩展。目前仅实现了基本的鉴权功能。	未设置
agent.span_limit_per_segment	单个segment中的span的最大个数。通过这个配置项，Skywalking可评估应用程序内存使用量。	未设置
agent.ignore_suffix	如果这个集合中包含了第一个span的操作名，这个segment将会被忽略掉。	未设置
agent.is_open_debugging_class	如果为true，skywalking会将所有经Instrument转换过的类文件保存到/debugging文件夹下。Skywalking团队会要求你提供这些类文件以解决兼容性问题。	未设置
agent.cause_exception_depth	在记录异常信息的时候, 探针需要记录的堆栈深度.	5
agent.force_reconnection_period	grpc的强制重连周期，基于grpc_channel_check_interval.	1
agent.operation_name_threshold	设置操作名不建议超过最大长度(190).	150
agent.keep_tracing	如果该值为 true，即使后台不可用，也要保持跟踪.	false
osinfo.ipv4_list_size	限制ipv4列表的长度.	10
collector.grpc_channel_check_interval| 检查grpc的channel状态的时间间隔。|30`
collector.backend_service	接收skywalking trace数据的后端地址	127.0.0.1:11800
collector.heartbeat_period	探针心跳报告时间. 单位秒.	30
collector.grpc_upstream_timeout	grpc客户端向上游发送数据时超时多长时间. 单位秒.	30 秒
collector.get_profile_task_interval	嗅探器获取配置文件任务列表间隔.	20
logging.level	日志级别。默认为debug。	DEBUG
logging.file_name	日志文件名	skywalking-api.log
logging.output	日志输出. 默认是文件. 使用控制台意味着输出到标准输出.	FILE
logging.dir	日志目录。默认为空串，表示使用"system.out"输出日志。	""
logging.pattern	日志格式. 所有的转换说明符:   * %level means log level.   * %timestamp 表示现在的时间格式 yyyy-MM-dd HH:mm:ss:SSS.   * %thread 表示当前线程的名称.   * %msg 表示用户记录的某些消息.   * %class 表示TargetClass的SimpleName.   * %throwable 表示用户抛出的异常.   * %agent_name 表示 agent.service_name	%level %timestamp %thread %class : %msg %throwable
logging.max_file_size	日志文件的最大大小。当日志文件大小超过这个数，归档当前的日志文件，将日志写入到新文件。	300 * 1024 * 1024
logging.max_history_files	The max history log files. When rollover happened, if log files exceed this number,then the oldest file will be delete. Negative or zero means off, by default.	-1
jvm.buffer_size	收集JVM信息的buffer的大小。	60 * 10
buffer.channel_size	buffer的channel大小。	5
buffer.buffer_size	buffer的大小	300
profile.active	如果为true，SkyWalking代理将在用户创建新的配置文件任务时启用配置文件. 否则禁用概要.	true
profile.max_parallel	并行监控段计数	5
profile.duration	监控段最大时间(分钟)，如果当前监控段时间超出限制，则停止.	10
profile.dump_max_stack_depth	最大线程转储的堆栈深度	500
profile.snapshot_transport_buffer_size	快照传输到后端缓冲区的大小	50
plugin.mongodb.trace_param	如果为true，记录所有访问MongoDB的参数信息。默认为false，表示仅记录操作名，不记录参数信息。	false
plugin.elasticsearch.trace_dsl	如果为true，记录所有访问ElasticSearch的DSL信息。默认为false。	false
plugin.springmvc.use_qualified_name_as_endpoint_name	如果为true，endpoint的name为方法的全限定名，而不是请求的URL。默认为false。	false
plugin.toolit.use_qualified_name_as_operation_name	如果为true，operation的name为方法的全限定名，而不是给定的operation name。默认为false。	false
plugin.mysql.trace_sql_parameters	如果设置为 true, SQL 查询 (典型的是 java.sql.PreparedStatement) 的参数也会被采集.	false
plugin.mysql.sql_parameters_max_length	如果设置为正整数, 收集的 SQL 参数 db.sql.parameters 会被截断到这个长度, 否则会被完整保存, 这可能会导致性能问题.	512
plugin.solrj.trace_statement	如果为 true, 追踪 Solr 查询请求中的所有查询参数(包括 deleteByIds 和 deleteByQuery) 默认为 false.	false
plugin.solrj.trace_ops_params	如果为 true, 追踪 Solr 查询中所有操作参数, 默认为 false.	false
plugin.peer_max_length	Peer 描述最大限制.	200
plugin.mongodb.filter_length_limit	如果设置为正数, WriteRequest.params 将被截短到这个长度, 否则它将被完全保存，这可能会导致性能问题.	256
plugin.postgresql.trace_sql_parameters	如果设置为true，将收集sql的参数(通常是 java.sql.PreparedStatement).	false
plugin.postgresql.sql_parameters_max_length	如果设置为正数, db.sql.parameters 将被截断到这个长度，否则它将被完全保存，这可能会导致性能问题.	512
plugin.mariadb.trace_sql_parameters	如果设置为true，将收集sql的参数(通常是 java.sql.PreparedStatement).	false
plugin.mariadb.sql_parameters_max_length	如果设置为正数，db.sql 将被截断到这个长度，否则它将被完全保存，这可能会导致性能问题.	512
plugin.light4j.trace_handler_chain	如果为true，请跟踪属于请求的Light4J处理程序链的所有中间件/业务处理程序.	false
plugin.opgroup.*	支持在不同插件中自定义组规则的操作名. 请阅读 Group rule supported plugins	Not set
plugin.springtransaction.simplify_transaction_definition_name	如果为true，事务定义名称将被简化.	false
plugin.jdkthreading.threading_class_prefixes	线程类 (java.lang.Runnable and java.util.concurrent.Callable) 及其子类(包括任何名称匹配 THREADING_CLASS_PREFIXES (以 ， 分隔)的匿名内部类) 将被检测, 确保只指定短小的前缀，就像您预期要测试的一样, (java. 和 javax. 会因安全问题而被忽略)	Not set
plugin.tomcat.collect_http_params	这个配置项控制Tomcat插件是否应该收集请求的参数. 同样，在概要追踪中隐式激活.	false
plugin.springmvc.collect_http_params	这个配置项控制SpringMVC插件是否应该收集请求的参数, 当您的Spring应用程序基于Tomcat时, 只需要设置 plugin.tomcat.collect_http_params 或 plugin.springmvc.collect_http_params 之一. 同样，在概要追踪中隐式激活.	false
plugin.http.http_params_length_threshold	当启用 COLLECT_HTTP_PARAMS时，要保留多少字符并将其发送到OAP后端，请使用负值来保留和发送完整的参数. 添加这个配置项是为了提高性能.	1024
correlation.element_max_number	关联上下文的最大元素数.	3
correlation.value_max_length	关联上下文元素的最大值长度.	128

 

4 插件开发指南

SkyWalking java agent支持插件的开发以扩展支持列表。如果你想开发java agent插件，请阅读插件开发指南。

5 测试

如果你对插件的兼容性测试或agent的性能感兴趣，可以阅读下面的测试报告。

• Plugin Test
• Java Agent Performance Test

6 注意

¹ 由于自2018年以来gRPC不支持JDK 1.6, SkyWalking 在所有 7.x 版本都放弃支持 JDK 6/7. 但是，gRPC向前向后兼容(至少目前如此), 所有 SkyWalking 6.x agents 均可以与 7.x(包括agent 和 后台)协作.

转载标明链接：https://blog.csdn.net/wabiaozia/article/details/115038648

7 附

本文主要摘自 https://skyapm.github.io/document-cn-translation-of-skywalking/zh/8.0.0/setup/service-agent/java-agent/

主要进行了章节次序调整和部分章节内容的填充。