Skip to content
Client Plugin

Ktor Client에서 OpenTelemetry를 사용한 분산 추적

필수 종속성: io.opentelemetry.instrumentation:opentelemetry-ktor-3.0

코드 예제: opentelemetry

Ktor는 트레이스(trace), 메트릭(metric), 로그와 같은 텔레메트리(telemetry) 데이터를 수집하기 위한 오픈 소스 관측 가능성(observability) 프레임워크인 OpenTelemetry와 연동됩니다. OpenTelemetry는 애플리케이션을 계측하고 Grafana나 Jaeger와 같은 모니터링 및 관측 가능성 도구로 데이터를 내보내는 표준화된 방법을 제공합니다.

KtorClientTelemetry 플러그인을 사용하면 나가는(outgoing) HTTP 요청을 자동으로 추적할 수 있습니다. 메서드, URL, 상태 코드와 같은 메타데이터를 캡처하고 서비스 간에 트레이스 컨텍스트(trace context)를 전파합니다. 또한 스팬 속성(span attributes)을 커스터마이징하거나 자체 OpenTelemetry 구성을 적용할 수도 있습니다.

서버 측에서는 서버로 들어오는 HTTP 요청을 계측할 수 있도록 OpenTelemetry의 KtorServerTelemetry 플러그인을 제공합니다.

종속성 추가 ​

KtorClientTelemetry을 사용하려면 빌드 스크립트에 opentelemetry-ktor-3.0 아티팩트를 추가하세요.

kotlin
implementation("io.opentelemetry.instrumentation:opentelemetry-ktor-3.0:2.18.1-alpha")
groovy
implementation "io.opentelemetry.instrumentation:opentelemetry-ktor-3.0:2.18.1-alpha"
xml
 <dependencies>
  <dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-ktor-3.0</artifactId>
    <version>2.18.1-alpha</version>
  </dependency>
</dependencies>

OpenTelemetry 구성 ​

Ktor 애플리케이션에 KtorClientTelemetry 플러그인을 설치하기 전에 OpenTelemetry 인스턴스를 구성하고 초기화해야 합니다. 이 인스턴스는 트레이스와 메트릭을 포함한 텔레메트리 데이터를 관리하는 역할을 합니다.

자동 구성 ​

OpenTelemetry를 구성하는 대표적인 방법은 AutoConfiguredOpenTelemetrySdk를 사용하는 것입니다. 이는 시스템 속성(system properties) 및 환경 변수를 기반으로 익스포터(exporter)와 리소스(resource)를 자동으로 구성하여 설정을 간소화해 줍니다.

자동으로 감지된 구성도 커스터마이징할 수 있습니다. 예를 들어 다음과 같이 service.name 리소스 속성을 추가할 수 있습니다.

kotlin
package com.example

import io.opentelemetry.api.OpenTelemetry
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk
import io.opentelemetry.semconv.ServiceAttributes

fun getOpenTelemetry(serviceName: String): OpenTelemetry {

    return AutoConfiguredOpenTelemetrySdk.builder().addResourceCustomizer { oldResource, _ ->
        oldResource.toBuilder()
            .putAll(oldResource.attributes)
            .put(ServiceAttributes.SERVICE_NAME, serviceName)
            .build()
    }.build().openTelemetrySdk
}

프로그래밍 방식 구성 ​

환경 기반 구성에 의존하는 대신 코드에서 직접 익스포터, 프로세서, 프로파게이터(propagator)를 정의하려면 OpenTelemetrySdk를 사용할 수 있습니다.

다음 예제는 OTLP 익스포터, 스팬 프로세서, 트레이스 컨텍스트 프로파게이터를 사용하여 프로그래밍 방식으로 OpenTelemetry를 구성하는 방법을 보여줍니다.

kotlin
import io.opentelemetry.api.OpenTelemetry
import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator
import io.opentelemetry.context.propagation.ContextPropagators
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter
import io.opentelemetry.sdk.OpenTelemetrySdk
import io.opentelemetry.sdk.trace.SdkTracerProvider
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor

