Compatibility issues when using opentelemetry-android with minimum required versions

[priettt]

TL;DR

Testing opentelemetry-android with our documented minimum requirements (Kotlin 2.0, AGP 7.4) revealed compatibility issues:

1. AGP 7.4 is not viable - fails with modern AndroidX libraries and D8 dexing errors
2. Minimum AGP could be 8.0.2 - resolves the tooling issues
3. OkHttp 5.3.2 forces Kotlin stdlib 2.2.21 - incompatible with our stated Kotlin 2.0 minimum
4. Action needed: Either bump minimum Kotlin to 2.2 OR downgrade OkHttp dependency to v4 (how?)
5. Missing requirement: We should define a minimum compileSdk version in VERSIONING.md. 34 is a good starting point, as it works with AGP 8.0.2.
6. Testing: We could add something like my test app to the CI, and verify that it builds with the minimum versions, at least to get some basic verification that the stated minimum requirements are correct.

Context

Following the discussion in #1489 about bumping the minimum Kotlin version to 2.0, I created a test app to verify all the compatibility claims made in our VERSIONING.md:

• Kotlin 2.0
• API 26
• AGP 7.4 and Gradle 7.5
• JDK 11 (build-time)
• Java language level 8

Test app repository: https://github.com/priettt/small-android-app

• main branch: works without opentelemetry-android
• otel-android-issue branch: fails with opentelemetry-android

Issues found

1. AGP 7.4 incompatibility with modern AndroidX libraries

Error: checkDebugAarMetadata fails with lifecycle-runtime-ktx:2.9.x

Could not resolve androidx.lifecycle:lifecycle-runtime-ktx:2.6.1.
  > The consumer was configured to find a runtime of a component, preferably optimized for Android, 
    as well as attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '7.4.2'

Root cause: androidx.lifecycle:lifecycle-process:2.9.x uses multi-variant KMP metadata that AGP 7.4 cannot resolve.

Workaround: Downgrade to androidx.lifecycle:lifecycle-process:2.8.7

2. AGP 7.4 incompatibility with androidx.core

Error: checkDebugAarMetadata fails

Dependency 'androidx.core:core-ktx:1.17.0' requires Android Gradle plugin 8.9.1 or higher.
This build currently uses Android Gradle plugin 7.4.2.

Workaround: Downgrade to androidx.core:core:1.13.1

3. D8 dexing failures with AGP 7.4

Error: Multiple NullPointerException during dexing

ERROR:/Users/.../opentelemetry-exporter-sender-okhttp-1.57.0.jar: D8: java.lang.NullPointerException
ERROR:/Users/.../opentelemetry-api-1.57.0.jar: D8: java.lang.NullPointerException
[... many more similar errors]

Analysis: D8 in AGP 7.4 fails to process multiple OpenTelemetry artifacts. This appears to be a tooling limitation rather than a dependency issue.

Recommendation: Bump minimum AGP to 8.0.2 instead of continuing to downgrade dependencies.

4. Kotlin stdlib version conflict (Critical)

After bumping to AGP 8.0.2, a new issue appears:

Error: Kotlin metadata version incompatibility

e: Module was compiled with an incompatible version of Kotlin. 
   The binary version of its metadata is 2.2.0, expected version is 2.0.0.

Root cause: A transitive dependency is exposing kotlin-stdlib:2.2.21

Investigation: Running ./gradlew :app:dependencyInsight --dependency kotlin-stdlib --configuration releaseRuntimeClasspath reveals:

org.jetbrains.kotlin:kotlin-stdlib:2.2.21
+--- com.squareup.okhttp3:okhttp-android:5.3.2
     \--- com.squareup.okhttp3:okhttp:5.3.2
          \--- io.opentelemetry:opentelemetry-exporter-sender-okhttp:1.57.0
               +--- io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha:2.23.0-alpha

The culprit: okhttp3-android:5.3.2 (brought in by opentelemetry-instrumentation-bom-alpha:2.23.0-alpha)

Verification: Downgrading to opentelemetry-instrumentation-bom-alpha:2.17.1-alpha (last version using OkHttp 4) allows the build to succeed.

Proposed solutions

We have two options:

1. Bump minimum Kotlin requirement to 2.2 in VERSIONING.md
2. Downgrade OkHttp dependency in opentelemetry-instrumentation-bom-alpha to OkHttp 4 (if possible)

Additionally, we should:

• Update VERSIONING.md to reflect minimum AGP 8.0.2 (AGP 7.4 is not viable)
• Consider using coreLibrariesVersion Kotlin compiler extension to prevent future stdlib conflicts
• Define minimum compileSdk version in VERSIONING.md (currently not specified). 34 may be a good starting point, as it works with AGP 8.0.2.

Questions

1. Is it acceptable to bump the minimum Kotlin version to 2.2? I think not, it's too new.
2. Can we downgrade the OkHttp dependency in the instrumentation BOM?
3. Should we update our minimum AGP requirement to 8.0.2?

[LikeTheSalad]

Thank you for gathering all these details! It provides a great overview of the situation. I'll address proposed solutions/questions below.

1. Bump minimum Kotlin requirement to 2.2 in VERSIONING.md

I'm up for keeping Kotlin on its latest version for this project, while ensuring that the binaries are compatible with older versions, as we do here. It's been a while since I tested it, though I'm guessing it should still work even for Kotlin 2.3.0, where if we set the min compatible version to 2.0, for example, we should get the best of both worlds? Meaning that, we can use libraries that require later Kotlin versions, such as OkHttp, while still keeping our artifacts compatible with projects that use lower versions.

3. Downgrade OkHttp dependency in opentelemetry-instrumentation-bom-alpha to OkHttp 4 (if possible)

I don't like the idea of having to downgrade dependencies. I'm not fully closed to it, but I'd leave that option as the very last/desperate one.

On questions:

1. Is it acceptable to bump the minimum Kotlin version to 2.2? I think not, it's too new.

If we can get away with making our code compatible with 2.0 (as mentioned earlier in this comment) while we use 2.3 (or the latest version available in the future) for our compilation, I'd prefer that to enforcing too recent versions of Kotlin on our users (unless there's no other way because the "binary compatibility" feature stops working for our project or the like).

2. Can we downgrade the OkHttp dependency in the instrumentation BOM?

If you're referring to the Java Instrumentation project's BOM, I don't think we can convince the maintainers of doing so, and it's also not what we should do as a first option imo.

3. Should we update our minimum AGP requirement to 8.0.2?

I'm fine with doing this. Especially since the latest stable versions are 9.x already. Maybe we can have it as a rule to always keep AGP compatibility down to the last major version. So when AGP 10 stable is released, we can switch to 9.0 as our minimum and so on.

Please let me know if I missed or misunderstood some of your proposals. Overall, I'm up for keeping versions updated and trying to keep our code compatible with older versions as much as possible. If that becomes impossible, I'd lean more towards keeping our versions up-to-date, even if that causes issues for older environments, and prompting users to either upgrade their envs or to use older versions of OTel Android, similarly to what OkHttp seems to do as they mention here. Still, I'm looking forward to other opinions on this topic before making a decision.