Початок роботи

OpenTelemetry Kotlin надає Kotlin Multiplatform реалізацію специфікації OpenTelemetry.

OpenTelemetry Kotlin SDK

Підтримувані платформи

OpenTelemetry Kotlin наразі вимагає Kotlin 2.0 або новішої версії. Підтримувані платформи та їхні вимоги наведені нижче:

Стабільність API

API наразі підлягає змінам без попередження, і більшість символів вимагають явного включення. Ви можете включити їх окремо, додавши @OptIn(ExperimentalApi::class) на кожному виклику.

Альтернативно, ви можете включити їх для всього модуля або проєкту, змінивши аргументи компілятора Kotlin:

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

Підтримувані режими

OpenTelemetry Kotlin API працює в 2 режимах:

• Звичайний режим, який захоплює телеметрію за допомогою реалізації Kotlin Multiplatform (KMP). Доступний для всіх цільових платформ.
• Режим сумісності, який виступає фасадом для OpenTelemetry Java SDK. Доступний лише для цільових платформ JVM/Android.

Встановлення OpenTelemetry Kotlin

Спочатку виберіть, чи слідувати інструкціям для звичайного режиму або режиму сумісності нижче.

Використання звичайного режиму

1. Додайте ці залежності до build.gradle модуля, який ініціалізує SDK:

dependencies {
    val otelKotlinVersion = "<replace-with-latest-version>"
    implementation("io.opentelemetry.kotlin:core:$otelKotlinVersion")
    implementation("io.opentelemetry.kotlin:implementation:$otelKotlinVersion")
}

1. Ініціалізуйте SDK на ранньому етапі життєвого циклу вашого застосунку:

val otelKotlin: OpenTelemetry = createOpenTelemetry {
    // configure SDK here
}

1. Використовуйте Kotlin API у вашому застосунку.

Використання режиму сумісності

Режим сумісності дозволяє використовувати Kotlin API, який під капотом використовує OpenTelemetry Java SDK. Це може бути корисно, якщо ви вже використовуєте Java реалізацію або не хочете використовувати Kotlin реалізацію.

1. Додайте ці залежності до build.gradle модуля, який ініціалізує SDK:

dependencies {
    val otelKotlinVersion = "<replace-with-latest-version>"
    implementation("io.opentelemetry.kotlin:core:$otelKotlinVersion")
    implementation("io.opentelemetry.kotlin:compat:$otelKotlinVersion")
}

1. Обгорніть ваш наявний екземпляр OpenTelemetry Java інстанцію:

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

// або, альтернативно, створіть екземпляр, який використовує opentelemetry-java під капотом
val otelKotlin: OpenTelemetry = createCompatOpenTelemetry {
    // configure SDK here
}

1. Використовуйте Kotlin API разом або замість Java API у вашому застосунку.

Налаштування інших модулів

Далі додайте залежності api та noop до build.gradle всіх модулів, які ви хочете інструментувати:

dependencies {
    val otelKotlinVersion = "<replace-with-latest-version>"
    implementation("io.opentelemetry.kotlin:api:$otelKotlinVersion")
    implementation("io.opentelemetry.kotlin:noop:$otelKotlinVersion")
}

Як я можу інструментувати свій застосунок?

Нижче наведено мінімальний приклад, який генерує лог та трасу:

fun example(otel: OpenTelemetry = NoopOpenTelemetry) {
    // генерує лог
    val logger = otel.loggerProvider.getLogger("my_logger")
    logger.log("Hello, World!")

    // починає та завершує відрізок
    val tracer = otel.tracerProvider.getTracer("my_tracer")
    tracer.startSpan("my_span").end()
}

Щоб надсилати телеметрію, передайте реальний екземпляр OpenTelemetry як параметр замість no-op. Якщо ви є автором бібліотеки, цей підхід дуже корисний, оскільки дозволяє користувачам вашої бібліотеки вибирати, чи отримувати телеметрію з вашої бібліотеки.

Експорт до OpenTelemetry Collector

Як останній крок, ймовірно, потрібно налаштувати експорт телеметрії через OTLP/HTTP до OpenTelemetry Collector або до бекенду, який приймає OTLP. Додайте залежність exporters-otlp у модуль, де ви ініціалізували SDK:

dependencies {
    val otelKotlinVersion = "<replace-with-latest-version>"
    implementation("io.opentelemetry.kotlin:exporters-otlp:$otelKotlinVersion")
}

Потім налаштуйте експортери OTLP з пакетним процесором:

val url = "http://localhost:4318"
val otel: OpenTelemetry = createOpenTelemetry {
    tracerProvider {
        export {
            batchSpanProcessor(
                otlpHttpSpanExporter(url)
            )
        }
    }
    loggerProvider {
        export {
            batchLogRecordProcessor(
                otlpHttpLogRecordExporter(url)
            )
        }
    }
}

Вітаємо! Ви завершили кроки встановлення OpenTelemetry Kotlin SDK.