概述

裸机集成

docker集成

k8s集成

高级特性

Trace api

Logback traceId协同

跨线程trace

附录

Agent参数

本地缓存队列参数

是否显示Sql参数

其他参数

概述

java 应用skywalking集成主要以java agent形式接入。

官方详细文档点击skywalking-java集成查看。

java agent 环境限制 JDK 8 - 17。

注意！！！spring-gateway 不同版本间存在兼容问题，agent包中提供了2.0.x，2.1.x，3.x 几个版本插件。基于公司现状和业务稳定性考虑，agent包中默认只加载2.1.x的gateway版本，即spring-gateway版本在[2.1.x-3.x)之间的gateway监控支持，如果要支持其他版本，需特殊处理。

裸机集成

本地开发引入java agent，按以下3步集成

1.agent包下载地址：

点击skywalking-agent-8.8.1.tar下载

2.配置参数修改：

下载agent 包 config/agent.config修改配置参数(也可不改，通过后面启动参数方式覆盖)：

agent.service_name 监控应用名.

collector.backend_service skywalking oap server地址，默认 127.0.0.1:11800，测试环境 10.157.4.91:31590

3.启动agent参数设置：

应用启动java命令中添加 -javaagent:/path/to/skywalking-package/agent/skywalking-agent.jar 参数.

说明：第2步中的参数配置也可以通过jvm参数动态覆盖，格式：-Dskywalking.{具体参数名}

-javaagent:C:/workspace/tools/apache-skywalking-apm-bin-es7/agent/skywalking-agent.jar
-Dskywalking.agent.service_name=dev_adminApp
-Dskywalking.collector.backend_service=10.157.4.91:31590

更多agent参数配置请点击agent参数配置查看。

idea启动配置添加

应用启动完成，访问某个接口。刷新skywalking ui查看

Skywalking实现了大量中间件、通用组件插件，以下地址可参考详细列表

https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/supported-list/

docker集成

纯docker部署，主要应用客户现场部署(非k8s环境)，也需要集成skywalking的场景。

项目工程中Dockerfile文件加入以下指令片段

#FROM apache/skywalking-java-agent:8.7.0-alpine AS skywalking_agent_build
FROM harbor.sxftwork.com/arch_common_module/skywalking-java-agent:8.8.1-alpine AS skywalking_agent_build
FROM openjdk:8-jre-alpine
# 复制agent 到应用目录。
# 注意：/skywalking/agent/目录默认为root访问权限，若打docker镜像时为非root用户，请做相应调整。
# 如work用户，对应工作目录调整 COPY --chown=work:work --from=skywalking_agent_build /skywalking/agent/ /home/work/skywalking/agent/
#  agent参数调整 -javaagent:/home/work/skywalking/agent/skywalking-agent.jar
COPY --from=skywalking_agent_build /skywalking/agent/ /skywalking/agent/
# 对应pom.xml文件中的dockerfile-maven-plugin插件buildArgs配置项JAR_FILE的值
ARG JAR_FILE
WORKDIR /app
COPY ${JAR_FILE} app.jar
EXPOSE 8080
RUN echo "Asia/Shanghai" > /etc/timezone
ENTRYPOINT ["java","-javaagent:/skywalking/agent/skywalking-agent.jar","-jar","/app/app.jar"]

说明：

harbor.sxftwork.com/arch_common_module/skywalking-java-agent:8.8.1-alpine为skywalking agent定制化调整后的私有镜像
${JAR_FILE} 为应用打包后部署jar文件路径

docker启动

docker run  -p 8080:8080 \
 -e TZ="Asia/Shanghai" \
 -e SW_AGENT_NAME=appname \
 -e SW_AGENT_COLLECTOR_BACKEND_SERVICES="127.0.0.1:11800" \
 --name appname --restart always -d appimagename:v1.0.0

说明：SW_AGENT_NAME值替换为应用名，SW_AGENT_COLLECTOR_BACKEND_SERVICES值替换为oap server地址，测试环境oap地址：10.157.4.91:31590

注意环境变量取值为agent安装包/config目录agent.config文件中属性名对应的环境变量，而不是键值。

