はじめに

OpenTelemetry Kotlin SDK を使い始める

OpenTelemetry Kotlin は、OpenTelemetry 仕様の Kotlin Multiplatform 実装を提供します。

OpenTelemetry Kotlin SDK

サポートされるプラットフォーム

OpenTelemetry Kotlin は現在 Kotlin 2.0 以上が必要です。 現在サポートされているプラットフォームとその前提条件は以下のとおりです。

プラットフォーム前提条件
AndroidminSdk >=21
JVMJDK >= 11
iOS16.0
JavaScriptES5

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. SDK を初期化するモジュールの build.gradle に以下の依存関係を追加します。
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 {
    // ここで SDK を設定する
}
  1. アプリで Kotlin API を使用します。

互換モードを使用する

互換モードでは、内部的に OpenTelemetry Java SDK を使用する Kotlin API を利用できます。 これは、すでに Java 実装を使用している場合や、Kotlin 実装を使用したくない場合に役立ちます。

  1. SDK を初期化するモジュールの build.gradle に以下の依存関係を追加します。
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 {
    // ここで SDK を設定する
}
  1. アプリで Java API のかわりに、または Java API と並行して Kotlin API を使用します。

他のモジュールのセットアップ

次に、計装したいすべてのモジュールの build.gradle に api および noop の依存関係を追加します。

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()
}

テレメトリーを出力するには、no-op ではなく OpenTelemetry の実インスタンスをパラメーターとして渡します。 ライブラリの作者にとって、このパターンはライブラリの利用者がライブラリからのテレメトリー収集にオプトインできるため、非常に便利です。

OpenTelemetry Collector へのエクスポート

最後のステップとして、OTLP/HTTP を介して OpenTelemetry Collector、または OTLP を受け入れるバックエンドへのテレメトリーエクスポートを設定する必要があります。 SDK を初期化したモジュールに exporters-otlp の依存関係を追加します。

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 のインストール手順が完了しました。


最終更新 September 5, 2026: [ja] add translation of content/en/docs/languages/kotlin/getting-started.md (#11553) (d3baed32)