OpenTelemetry系列（五）｜ OpenTelemetry Java Instrumentation二次开发指南

深碍√TFBOYSˉ_ 2023-09-23 21:01 38阅读 0赞

## 前言 ##

我们上一章介绍了`OpenTelemetry Java Instrumentation`的使用，但是那些都是一些基本的使用，如果有一些自定义的功能，还是需要一些开发工作。本章节将以保姆级教程来介绍一下如何在`OpenTelemetry Java Instrumentation`上进行二次开发（本文中会将`OpenTelemetry Java Instrumentation`简写成`OJI`以方便阅读）。

> 本文中的相关源码以及相关的实现均为目前的OJI的最新main分支版本目前为1.22.0-SNAPSHOT

## 开发准备 ##

### 第一次编译 ###

`OJI`使用`gradle`来进行依赖管理，核心的依赖和仓库等等信息都包含在根目录下的`settings.gradle.kts`中，后续的相关维护也要在其中。并且`OJI`的开发需要jdk9+的版本，因此需要确认自己的jdk版本是否符合要求。

在确认好前期准备后进入项目，执行`gradle assemble`来进行打包操作。初次打包可能需要花费超过1个小时，需要耐心等待。除此之外如果遇到依赖拉取失败问题，则可以在`build.gradle.kts`文件中添加如下配置以使用其他的仓库地址，此处使用的是阿里云仓库：

allprojects {
      repositories {
        maven {
          setUrl("https://maven.aliyun.com/nexus/content/groups/public/")
        }
        mavenCentral()
        mavenLocal()
        jcenter {
          setUrl("https://jcenter.bintray.com/")
        }
        google()
      }
    }
    复制代码

经过一段时间等待，当控制台输出如下文字，即表示编译成功。

BUILD SUCCESSFUL in 12m 25s
    2464 actionable tasks: 2212 executed, 232 from cache, 20 up-to-date
    
    A build scan was not published as you have not authenticated with server 'ge.opentelemetry.io'.
    For more information, please see https://gradle.com/help/gradle-authenticating-with-gradle-enterprise.
    复制代码

之后我们就可以在`javaagent/build/libs`目录下找到最终的agent包`opentelemetry-javaagent-{version}.jar`

![format_png][]

### 新建组件 ###

为了便于管理，我们后续的所有功能示例都将包含在一个组件中，而不会进行多组件的分割。

在进行所有的开发之前我们需要新建一个组件：

1.  在`instrumentation`目录下新建一个目录作为组件的目录，我此处将其命名为`bjwzds`
2.  在此目录中新建`javaagent`目录，并在此目录下创建`build.gradle.kts`文件，文件内容如下：

plugins {
      id("otel.javaagent-instrumentation")
    }
    
    dependencies {
    
    }
    复制代码

1.  在全局的`settings.gradle.kts`中添加`hideFromDependabot(":instrumentation:bjwzds:javaagent")`或者是`include(":instrumentation:bjwzds:javaagent")`来引入我们新增的模块。
2.  开始在`javaagent`目录下构建我们的项目结构，大致如下：

![format_png 1][]

至此我们开发的准备工作已经完成，接下来就是愉快的coding环节了！

## 自定义Instrumentation ##

需要注意的是在早期版本中可以自己完全创建项目然后以外部插件的形式来注入，但是在后续版本中这种方式被废弃，因此后续的开发都是在clone下来的`OJI`项目中进行开发。

虽然`OJI`已经提供了非常多的`Instrumentation`类库，许许多多知名的开源项目都在其中，但是总是可能会有一些需要自己来处理的内容，比如一些商用库，比如一些公司自制的二方或者三方依赖。这些都不可能找到现成的实现，那么就只能自己来了！

`OJI`提供了完善的`Instrumentation`扩展能力，大家可以自行定义自己需要的`Instrumentation`。

### 简单例子 ###

要创建一个自定义的`Instrumentation`，最基础的是要先创建一个继承`InstrumentationModule`的类：

@AutoService(InstrumentationModule.class)
    public class BjwzdsInstrumentationModule extends InstrumentationModule {
      public BjwzdsInstrumentationModule() {
        // 此处定义的是组件的名称，以及组件的别名，会在配置组件的开关时使用
        super("bjwzds", "bjwzds-1.0");
      }
    
      @Override
      public List<TypeInstrumentation> typeInstrumentations() {
        // 组件内包含的TypeInstrumentation，是一个list
        return Collections.singletonList(new BjwzdsInstrumentation());
      }
    }
    复制代码

