An implementation of the OpenTelemetry specification as a Kotlin Multiplatform Library.

This API operates in 2 modes:

1. Compatibility mode, where it acts as a façade for the OpenTelemetry Java SDK
2. Regular mode, where it captures telemetry via a Kotlin Multiplatform (KMP) implementation

The following targets are supported:

• Android (API >=21)
• JVM (JDK >= 8)
• iOS
• JavaScript

• Tracing
• Logging

1. Add the following dependencies to your Android/Java project:

dependencies {
    val otelKotlinVersion = "0.1.0-alpha"
    implementation("io.opentelemetry.kotlin:core:$otelKotlinVersion")
    implementation("io.opentelemetry.kotlin:implementation:$otelKotlinVersion")
}

2. Initialize the SDK:

val otelKotlin = createOpenTelemetry {
    // configure SDK here
}

3. Use the Kotlin API in your app

Compatibility mode allows you to use a Kotlin API that uses the OpenTelemetry Java SDK under the hood to export telemetry. This can be helpful if you already use the Java implementation or don't want to use the Kotlin implementation.

1. Add the following dependencies to your Android/Java project:

dependencies {
    val otelKotlinVersion = "0.1.0-alpha"
    implementation("io.opentelemetry.kotlin:core:$otelKotlinVersion")
    implementation("io.opentelemetry.kotlin:compat:$otelKotlinVersion")
}

2. Wrap your existing OTel Java instance:

val otelJava = io.opentelemetry.sdk.OpenTelemetrySdk.builder().build()
val otelKotlin = otelJava.toOtelKotlinApi()

// or alternatively, create an instance that uses opentelemetry-java under the hood
val otelKotlin = createCompatOpenTelemetry {
    // configure SDK here
}

3. Use the Kotlin API instead of the Java API in your app

If you need to instrument code outside the module where the OpenTelemetry SDK initializes, only the api and noop dependencies are required:

dependencies {
    val otelKotlinVersion = "0.1.0-alpha"
    implementation("io.opentelemetry.kotlin:api:$otelKotlinVersion")
    implementation("io.opentelemetry.kotlin:noop:$otelKotlinVersion")
}

This ensures that you are writing instrumentation solely against OpenTelemetry's Instrumentation API and allows straightforward injection of different OpenTelemetry implementations. This is particularly useful for library authors who can instrument an SDK with the optional noop module by default, then ask consumers to pass in a real instance, as demonstrated below:

fun example(otel: OpenTelemetry = NoopOpenTelemetry) {
    val logger = otel.loggerProvider.getLogger("my_logger")
    logger.log("Hello, World!")
}

val tracer = otelKotlin.tracerProvider.getTracer(
    name = "kotlin-example-app",
    version = "0.1.0"
)
tracer.createSpan("my_span")

val logger = otelKotlin.loggerProvider.getLogger("my_logger")
logger.log("Hello, World!")

The API is subject to breaking change without notice and most symbols require an opt-in. You can opt-in on a case-by-case basis by adding @OptIn(ExperimentalApi::class) at each call site. Alternatively, you can opt-in for your whole module or project by altering Kotlin's compiler arguments:

kotlin {
    optIn.add("io.opentelemetry.kotlin.ExperimentalApi")
}

Example usage of the library can be found here.

Got feedback or found a bug? Please open a GitHub issue and we'll get back to you.

We are currently resource constrained and are actively seeking new contributors interested in working towards approver / maintainer roles. In addition to the documentation for approver / maintainer roles and the contributing guide, here are some additional notes on engaging:

• Pull request reviews are equally or more helpful than code contributions. Comments and approvals are valuable with or without a formal project role. They're also a great forcing function to explore a fairly complex codebase.
• Attending the Special Interest Group (SIG) is a great way to get to know community members and learn about project priorities.
• Issues labeled help wanted are project priorities. Code contributions (or pull request reviews when a PR is linked) for these issues are particularly important.
• Triaging / responding to new issues and discussions is a great way to engage with the project.
• We are available in the #otel-kotlin channel in the CNCF Slack. Please join us there for further discussions.

• Jamie Lynch, Embrace
• Jason Plumb, Splunk

For more information about the maintainer role, see the community repository.

• Hanson Ho, Embrace
• Masaki Sugimoto, Henry, Inc
• Francisco Prieto, Canary Technologies

For more information about the approver role, see the community repository.