diff --git a/README.md b/README.md index 77a9f108f..b516aa1d8 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,9 @@ The repository contains the `OpenTelemetry Android Agent`, which initializes the [OpenTelemetry Java SDK](https://github.com/open-telemetry/opentelemetry-java) and provides auto-instrumentation of Android apps for real user monitoring (RUM). +While this project isn't 100% Kotlin, it has a "Kotlin-First" policy where usage in Kotlin-based Android apps will be prioritized in terms +of API and idioms. More details about this policy can be found [here](./docs/KOTLIN_FIRST.md). + # Getting Started > If your project's minSdk is lower than 26, then you must enable @@ -68,6 +71,7 @@ The following instrumentations are bundled with the Android Agent: See the following pages for details about the related topics: +- [Kotlin-First Policy](./docs/KOTLIN_FIRST.md) - [StrictMode Guidance](./docs/STRICTMODE.md) - [Exporter Management](./docs/EXPORTER_CHAIN.md) diff --git a/docs/KOTLIN_FIRST.md b/docs/KOTLIN_FIRST.md new file mode 100644 index 000000000..af482c55a --- /dev/null +++ b/docs/KOTLIN_FIRST.md @@ -0,0 +1,27 @@ +# Kotlin-First Policy + +The OpenTelemetry Android Agent was initially built when Java was the predominant language for Android development. Over the years, the +platform has shifted towards being one that is primarily Kotlin, so this project will follow suit. This means that we consider the primary +use case of this project to be apps written in Kotlin by folks who are familiar with Android development in Kotlin. + +In practice, we want our API and code to be structured with the Kotlin language and idioms in mind. This will allow the project to feel +more native and be more readable to modern Android developers, thereby reduce one layer of friction of adopting OpenTelemetry: the +Java-ness of it all. + +Both the public API of the Agent and internal code will be progressively converted into Kotlin. It is a goal for us for all production +code to one day be written exclusively in Kotlin. + +## OpenTelemetry API Compatibility + +The OpenTelemetry Android Agent is currently built on the OTel Java SDK and ecosystem. It also exports the OTel Java API for recording OTel +signals. This will be the case until official Kotlin versions are released and stabilized under the OpenTelemetry org, which is currently +under development. + +## Java Compatibility + +Java and Kotlin are interoperable from a language standpoint, so in theory, the Agent API is callable from Java. But from a public API +standpoint, we consider the Java use case to be unsupported, meaning that as the API evolves, we will NOT make special efforts to preserve +Java language consistency or ergonomics. We will only consider an API change "breaking" if it affects the Kotlin use case. + +Bugs should not be filed for compatibility issues when calling the Agent API from Java. As such, we advise that all usage are done in +Kotlin if possible to prevent syntactic changes from breaking your app's build.