在有了`InstrumentationModule`的类后，只需要再创建一个`TypeInstrumentation`的实现类，我们的一个最简单的`Instrumentation`就已经完成了。如下是一个`TypeInstrumentation`的实现的例子：

public class BjwzdsInstrumentation implements TypeInstrumentation {
      @Override
      public ElementMatcher<TypeDescription> typeMatcher() {
        return named("org.example.bjwzds.AgentTest");
      }
    
      @Override
      public void transform(TypeTransformer transformer) {
        transformer.applyAdviceToMethod(
            isMethod()
                .and(isPublic())
                .and(named("test")),
            this.getClass().getName() + "$BjwzdsAdvice");
      }
    
      @SuppressWarnings("unused")
      public static class BjwzdsAdvice {
    
        @Advice.OnMethodEnter(suppress = Throwable.class)
        public static void methodEnter() {
          System.out.println("enter method");
        }
    
        @Advice.OnMethodExit(suppress = Throwable.class)
        public static void methodExit() {
          System.out.println("exit method");
        }
      }
    }
    复制代码

这个例子很简单，作用是在`org.example.bjwzds.AgentTest.test`方法的执行前和执行后分别输出日志。

1.  在`typeMatcher`中定义的事需要进行切面的类，这个例子中指定了名称，全限定名叫做`org.example.bjwzds.AgentTest`
2.  在`transform`中定义切面的方法，以及方法绑定的执行类。在这个例子中切面的方法为是`public`方法且名字是`test`的方法，绑定的类是当前类的内部类`BjwzdsAdvice`
3.  绑定的执行类`BjwzdsAdvice`定义了`@Advice.OnMethodEnter`和`@Advice.OnMethodExit`这两个注解分别用来定义进入方法和离开方法。因此这个类会在进入方法时执行`System.out.println("enter method");`并在离开时执行`System.out.println("exit method");`

我们将修改完的代码编译生成新的agent，然后在我们的demo项目中进行测试。

DEMO项目很简单，只有一个类文件：

package org.example.bjwzds;
    
    public class AgentTest {
        public void test() {
            System.out.println("This is a test function");
        }
    
        public static void main(String[] args) {
            AgentTest agentTest = new AgentTest();
    
            agentTest.test();
        }
    }
    复制代码

我们先不引入agent执行这个类，输出：

![format_png 2][]

然后我们引入Agent，再执行，输出：

![format_png 3][]

我们明显可以看到我们的Agent已经生效了，并且如我们设计的一样，在`test`执行前后分别输出了日志。

### 扩展能力 ###

上面的例子是一个简单的`Instrumentation`例子，但是实际上在具体的使用中仅仅如此是不够的，接下来我们来介绍一些`Instrumentation`更广阔的能力。

接下来为了让大家更加了解`Instrumentation`的实现，我们来一起实现一个真正的调用链的`Instrumentation`样例。

首先需要说明的是调用链组件的实现形式和我们上述的例子并无二致，两者间的差距是绑定的执行方法中逻辑的区别。在正式开始前我们先来看一个`java-http-client`插件的例子：

@Advice.OnMethodEnter(suppress = Throwable.class)
        public static void methodEnter(
            @Advice.Argument(value = 0) HttpRequest httpRequest,
            @Advice.Local("otelContext") Context context,
            @Advice.Local("otelScope") Scope scope) {
          Context parentContext = currentContext();
          if (!instrumenter().shouldStart(parentContext, httpRequest)) {
            return;
          }
    
          context = instrumenter().start(parentContext, httpRequest);
          scope = context.makeCurrent();
        }
    
        @Advice.OnMethodExit(onThrowable = Throwable.class, suppress = Throwable.class)
        public static void methodExit(
            @Advice.Argument(0) HttpRequest httpRequest,
            @Advice.Return HttpResponse<?> httpResponse,
            @Advice.Thrown Throwable throwable,
            @Advice.Local("otelContext") Context context,
            @Advice.Local("otelScope") Scope scope) {
          if (scope == null) {
            return;
          }
    
          scope.close();
          instrumenter().end(context, httpRequest, httpResponse, throwable);
        }
    复制代码

这是一个典型的调用链插件的实现逻辑，代码中的`shouldStart`，`start`，`end`都是`OJI`提供的API，用来帮助生成`Trace`，`Span`，以及处理一些必要的逻辑。上述代码中的`instrumenter()`是自己实现的代码，但是其也不过是调用API来构建一个特定类型的`Instrumenter`。

按照上面的说法，那我们岂不是只要CtrlC，CtrlV就能够简单的创建一个调用链组件了呢？

