Налаштування OpenTelemetry Kotlin

SDK OpenTelemetry Kotlin налаштовується під час ініціалізації за допомогою його параметра DSL. І createOpenTelemetry, і createCompatOpenTelemetry використовують той самий DSL, повний приклад якого наведено нижче:

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

Наступні розділи показують, як налаштувати різні аспекти поведінки SDK. Це не вичерпний перелік способів налаштування SDK, скоріше тут висвітлено найчастіші випадки використання.

Експорт

Експорт телеметрії через OTLP

OpenTelemetry Kotlin підтримує експорт через OTLP поверх HTTP у двійковому кодуванні. Логи та траси можна експортувати за допомогою наведеної нижче конфігурації, яка надсилає дані до типового порту OpenTelemetry Collector:

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

Ресурс

Ресурси можна налаштувати глобально, щоб додати атрибути до всіх сигналів:

val otel: OpenTelemetry = createOpenTelemetry {
    serviceName = "checkout"

    resource(schemaUrl = "https://opentelemetry.io/schemas/1.30.0") {
        setStringAttribute("service.namespace", "payments")
        setBooleanAttribute("feature.experimental_checkout", true)
        setLongAttribute("service.instance.replica", 3)
        setDoubleAttribute("rollout.percentage", 0.25)
        setStringListAttribute("service.tags", listOf("checkout", "v2"))
    }

    tracerProvider {
        resource {}
    }
}

Ресурс також можна обмежити одним сигналом. Його обʼєднують із будь-якою глобальною конфігурацією, причому локальна має пріоритет:

val otel: OpenTelemetry = createOpenTelemetry {
    tracerProvider {
        resource {
            setStringAttribute("service.namespace", "payments")
        }
    }
}

Синтаксичний цукор також дозволяє задавати ресурси з Map<String, Any>:

val otel: OpenTelemetry = createOpenTelemetry {
    resource {
        resource(mapOf("service.namespace" to "payments"))
    }
}

За замовчуванням SDK завжди встановлює service.name, service.version і telemetry.sdk.*. Ці значення можна перевизначити, надавши власні.

Обмеження

Обмеження атрибутів

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

val otel: OpenTelemetry = createOpenTelemetry {
    attributeLimits {
        attributeCountLimit = 200
        attributeValueLengthLimit = 256
    }
}

Обмеження для логів

Обмеження для логів діють подібно до розділу обмеження атрибутів, але стосуються записів логів:

val otel: OpenTelemetry = createOpenTelemetry {
    loggerProvider {
        logLimits {
            attributeCountLimit = 200
            attributeValueLengthLimit = 256
        }
    }
}

Обмеження для відрізків

Обмеження для відрізків надають ті самі обмеження, що й раніше в розділі обмеження атрибутів, а також конфігурацію, яка обмежує кількість відрізків і подій, що захоплюються:

val otel: OpenTelemetry = createOpenTelemetry {
    tracerProvider {
        spanLimits = 200
        eventCountLimit = 250
        attributeCountPerEventLimit = 50
        attributeCountPerLinkLimit = 20
        attributeCountLimit = 200
        attributeValueLengthLimit = 256
    }
}

Неявне зберігання контексту

Як описано в посібнику з інструментування неявного контексту, можна змінити типовий механізм зберігання неявного контексту. За замовчуванням його зберігають у глобальному механізмі на весь процес, але за допомогою storageMode це можна змінити на thread-local:

val otel: OpenTelemetry = createOpenTelemetry {
    context {
        storageMode = ImplicitContextStorageMode.THREAD_LOCAL
        // storage { MyCustomStorage() }
    }
}

Ви також можете реалізувати власні механізми зберігання. Нижчий приклад відтворює ту саму поведінку, що й типовий підхід OpenTelemetry Kotlin до глобального зберігання контексту:

val otel: OpenTelemetry = createOpenTelemetry {
    context {
        storage { MyCustomStorage() }
    }
}

class CustomStorage(private val default: Context): ImplicitContextStorage {

    private var ref: Context = default

    override fun setImplicitContext(context: Context) {
        ref = context
    }

    override fun implicitContext(): Context = ref
}

Востаннє змінено July 12, 2026: [uk] Ukrainian documentation for OpenTelemetry (408b37c7)