如果还不熟悉 Tracing 的基本概念,可以先翻看前面一篇文章《Java 服务接入 OpenTracing(1)–从 Tracing 到 OpenTracing》。前文我们已经提到,OpenTracing API 只定义 Span 采集/上报过程的相关接口,而具体的采集实现/上报实现/聚合查询实现都是由具体的 Tracing 项目选择支持实现。所以本文以 Jaeger 为例子来描述如何让 Java 项目快速接入 Tracing 功能。
接入前准备
搭建 Collector 和 Querier
Jaeger 提供了一个 all-in-one 的镜像,非常方便于在开发环境使用,只要有 docker 环境,一行代码就可以运行起来。
docker run -d --name jaeger \
-e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \
-p 5775:5775/udp \
-p 6831:6831/udp \
-p 6832:6832/udp \
-p 5778:5778 \
-p 16686:16686 \
-p 14268:14268 \
-p 14250:14250 \
-p 9411:9411 \
jaegertracing/all-in-one:1.21
这个应用里面同时包含了 Collector 和 Querier 的功能。从 Jaeger 官方架构图的角度来开,这个 all-in-one 还包含了 jaeger-agent 功能。但是这个镜像虽然功能很全面,但是不适合在生产环境使用。一是因为这个镜像起来的服务,数据是存在内存的,无法持久化 trace 信息。二是在生产环境数据量是比较大的,在 Reporter 端到 Collector 端的数据传输还需要考虑流量的问题。所以如果是上生产环境,建议参考官方提供的机构,再根据实际情况做一些功能增减。
执行上述指令后系统下载包,并启动服务。执行 docker ps | grep jaeger
, 在 status 列看到 up xxx
说明启动成功
╰$ docker ps | grep jaeger
a4848198fca0 jaegertracing/all-in-one:1.21 "/go/bin/all-in-one-…" 2 minutes ago Up 2 minutes 0.0.0.0:5775->5775/udp, 0.0.0.0:5778->5778/tcp, 0.0.0.0:9411->9411/tcp, 0.0.0.0:14250->14250/tcp, 0.0.0.0:14268->14268/tcp, 0.0.0.0:6831-6832->6831-6832/udp, 0.0.0.0:16686->16686/tcp jaeger
这个时候,就可以通过 http://localhost:16686
访问 jaeger ui 了。但是此时,因为没有任务服务接入,所以 Service 还没有可选项目。
准备被织入 java 项目(如果已经有自己的项目jar包,可以直接跳过此步)
我们这里使用的是其官网提供的 demo 的 java 项目
项目地址: [opentracing-contrib/java-specialagent-demo]
git clone 项目,然后构建出演示 app 的 jar 包 (需要安装和配置好 git 和 maven3+ )
git clone https://github.com/opentracing-contrib/java-specialagent-demo
cd microdonuts
mvn package
# maven 执行日志...
等待 maven 执行完成后,会生成一个 target/
文件夹,里面会有一个 api-1.0-SNAPSHOT.jar
文件,这个 jar 就是我们要织入的目标项目
准备 java-specialagent 包
java-specialagent 是 OpenTracing 里面对 java 使用 javaagent 方式织入代码实现接入的开源项目,由于其接入没有代码入侵性,一次接入可以实现多开源项目的 Traicng 采点,因此成了最常用的 Instrument 项目。
项目地址: [opentracing-contrib/java-specialagent]
使用如下指令下载稳定包版本 1.7.4 到启动目录
# 在 java-specialagent-demo/microdonuts 目录下面执行
wget -O opentracing-specialagent-1.7.4.jar "https://repo1.maven.org/maven2/io/opentracing/contrib/specialagent/opentracing-specialagent/1.7.4/opentracing-specialagent-1.7.4.jar"
Java 项目织入 specialagent
java 项目织入 specialagent 非常简单只需要在 java 启动指令里面增加 javaagent 以及 Tracing 的一些启动参数。如下
# 在 java-specialagent-demo/microdonuts 目录下面执
java -cp ./target/api-1.0-SNAPSHOT.jar -javaagent:./opentracing-specialagent-1.7.4.jar -Dsa.exporter=jaeger -Dsa.log.level=FINE -DJAEGER_SERVICE_NAME=apiDemo -DJAEGER_SAMPLER_TYPE=probabilistic -DJAEGER_SAMPLER_PARAM=1 -DJAEGER_ENDPOINT="http://localhost:14268/api/traces" com.otsample.api.App
里面有一个参数 -javaagent:
。SpecialAgent 就是利用 java 1.5+ 支持的 javaagent 功能来实现非侵入式织入的。
另外还有不少的 -Dxxx
参数。这些参数 java 本身不使用,而是当作环境变量传给 SpeicalAgent 使用的。这些参数都可以在 SpecialAgent 的 Github 的 README 文件中找到。下面列举下上文使用参数
- sa.exporter: SpecialAgent 的 Tracer 选择参数,目前可选的 Tracer 有 jaeger, lightstep, wavefront, otel, or mock. 因为我们 Collector 和 Querier 用的是 jaeger 的。为了保持兼容性,则设置了 jaeger。根据我们选择了 jaeger 作为 Tracer, 则对应需要设置 Jaeger Tracer 的参数。 参考:Jaeger Configuration Envs
- JAEGER_SERVICE_NAME: 指定当前的服务名,对应的就是 jaeger-query ui 的 services
- JAEGER_SAMPLER_TYPE: 指定采样方法。一般我们使用百分比采样(probabilistic)。
- JAEGER_SAMPLER_PARAM:指定采样参数,如果采样方法选择了百分比,则这个参数就是具体百分比的值。该参数取值为 0.0-1.0。我们设置为1代表全采样。
- JAEGER_ENDPOINT: 值采集 Span 后的上报地址。如果选择了这个参数,则是直接通过