fun configureOpenTelemetry(): OpenTelemetry {
    val spanExporter = OtlpGrpcSpanExporter.builder()
        .setEndpoint("http://localhost:4317")
        .build()

    val tracerProvider = SdkTracerProvider.builder()
        .addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build())
        .build()

    return OpenTelemetrySdk.builder()
        .setTracerProvider(tracerProvider)
        .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
        .buildAndRegisterGlobal()
}

텔레메트리 설정을 완벽하게 제어해야 하거나, 배포 환경에서 자동 구성에 의존할 수 없는 경우 이 방식을 사용하세요.

자세한 내용은 OpenTelemetry SDK 구성 요소 문서를 참조하세요.

KtorClientTelemetry 설치 ​

KtorClientTelemetry 플러그인을 설치하려면 클라이언트 구성 블록 내의 install 함수에 전달하고 구성된 OpenTelemetry 인스턴스를 설정하세요.

kotlin
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.auth.*
//...

val client = HttpClient(CIO) {
    val openTelemetry = getOpenTelemetry(serviceName = "opentelemetry-ktor-client")

    install(KtorClientTelemetry) {
        setOpenTelemetry(openTelemetry)
    }
}

트레이싱 구성 ​

Ktor 클라이언트가 나가는 HTTP 호출에 대해 OpenTelemetry 스팬을 기록하고 내보내는 방식을 커스터마이징할 수 있습니다. 아래 옵션들을 통해 추적할 요청, 스팬 이름 지정 방식, 포함할 속성, 캡처할 헤더, 스팬 종류(kind) 결정 방식 등을 세부적으로 조정할 수 있습니다.

이러한 개념에 대한 자세한 내용은 OpenTelemetry 트레이싱 문서를 참조하세요.

추가 HTTP 메서드 추적 ​

기본적으로 플러그인은 표준 HTTP 메서드(GET, POST, PUT 등)를 추적합니다. 추가적인 메서드나 커스텀 메서드를 추적하려면 knownMethods 프로퍼티를 구성하세요.

kotlin
install(KtorClientTelemetry) {
    // ...
    knownMethods(HttpMethod.DefaultMethods + CUSTOM_METHOD)
}

헤더 캡처 ​

특정 HTTP 요청 헤더를 스팬 속성으로 포함하려면 capturedRequestHeaders 프로퍼티를 사용하세요.

kotlin
install(KtorClientTelemetry) {
    // ...
    capturedRequestHeaders(HttpHeaders.UserAgent)
}

응답 헤더 캡처 ​

특정 HTTP 응답 헤더를 스팬 속성으로 캡처하려면 capturedResponseHeaders 프로퍼티를 사용하세요.

kotlin
install(KtorClientTelemetry) {
    // ...
    capturedResponseHeaders(HttpHeaders.ContentType, CUSTOM_HEADER)
}

커스텀 속성 추가 ​

스팬의 시작 또는 종료 시점에 커스텀 속성을 부여하려면 attributesExtractor 프로퍼티를 사용하세요.

kotlin
install(KtorClientTelemetry) {
    // ...
    attributesExtractor {
        onStart {
            attributes.put("start-time", System.currentTimeMillis())
        }
        onEnd {
            attributes.put("end-time", Instant.now().toEpochMilli())
        }
    }
}

다음 단계 ​

KtorClientTelemetry을 설치하고 구성한 후에는 KtorServerTelemetry를 사용하는 서비스처럼 텔레메트리가 활성화된 다른 서비스로 요청을 보내 스팬이 정상적으로 생성되고 전파되는지 확인할 수 있습니다. Jaeger, Zipkin, Grafana Tempo와 같은 관측 가능성 백엔드 도구에서 트레이스의 양쪽(클라이언트 및 서버)을 모두 확인하여 분산 추적이 엔드투엔드로 원활히 작동하는지 검증할 수 있습니다.