k8s集成

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: arch-skywalking-demo
    release: v1.0.0
  name: arch-skywalking-demo
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: arch-skywalking-demo
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: arch-skywalking-demo
        release: v1.0.0
    spec:
      restartPolicy: Always
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - podAffinityTerm:
                labelSelector:
                  matchLabels:
                    app: arch-skywalking-demo
                topologyKey: kubernetes.io/hostname
              weight: 1
      volumes:
        - name: skywalking-agent
          emptyDir: { }
      initContainers:
        - name: agent-container
          image: harbor.sxftwork.com/arch_common_module/skywalking-java-agent:8.8.1-alpine
          volumeMounts:
            - name: skywalking-agent
              mountPath: /agent
          command: [ "/bin/sh" ]
          args: [ "-c", "cp -R /skywalking/agent /agent/" ]
      containers:
        - env:
            - name: JAVA_TOOL_OPTIONS
              value: "-javaagent:/skywalking/agent/skywalking-agent.jar"
            - name: SW_AGENT_NAME
              value: "dev_arch-skywalking-demo"
            - name: SW_AGENT_COLLECTOR_BACKEND_SERVICES
              value: "10.157.4.91:31590"
          volumeMounts:
            - name: skywalking-agent
              mountPath: /skywalking
          image: 'harbor.sxftwork.com/arch_common_module/arch_skywalking_demo:v1.0.0'
          imagePullPolicy: IfNotPresent
          name: arch-skywalking-demo
          ports:
            - containerPort: 8080
              name: app
              protocol: TCP

说明：

应用yml文件Deployment对象，spec.template.spec元素添加图示35-56 配置。
initContainers步骤，初始化java skywalking agent到容器目录。JAVA_TOOL_OPTIONS参数动态注入agent到jvm。
调整环境变量对应值。
SW_AGENT_NAME：集成应用服务名，格式[环境前缀]_[应用名]。如用户系统，应用名user，开发环境SW_AGENT_NAME=dev_user,测试环境SW_AGENT_NAME=sit_user

SW_AGENT_COLLECTOR_BACKEND_SERVICES：埋点数据上报oap server地址，测试环境aop server地址(前置代理)10.157.4.91:31590

注意：

如果部署应用非root账户，k8s yaml文件需添加以下配置项，否则启动时会出现权限访问报错，因为skywalking agent 镜像默认以root作为操作账户。

#copy到yaml请手动删除对应注释
securityContext: # 与deployment对象，containers节点同级。
   fsGroup: 1000  # 文件卷操作用户。1000为启动应用的userid。不同环境做相应调整
   runAsGroup: 1000  # 以1000的userid用户组运行程序进程
   runAsNonRoot: true  # 非root账户启动应用
   runAsUser: 1000 # 以1000的userid用户运行程序进程

详细应用k8s配置可参考以下文件：

附件 (1)上传文件

arch-skywalking-demo.yml

---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: arch-skywalking-demo
    release: v1.0.0
  name: arch-skywalking-demo
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: arch-skywalking-demo
  strategy:
    rollingUpdate:
      maxSurge: 25%
      maxUnavailable: 25%
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: arch-skywalking-demo
        release: v1.0.0
    spec:
      restartPolicy: Always
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - podAffinityTerm:
                labelSelector:
                  matchLabels:
                    app: arch-skywalking-demo
                topologyKey: kubernetes.io/hostname
              weight: 1
      volumes:
        - name: skywalking-agent
          emptyDir: { }
      initContainers:
        - name: agent-container
          image: harbor.sxftwork.com/arch_common_module/skywalking-java-agent:8.8.1-alpine
          volumeMounts:
            - name: skywalking-agent
              mountPath: /agent
          command: [ "/bin/sh" ]
          args: [ "-c", "cp -R /skywalking/agent /agent/" ]
      containers:
        - env:
            - name: JAVA_TOOL_OPTIONS
              value: "-javaagent:/skywalking/agent/skywalking-agent.jar"
            - name: SW_AGENT_NAME
              value: "arch-skywalking-demo"
            - name: SW_AGENT_COLLECTOR_BACKEND_SERVICES
              value: "skywalking-oap:11800"
          image: 'harbor.sxftwork.com/arch_common_module/arch_skywalking_demo:v1.0.0'
          imagePullPolicy: IfNotPresent
          name: arch-skywalking-demo
          volumeMounts:
            - name: skywalking-agent
              mountPath: /skywalking
          ports:
            - containerPort: 8080
              name: app
              protocol: TCP
---
apiVersion: v1
kind: Service
metadata:
  name: arch-skywalking-demo
  namespace: default
  labels:
    app: arch-skywalking-demo
spec:
  selector:
    app: arch-skywalking-demo
  type: ClusterIP
  ports:
    - name: rest
      port: 8080
      protocol: TCP
      targetPort: 8080

高级特性

框架预置的agent 覆盖大多数通用场景埋点，有特殊需求的业务，可以通过应用代码自定义埋点实现更详细信息跟踪。

依赖引入：

依赖引入：
<dependency>
    <groupId>org.apache.skywalking</groupId>
    <artifactId>apm-toolkit-trace</artifactId>
    <version>8.7.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/org.apache.skywalking/apm-toolkit-logback-1.x -->
