skywalking java agent集成
目录
概述
裸机集成
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 覆盖大多数通用场景埋点，有特殊需求的业务，可以通过应用代码自定义埋点实现更详细信息跟踪。
依赖引入：
依赖引入：
org.apache.skywalking
apm-toolkit-trace
8.7.0
org.apache.skywalking
apm-toolkit-logback-1.x
8.7.0
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文件
%d{yyyy-MM-dd HH:mm:ss.SSS} [%tid] [%thread] %-5level %logger{36} -%msg%n
说明：
元素[%tid] 在业务日志中植入skywalking traceId值 - 注意encoder、layout元素 class属性的值
下载以下logback-spring.xml日志配置文件作为参考：
附件 (1)上传文件
logback-spring.xml
${APP_LOG_PATTERN}
UTF-8
${LOG_HOME}/${PROJECT_NAME}.%d{yyyy-MM-dd}.%i.log
30
100MB
${APP_LOG_PATTERN}
UTF-8
${LOG_HOME}/${PROJECT_NAME}-error.%d{yyyy-MM-dd}.%i.log
30
100MB
ERROR
${APP_LOG_PATTERN}
UTF-8
查看应用日志文件，找到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/**