OpenTelemetry Java Auto-Instrumentation for Custom Library Not Working

[NikunjPatel31]

I am trying to create auto-instrumentation for a custom library (MyLibrary) using OpenTelemetry Java Instrumentation. My goal is to generate traces for the method1() method in MyLibrary, which takes no parameters and writes to a file.

I have created a Java agent and the following classes for instrumentation:

MyLibraryInstrumentationModule

@AutoService(InstrumentationModule.class)
public class MyLibraryInstrumentationModule extends InstrumentationModule {

  public MyLibraryInstrumentationModule() {
    super("my-library");
  }

  @Override
  public List<TypeInstrumentation> typeInstrumentations() {
    return Collections.singletonList(new MyLibraryInstrumentation());
  }
}

MyLibrarySingletons

public class MyLibrarySingletons {

  private static final String INSTRUMENTATION_NAME = "io.opentelemetry.mylibrary";
  private static final Instrumenter<String, Object> INSTRUMENTER;

  static {
    SpanNameExtractor<String> spanNameExtractor = String::toString;

    InstrumenterBuilder<String, Object> builder =
        Instrumenter.<String, Object>builder(
            GlobalOpenTelemetry.get(), INSTRUMENTATION_NAME, spanNameExtractor);
    //            .addAttributesExtractor();

    INSTRUMENTER = builder.buildInstrumenter();
  }

  public static Instrumenter<String, Object> instrumenter() {
    return INSTRUMENTER;
  }

  private MyLibrarySingletons() {}
}

MyLibraryInstrumentation

public class MyLibraryInstrumentation implements TypeInstrumentation {
  @Override
  public ElementMatcher<TypeDescription> typeMatcher() {
    return named("method1");
  }

  @Override
  public void transform(TypeTransformer transformer) {
    transformer.applyAdviceToMethod(
        isPublic().and(named("method1")).and(takesNoArguments()),
        this.getClass().getName() + "$MethodAdvice");
  }

  @SuppressWarnings("unused")
  public static class MethodAdvice {

    @Advice.OnMethodEnter(suppress = Throwable.class)
    public static void methodEnter(
        @Advice.Local("otelContext") Context context, @Advice.Local("otelScope") Scope scope) {

      Context parentContext = currentContext();

      instrumenter().start(parentContext, "this is request from start");
    }

    @Advice.OnMethodExit(onThrowable = Throwable.class, suppress = Throwable.class)
    public static void methodExit(
        @Advice.Local("otelContext") Context context, @Advice.Local("otelScope") Scope scope) {

      if (scope == null) {
        return;
      }

      scope.close();

      instrumenter()
          .end(
              context,
              "This is request end of the method1",
              "This is response for end of method1",
              null);
    }
  }
}

Issue:

• I created the Java agent JAR with the above code .
• I then launched the application with -javaagent:path/to/opentelemetry-javaagent.jar.
• The application runs fine, but no traces are generated for method1() in my MyLibrary.

Debugging Steps I Tried:

• Verified that method1() in MyLibrary is being called.
• Confirmed that the Java agent is loading properly by adding other instrumentation, which worked as expected.
• Checked that the InstrumentationModule is correctly registered in META-INF/services/io.opentelemetry.javaagent.extension.instrumentation.InstrumentationModule.

Questions:

1. Why is the method1() instrumentation not working?
2. Is there an issue with the typeMatcher or transform logic in MyLibraryInstrumentation?
3. How can I debug the instrumentation process to identify what is going wrong?

[steverao]

You can check out related introduction about how to writing an instrumentation. If you can't any problem, please provide your repository that contains your code for us.

[NikunjPatel31]

@steverao I have read writing-instrumentation-module . The code that I have provided in the discussion is the code I am using. I have not created any repository for this.

Below is the code of MyLibrary:

public class MyLibrary {

    public void method1 () {

        var path = Path.of("path/temp.txt");

        try {
            Files.writeString(path, "this is a library");
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }
}

[steverao]

There are lots of probabilities. Any missing configuration might cause your problem. The effect of pseudocode is limited. Suggest providing the whole code or you can refer to a previous case of new instrumentation writing and compare if there are any differences.

[laurit]

Instead of

instrumenter().start(parentContext, "this is request from start");

you should probably have

context = instrumenter().start(parentContext, "this is request from start");
scope = context.makeCurrent();

with your current code both context and scope are null so the advice in methodExit will not do anything.
As for debugging you could insert System.err.println() or new Exception().printStackTrace() in your advice code to verify it is actually called.

[NikunjPatel31]

@laurit

Below is the code of application to which I am attaching the agent:

public static void main(String[] args) {

        MyLibrary myLibrary = new myLibrary();

        Timer timer = new Timer();


        timer.scheduleAtFixedRate(new TimerTask() {

            @Override
            public void run() {

                System.out.println("Timer task started...");

                myLibrary.method1();
            }
        }, 10 * 1000, 10000);

        SpringApplication.run(Demo2Application.class, args);
    }

I am able to see Timer task started...

Below is the updated Code of MyLibraryInstrumentation

@Override
  public ElementMatcher<TypeDescription> typeMatcher() {
    return nameStartsWith("com.mylibrary.test");
  }

  @Override
  public void transform(TypeTransformer transformer) {

    logger.info("**** we are inside the transform ***");

    transformer.applyAdviceToMethod(
        isMethod().and(isPublic()).and(named("method1")).and(takesNoArguments()),
        this.getClass().getName() + "$MethodAdvice");
  }

  @SuppressWarnings("unused")
  public static class MethodAdvice {

    @Advice.OnMethodEnter(suppress = Throwable.class)
    public static void methodEnter(
        @Advice.Local("otelContext") Context context, @Advice.Local("otelScope") Scope scope) {

      logger.info("**** inside methodEnter");

      Context parentContext = currentContext();

      context = instrumenter().start(parentContext, "this is request from start");
      scope = context.makeCurrent();
    }

    @Advice.OnMethodExit(onThrowable = Throwable.class, suppress = Throwable.class)
    public static void methodExit(
        @Advice.Local("otelContext") Context context, @Advice.Local("otelScope") Scope scope) {

      logger.info("**** inside methodEnter");

      if (scope == null) {
        return;
      }

      scope.close();

      instrumenter()
          .end(
              context,
              "This is request end of the method1",
              "This is response for end of method1",
              null);
    }
  }

Below is the dependency from pom.xml

<dependency>
            <groupId>com.mylibrary.test</groupId>
            <artifactId>MyLibrary</artifactId>
            <version>1.0.0</version>
</dependency>

This time I have added logger. I am able to see the log **** we are inside the transform *** . But logs for methodEnter and methodExit are not visible. I have made the necessary changes according to your suggestion.

[laurit]

If you enable debug output with -Dotel.javaagent.debug=true you'll probably see that your advice could not be applied. The advice code is copied at the start/end of the instrumented method so everything you use in the advice needs to be available in the application. The logger itself is probably fine, but by adding the logger field to the TypeInstrumentation class and using it from the Advice class you have made the Advice depend on the TypeInstrumentation so all the dependencies of the TypeInstrumentation class like, byte buddy, are now needed to apply the advice. I'd suggest you to use System.err.println instead of the logger unless you know what you are doing.

[NikunjPatel31]

I found the issue. I gave Instrumentation name in the constructor. Thank you @laurit @steverao