<dependency>
    <groupId>org.apache.skywalking</groupId>
    <artifactId>apm-toolkit-logback-1.x</artifactId>
    <version>8.7.0</version>
</dependency>

Trace api

代码埋点:

    /**
     * 方法上添加skywalking注解进行埋点
     * tag key值可随意定义，
     *     value值 arg[0]表示第一个入参值注入。returnedObj返回对象，若对象为pojo，通过.引用子属性。
     */
    @Trace
    @Tag(key = "param.url", value = "arg[0]")
    @Tag(key = "param.value", value = "arg[1]")
    @Tag(key = "return", value = "returnedObj")
//    @Tag(key = "username", value = "returnedObj.username")
//    @Tag(key = "age", value = "returnedObj.age")
    private String requestRemoteUrl(String url,String value){
        log.info("requestRemoteUrl log trace...");
        //业务代码中埋点
        //端点设置：不设置，默认类名+方法名+参数名。自定义值自动覆盖默认值。
//        ActiveSpan.setOperationName(String.format("requestRemoteUrl:url[%s],value[%s]",url,value));
        ActiveSpan.tag("biz_code_param_url", url);
        ActiveSpan.info("在代码中添加日志埋点...");
        ActiveSpan.info("--- skywalking traceId="+TraceContext.traceId());
        ActiveSpan.info("--- skywalking spanId="+TraceContext.spanId());
        ActiveSpan.info("--- skywalking segmentId="+TraceContext.segmentId());

        //业务逻辑实现。。。

        //跨线程异步测试,通过RunnableWrapper封装类处理
        ExecutorService executorService = Executors.newFixedThreadPool(1);
        executorService.submit(RunnableWrapper.of(new Runnable() {
            @Override
            @Trace
            public void run() {
                ActiveSpan.info("线程异步代码中添加日志埋点，线程名:"+Thread.currentThread().getName());
                ActiveSpan.info("--- skywalking traceId="+TraceContext.traceId());
                ActiveSpan.info("--- skywalking spanId="+TraceContext.spanId());
                ActiveSpan.info("--- skywalking segmentId="+TraceContext.segmentId());
            }
        }));


        return "invoke remote provider of nacos with response is : " + revStr;
    }

埋点效果：

Logback traceId协同

项目应用中使用logback日志框架，可以接入skywalking traceId集成。在日志log中会自动埋入请求traceId，调查线上问题时，通过traceId可以方便的在skywalking UI中搜索相关请求链路信息。

设置 %tid 到 logback.xml文件

<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
   <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
      <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.TraceIdPatternLogbackLayout">
          <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%tid] [%thread] %-5level %logger{36} -%msg%n</pattern>
      </layout>
   </encoder>
</appender>

说明：

<pattern>元素[%tid] 在业务日志中植入skywalking traceId值
注意encoder、layout元素 class属性的值

下载以下logback-spring.xml日志配置文件作为参考：

附件 (1)上传文件

logback-spring.xml

<configuration>
	<!--定义日志文件的存储地址 勿在 LogBack 的配置中使用相对路径-->
    <!--<property name="PROJECT_NAME" value="dctl-starter-demo"/>-->
    <springProperty scope="context" name="PROJECT_NAME" source="spring.application.name" />
    <property name="LOG_HOME"  value="/data/log/${PROJECT_NAME}"/>
