OpenTelemetry Kotlin

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

Supported targets

The following targets are supported:

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

Supported OTel APIs

• Tracing
• Logging

Getting Started

Regular mode

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

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

Instrumenting code

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!")
}

Example usage

Tracing API

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

Logging API

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

Example Apps

Example usage of the library can be found here.

Feedback/bugs

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

Contributing

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.

Maintainers

• Jamie Lynch, Embrace
• Jason Plumb, Splunk

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

Approvers

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

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

Thanks to all of our contributors!