答案是“是，也不完全是”。大致的逻辑上各个组件并无二致，甚至如果是同样类型的组件，如`apache-httpclient`和`okhttp`这种，那么绝大部分的代码都能够复用，但是这里有一个巨大的区别。

在之前的文章中我们曾经提到过调用链想要串联在一起需要将`TraceId`一级一级的透传下去，但是不同的组件透传的方式是不一样的，是的，这个区别就是每个组件需要根据自己的特点来实现`TraceId`的透传。

听上去似乎很复杂，但是好在`OpenTelemetry`在这方面也做好了准备，它将这个过程进行了抽象并提供了`TextMapSetter`和`TextMapGetter`接口来让我们自己实现。大致流程如下：

![format_png 4][]

也就是说实际上我们需要处理的是上下游传递数据的方式，以及如何进行数据的解析组装。

下面是一个简单实现的`OpenFeign`的调用链组件（其实feign的组件在社区在就有人提出，但是历经多个版本pr仍未被合并，这里的组件是我自己实现的一个极其简易版本，仅用于demo展示）：

`FeignInstrumentation`:

public class FeignInstrumentation implements TypeInstrumentation {
      @Override
      public ElementMatcher<TypeDescription> typeMatcher() {
        return named("feign.SynchronousMethodHandler");
      }
    
      @Override
      public void transform(TypeTransformer transformer) {
        transformer.applyAdviceToMethod(
            named("executeAndDecode"), this.getClass().getName() + "$RequestAdvice");
      }
    
      @SuppressWarnings("unused")
      public static class RequestAdvice {
    
        @Advice.OnMethodEnter(suppress = Throwable.class)
        public static void addRequestEnter(
            @Advice.Argument(0) RequestTemplate template,
            @Advice.Local("otelContext") Context context,
            @Advice.Local("otelScope") Scope scope) {
          Context parentContext = Java8BytecodeBridge.currentContext();
    
          if (!instrumenter().shouldStart(parentContext, template)) {
            return;
          }
    
          context = instrumenter().start(parentContext, template);
          scope = context.makeCurrent();
        }
    
        @Advice.OnMethodExit(onThrowable = Throwable.class, suppress = Throwable.class)
        public static void addRequestExit(
            @Advice.Argument(0) RequestTemplate template,
            @Advice.Thrown Throwable exception,
            @Advice.Local("otelContext") Context context,
            @Advice.Local("otelScope") Scope scope) {
          if (scope == null) {
            return;
          }
    
          scope.close();
    
          instrumenter().end(context, template, null, exception);
        }
      }
    }
    复制代码

`FeignSingleton`核心实例构建类，将设定好的配置类组合在一起生成`Instrumenter`实例:

public class FeignSingleton {
      private static final String INSTRUMENTATION_NAME = "io.opentelemetry.feign-1.0";
      private static final Instrumenter<RequestTemplate, Void> INSTRUMENTER;
    
      static {
        HttpClientAttributesGetter<RequestTemplate, Void> httpAttributesGetter =
            new FeignHttpAttributesGetter();
    
        NetClientAttributesGetter<RequestTemplate, Void> netAttributesGetter =
            new FeignNetAttributesGetter();
    
        INSTRUMENTER =
            Instrumenter.<RequestTemplate, Void>builder(
                    GlobalOpenTelemetry.get(),
                    INSTRUMENTATION_NAME,
                    HttpSpanNameExtractor.create(httpAttributesGetter))
                .addAttributesExtractor(
                    HttpClientAttributesExtractor.builder(httpAttributesGetter, netAttributesGetter).build())
                .buildClientInstrumenter(HttpHeaderSetter.INSTANCE);
      }
    
      public static Instrumenter<RequestTemplate, Void> instrumenter() {
        return INSTRUMENTER;
      }
    
      private FeignSingleton() {}
    }
    复制代码

`HttpHeaderSetter`，负责将内存中的数据转换并存储到发往下游请求的请求头:

enum HttpHeaderSetter implements TextMapSetter<RequestTemplate> {
      INSTANCE;
    
      @Override
      public void set(@Nullable RequestTemplate carrier, String key, String value) {
        if (carrier == null) {
          return;
        }
        carrier.header(key, value);
      }
    }
    复制代码

`FeignHttpAttributesGetter`，span中的http部分数据采集:

public class FeignHttpAttributesGetter implements HttpClientAttributesGetter<RequestTemplate, Void> {
      @Nullable
      @Override
      public String url(RequestTemplate requestTemplate) {
        return requestTemplate.url();
      }
    