<!--    <springProperty name="LOG_HOME" source="logging.path" />-->

    <!-- skywalking with the MDC, set %X{tid} in Pattern section of logback.xml-->
    <property name="APP_LOG_PATTERN"  value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%tid] [%thread] [${PROJECT_NAME:-}] %-5level %logger{50} - %msg%n"/>

    <!-- 控制台输出 -->
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.TraceIdPatternLogbackLayout">
                <pattern>${APP_LOG_PATTERN}</pattern>
            </layout>
            <!-- 记录日志的编码 -->
            <charset>UTF-8</charset> <!-- 此处设置字符集 -->
        </encoder>
    </appender>
    <!-- 按照每天生成日志文件   -->
    <appender name="dailyFile"  class="ch.qos.logback.core.rolling.RollingFileAppender">   
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <!-- 日志文件输出的文件名 -->
            <FileNamePattern>${LOG_HOME}/${PROJECT_NAME}.%d{yyyy-MM-dd}.%i.log</FileNamePattern>
            <MaxHistory>30</MaxHistory>
            <!-- 日志文件最大的大小 -->
            <MaxFileSize>100MB</MaxFileSize>
        </rollingPolicy>

        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.TraceIdPatternLogbackLayout">
                <pattern>${APP_LOG_PATTERN}</pattern>
            </layout>
            <!-- 记录日志的编码 -->
            <charset>UTF-8</charset> <!-- 此处设置字符集 -->
        </encoder>
    </appender>

    <appender name="errorFile"  class="ch.qos.logback.core.rolling.RollingFileAppender">
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <!-- 日志文件输出的文件名 -->
            <FileNamePattern>${LOG_HOME}/${PROJECT_NAME}-error.%d{yyyy-MM-dd}.%i.log</FileNamePattern>
            <MaxHistory>30</MaxHistory>
            <!-- 日志文件最大的大小 -->
            <MaxFileSize>100MB</MaxFileSize>
        </rollingPolicy>
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>ERROR</level>
        </filter>
        <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
            <layout class="org.apache.skywalking.apm.toolkit.log.logback.v1.x.TraceIdPatternLogbackLayout">
                <pattern>${APP_LOG_PATTERN}</pattern>
            </layout>
            <!-- 记录日志的编码 -->
            <charset>UTF-8</charset> <!-- 此处设置字符集 -->
        </encoder>
    </appender>

    <!-- 日志输出级别 -->
    <root level="info">
        <appender-ref ref="STDOUT" level="info"/>
        <appender-ref ref="dailyFile" />
        <appender-ref ref="errorFile" />
    </root>
    <!-- 指定项目中某个包，当有日志操作行为时的日志记录级别 -->
    <!-- com.tml为根包，也就是只要是发生在这个根包下面的所有日志操作行为的权限都是DEBUG -->
    <!-- 级别依次为【从高到低】：FATAL > ERROR > WARN > INFO > DEBUG > TRACE  -->
<!--    <logger name="com.mybatis" level="debug"/>-->
<!--    <logger name="java.sql" level="debug"/>-->
    <!--<logger name="com.dctl.ea.starter.demo.service" level="debug"/>-->
</configuration>

查看应用日志文件，找到traceId

Skywalking UI界面，通过traceId查找请求链路

跨线程trace

注意：程序逻辑有异步代码处理的，原有agent方式无法通过当前线程跟踪trace上下文，必须通过以下注解或者封装类方式特殊处理，才能保证整个调用链完整性。

注解实现

包装类实现

详细可参考官方文档：

https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/application-toolkit-trace/

附录

Agent参数

本地缓存队列参数

skywalking 本地缓存队列由缓存通道*通道队列构成

缓存通道

buffer.channel_size=${SW_BUFFER_CHANNEL_SIZE:5}
jvm和环境变量参数等价，选择其中之一

环境变量设置方式：SW_BUFFER_CHANNEL_SIZE=5，默认5个通道

jvm虚拟机参数设置方式：-Dskywalking.buffer.channel_size=5

缓存队列大小
buffer.buffer_size=${SW_BUFFER_BUFFER_SIZE:300}
jvm和环境变量参数等价，选择其中之一

环境变量设置方式：SW_BUFFER_BUFFER_SIZE=300，默认300长度

jvm虚拟机参数设置方式：-Dskywalking.buffer.buffer_size=300

是否显示Sql参数

plugin.jdbc.trace_sql_parameters=${SW_JDBC_TRACE_SQL_PARAMETERS:false}

jvm和环境变量参数等价，选择其中之一

环境变量设置方式：SW_JDBC_TRACE_SQL_PARAMETERS=true，默认false

jvm虚拟机参数设置方式：-Dskywalking.plugin.jdbc.trace_sql_parameters=true，默认false

其他参数

忽略请求后缀
agent.ignore_suffix=${SW_AGENT_IGNORE_SUFFIX:.jpg,.jpeg,.js,.css,.png,.bmp,.gif,.ico,.mp3,.mp4,.html,.svg}
jvm和环境变量参数等价，选择其中之一

环境变量设置方式：SW_AGENT_IGNORE_SUFFIX=.jpg,.jpeg,.js,.css,.png,.bmp,.gif,.ico,.mp3,.mp4,.html,.svg

jvm虚拟机参数设置方式：-Dskywalking.agent.ignore_suffix=.jpg,.jpeg,.js,.css,.png,.bmp,.gif,.ico,.mp3,.mp4,.html,.svg

忽略请求url
trace.ignore_path=/eureka/**,/consul/**
对应插件apm-trace-ignore-plugin。多个path以’,’分隔。
# ant path match style
# /path/? Match any single character
# /path/* Match any number of characters
# /path/** Match any number of characters and support multilevel directories
# Multiple path comma separation, like
jvm虚拟机参数设置方式: -Dskywalking.trace.ignore_path=/eureka/**,/consul/**