OpenTelemetry Java notes

OpenTelemetry Java Instrumentation

General

  • The java SDK uses grpc/protobuf as the default protocol, over port 4317
  • The java agent uses http/protobuf as the default protocol, over port 4318

Writing Instrumentation

Transform methods

When writing transform methods in instrumentation, when writing takesArgument() methods, if the class is in a java package you don’t need to use the named helper.

so instead of

  @Override
  public void transform(TypeTransformer transformer) {
    transformer.applyAdviceToMethod(
        isMethod()
            .and(named("invoke"))
            .and(takesArguments(4))
            .and(takesArgument(0, String.class))
            .and(takesArgument(1, Object.class))
            .and(takesArgument(2, named("java.lang.reflect.Type")))
            .and(takesArgument(3, named("java.util.Map")))

It could be:

  @Override
  public void transform(TypeTransformer transformer) {
    transformer.applyAdviceToMethod(
        isMethod()
            .and(named("invoke"))
            .and(takesArguments(4))
            .and(takesArgument(0, String.class))
            .and(takesArgument(1, Object.class))
            .and(takesArgument(2, Type.class))
            .and(takesArgument(3, Map.class))

A quote from one of the maintainers (https://github.com/laurit) about the dangers of using a class literal:

This code is run when the agent sets up the transformations. It does not see the application classes so you have to use named for any classes that belong to the instrumented library. It does see all the java. classes so those may be used directly. If you wish to further complicate things then consider that using a class literal loads that class. If there is an instrumentation that applies to that class then loading it before transformations are set up may inhibit instrumentations that do structural changes e.g. add a virtual field to the class.

Local Development

To publish a test jar locally to test, run the following command:

# Generate jar file from instrumentation repo
./gradlew assemble

# copy it to where you want to test it (update the destination and version number)
cp /Users/jay/code/projects/opentelemetry-java-instrumentation/javaagent/build/libs/opentelemetry-javaagent-2.5.0-SNAPSHOT.jar opentelemetry-javaagent.jar

Testing commands

To run tests using the latest dependency version, add -PtestLatestDeps=true to your test command

./gradlew -PtestLatestDeps=true :instrumentation:couchbase-3.1:javaagent:test