      @Nullable
      @Override
      public String flavor(RequestTemplate requestTemplate, @Nullable Void unused) {
        return "feign";
      }
    
      @Nullable
      @Override
      public String method(RequestTemplate requestTemplate) {
        return requestTemplate.method();
      }
    
      @Override
      public List<String> requestHeader(RequestTemplate requestTemplate, String name) {
        return new ArrayList<>();
      }
    
      @Nullable
      @Override
      public Integer statusCode(RequestTemplate requestTemplate, Void unused,
          @Nullable Throwable error) {
        return 200;
      }
    
      @Override
      public List<String> responseHeader(RequestTemplate requestTemplate, Void unused, String name) {
        return new ArrayList<>();
      }
    }
    复制代码

`FeignNetAttributesGetter`，span中的net部分数据采集:

public class FeignNetAttributesGetter implements NetClientAttributesGetter<RequestTemplate, Void> {
      @Nullable
      @Override
      public String transport(RequestTemplate requestTemplate, @Nullable Void unused) {
        return "transport";
      }
    
      @Nullable
      @Override
      public String peerName(RequestTemplate requestTemplate) {
        return "peerName";
      }
    
      @Nullable
      @Override
      public Integer peerPort(RequestTemplate requestTemplate) {
        return 10000;
      }
    }
    复制代码

**效果展示**：

![format_png 5][]

![format_png 6][]

至此，我们就简单的实现了一个可用的调用链插件，实际上纵观整体源码中自带的的插件也不过是这个例子的完善版本，基本原理都是万变不离其宗。

## 其他的自定义扩展能力 ##

在`OJI`中除了用户可以自定义调用链的组件，同样的用户也可以自定义一些其他的扩展插件能力，在这个篇章会介绍一些比较可能用到的扩展能力。

### 自定义配置 ###

`AutoConfigurationCustomizerProvider`是用来自定义用户需要注入的配置的接口。

一个简单的例子：

@AutoService(AutoConfigurationCustomizerProvider.class)
    public class MineAutoConfigurationCustomizerProvider implements
        AutoConfigurationCustomizerProvider {
    
      @Override
      public void customize(AutoConfigurationCustomizer autoConfigurationCustomizer) {
        autoConfigurationCustomizer
            .addPropertiesSupplier(this::getDefaultProperties);
      }
    
      private Map<String, String> getDefaultProperties() {
        Map<String, String> properties = new HashMap<>();
        properties.put("otel.exporter.otlp.endpoint", "http://backend:8080");
        properties.put("otel.exporter.otlp.insecure", "true");
        properties.put("otel.config.max.attrs", "16");
        properties.put("otel.traces.sampler", "demo");
        return properties;
      }
    }
    复制代码

在上面的例子中在启动之时添加了自定义的一些配置。接口的暴露的方法是`customize`，其参数是`AutoConfigurationCustomizer`，在`AutoConfigurationCustomizer`中提供了一系列的方法来帮助用户自定义想要的配置内容：

![format_png 7][]

### 自定义调用链ID生成规则 ###

在默认的SDK实现中`OpenTelemetry`使用的是默认的`RandomIdGenerator`来生成`traceId`和`spanId`，但是在真实的使用场景中往往需要自定义自己的规则来制定独特的`traceId`和`spanId`，这个时候就需要使用到`IdGenerator`了。

简单实现接口`IdGenerator`就能够自定义Id生成规则：

public class MineIdGenerator implements IdGenerator {
      @Override
      public String generateSpanId() {
        return String.valueOf(System.currentTimeMillis());
      }
    
      @Override
      public String generateTraceId() {
        return String.valueOf(System.currentTimeMillis());
      }
    }
    复制代码

之后在`AutoConfigurationCustomizer`中以如下方式将自己定义的`IdGenerator`加入进去即可生效：

@Override
      public void customize(AutoConfigurationCustomizer autoConfigurationCustomizer) {
        autoConfigurationCustomizer
            .addTracerProviderCustomizer(this::configureSdkTracerProvider);
      }
    
      private SdkTracerProviderBuilder configureSdkTracerProvider(
          SdkTracerProviderBuilder tracerProvider, ConfigProperties configProperties) {
        return tracerProvider
            .setIdGenerator(new MineIdGenerator());
      }
    复制代码

### 自定义透传 ###

在上文中我们提到过调用链的一个核心是调用链数据的透传，透传就需要借助到`Propagator`机制，在`OJI`中默认使用的是两个`Propagator`：`Traceparent`和`Baggage`。

`Traceparent`用于调用链的traceId等调用链基础数据的传递 `Baggage`可以用于自定义的请求头的传递，以固定的请求头"baggage"，其中他的指格式为K-V结构

按照道理来说这两个`Propagator`基本也已经够用了，但是在一些场景，如全链路灰度，全链路压测时，往往需要使用自己独有的标识，那么一个自定义的传递标识（请求头）就很有必要了。

想要创建自己的`Propagator`，那么就需要先实现接口`ConfigurablePropagatorProvider`：

@AutoService(ConfigurablePropagatorProvider.class)
    public class ColorConfigurablePropagatorProvider implements ConfigurablePropagatorProvider {
      @Override
      public TextMapPropagator getPropagator(ConfigProperties config) {
        return new ColorPropagator();
      }
    
      @Override
      public String getName() {
        return "color";
      }
    }
    复制代码

在这个接口中定义了`Propagator`的名称与实现。

接下来就是实现类，实现类需要实现`TextMapPropagator`接口，如下：

public class ColorPropagator implements TextMapPropagator {
      private static final String FIELD = "color";
      private static final ContextKey<String> PROPAGATION_KEY =
          ContextKey.named("propagation.color");
    
      @Override
      public Collection<String> fields() {
        return Collections.singletonList(FIELD);
      }
    
      @Override
      public <C> void inject(Context context, @Nullable C carrier, TextMapSetter<C> setter) {
        String v = context.get(PROPAGATION_KEY);
    
        if (v != null) {
          setter.set(carrier, FIELD, v);
        }
      }
    
      @Override
      public <C> Context extract(Context context, @Nullable C carrier, TextMapGetter<C> getter) {
        String v = getter.get(carrier, FIELD);
        if (v != null) {
          return context.with(PROPAGATION_KEY, v);
        } else {
          return context;
        }
      }
    }
    复制代码

上面实现了一个最简单的`Propagator`，这个`Propagator`的名称是`color`，传播时的header关键字也是`color`，他只做了一件事，就是接收数据时将数据从header中取出存放入内存中，`ContextKey`为`"propagation.color"`，而数据发出时就从内存中取出数据放入header之中。因此上述的实现流程以最简单的形式构建了一个支持透传的`Propagator`。

### 其他 ###

其实`OJI`还支持其他种类的扩展，但是由于篇幅有限，以及一些扩展方式并不是很常用，因此略过。如果感兴趣可以在此处[extensions][]找到官方的更多文档。

## 总结 ##

这篇讲述`OJI`的二次开发的一些方式并列出了代码，我自认为全网应该不会有比这篇更加详细的文章来讲述这方面的内容。（这都是踩了无数的坑总结出来的！）

至此`OpenTelemetry`系列的文章暂时就告一段落了，但是这不代表后续相关的内容就完全结束了。其中包含整体观测体系的架构，调用链的存储方式，metrics的处理都是可以展开细谈的。所以后续我可能会视情况更新一些相关的文章，但是不会再放在这个系列中了，敬请期待。

作者：骑牛上青山  
原文链接：https://juejin.cn/post/7183580820026687525

[format_png]: https://img-blog.csdnimg.cn/img_convert/339427e1ae96baa9032e1aac3063cce2.webp?x-oss-process=image/format,png
[format_png 1]: https://img-blog.csdnimg.cn/img_convert/6155af3a5f468a66228173d941b3a23d.webp?x-oss-process=image/format,png
[format_png 2]: https://img-blog.csdnimg.cn/img_convert/ae4566a880a94013cf39484b919a4bfc.webp?x-oss-process=image/format,png
[format_png 3]: https://img-blog.csdnimg.cn/img_convert/771512ed7bf2cac88dd3cca60b3ac4cf.webp?x-oss-process=image/format,png
[format_png 4]: https://img-blog.csdnimg.cn/img_convert/594dffa1419c39a2e4d4bb29cfb4a1c9.webp?x-oss-process=image/format,png
[format_png 5]: https://img-blog.csdnimg.cn/img_convert/c29deeed1520b57e2118c7cecdce0baf.webp?x-oss-process=image/format,png
[format_png 6]: https://img-blog.csdnimg.cn/img_convert/fa6fd45b550e95e996fb495e89443464.webp?x-oss-process=image/format,png
[format_png 7]: https://img-blog.csdnimg.cn/img_convert/49bb5771cb5461a1663f5605aefa61fd.webp?x-oss-process=image/format,png
[extensions]: https://link.juejin.cn?target=https%3A%2F%2Fgithub.com%2Fopen-telemetry%2Fopentelemetry-java-instrumentation%2Fblob%2Fmain%2Fexamples%2Fextension%2FREADME.md