Java용 Azure SDK에서 추적 구성

아티클
10/23/2023

이 문서에서는 Java용 Azure SDK를 구성하여 추적 기능을 통합하는 방법을 소개합니다.

OpenTelemetry SDK를 사용하고 구성하거나 OpenTelemetry 호환 에이전트를 사용하여 Azure 클라이언트 라이브러리에서 추적을 사용하도록 설정할 수 있습니다. OpenTelemetry는 클라우드 네이티브 소프트웨어에 대한 원격 분석 데이터를 생성, 캡처 및 수집하기 위한 인기 있는 오픈 소스 관찰 프레임워크입니다.

추적 과 관련된 두 가지 주요 개념인 범위 및 추적이 있습니다. 범위는 추적의 단일 작업을 나타냅니다. 범위는 HTTP 요청, RPC(원격 프로시저 호출), 데이터베이스 쿼리 또는 코드에서 사용하는 경로를 나타낼 수 있습니다. 추적은 시스템을 통한 작업 경로를 보여 주는 범위의 트리입니다. TraceID라는 고유한 16 바이트 시퀀스로 추적을 고유하게 구분할 수 있습니다. 이러한 개념 및 OpenTelemetry와 관련된 방법에 대한 자세한 내용은 OpenTelemetry 설명서를 참조 하세요.

Azure Monitor Java 에이전트를 사용하여 Azure SDK 추적

Azure Monitor Java In-process 에이전트를 사용하여 코드 변경 없이 애플리케이션 모니터링을 사용하도록 설정할 수 있습니다. 자세한 내용은 Java 애플리케이션에 대한 Azure Monitor OpenTelemetry 기반 자동 계측을 참조하세요. Azure SDK 지원은 에이전트 버전 3.2부터 기본적으로 사용하도록 설정됩니다.

OpenTelemetry 에이전트를 사용하여 Azure SDK 호출 추적

OpenTelemetry Java 에이전트를 사용하는 경우 Azure SDK 계측은 버전 1.12.0부터 기본으로 사용하도록 설정됩니다.

내보내기를 구성하거나, 수동 계측을 추가하거나, 원격 분석을 보강하는 방법에 대한 자세한 내용은 Java용 OpenTelemetry Instrumentation을 참조하세요.

참고 항목

OpenTelemetry 에이전트 아티팩트가 안정적이지만 유선 원격 분석 안정성 보장을 제공하지 않으므로 에이전트를 업데이트할 경우 시간이 지남에 따라 변경될 수 있는 Azure SDK에서 생성된 범위 이름 및 특성 이름이 발생할 수 있습니다. 자세한 내용은 호환성 요구 사항을 참조 하세요.

OpenTelemetry SDK를 사용하여 애플리케이션 수동 계측(미리 보기)

OpenTelemetry SDK를 직접 사용하는 경우 선택한 백 엔드에 대해 SDK 및 내보내기를 구성해야 합니다. 자세한 내용은 OpenTelemetry 설명서를 참조 하세요.

Azure SDK 추적을 사용하도록 설정하려면 애플리케이션에 최신 com.azure:azure-core-tracing-opentelemetry 패키지를 추가합니다. 예를 들어 Maven에서 pom.xml 파일에 다음 항목을 추가합니다.

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-tracing-opentelemetry</artifactId>
</dependency>

지금 애플리케이션을 실행하는 경우 백 엔드에서 Azure SDK 범위를 가져와야 합니다. 그러나 비동기 호출을 사용하면 Azure SDK와 애플리케이션 범위 간의 상관 관계가 끊어질 수 있습니다.

기본적으로 Azure SDK는 OpenTelemetry에 의해 암시적으로 전파되는 것을 부모로 새 범위에 사용합니다 io.opentelemetry.context.Context.current(). 비동기 호출에서 암시적 컨텍스트 전파가 중단됩니다. OpenTelemetry 에이전트는 컨텍스트 전파를 지원하여 이 문제를 해결하지만 OpenTelemetry SDK에는 이러한 기능이 없습니다.

추적 컨텍스트를 명시적으로 전달

Azure SDK를 사용하면 키 아래의 추적 컨텍스트를 trace-context 명시적으로 전달할 com.azure.core.util.Context 수 있습니다. 명시적 추적 컨텍스트를 제공하는 경우 Azure SDK는 암시적 컨텍스트 대신 이를 사용하므로 애플리케이션과 Azure SDK 범위 간의 상관 관계를 설정할 수 있습니다.

다음 예제에서는 들어오는 웹 요청을 수동으로 추적할 때 애플리케이션 구성 클라이언트 라이브러리가 이 요청의 범위에서 비동기적으로 호출됩니다.

Span span = TRACER.spanBuilder("incoming request").startSpan();
io.opentelemetry.context.Context traceContext = io.opentelemetry.context.Context.root().with(span);

// Put the incoming-request span (wrapped into the OpenTelemetry Context) into the Azure SDK Context
// and pass it over to the Application Configuration call.
appConfigClient.setConfigurationSettingWithResponse(settings, true, new com.azure.core.util.Context("trace-context", traceContext));

// You could also pass the context using the reactor `contextWrite` method under the same `trace-context` key.
appConfigAsyncClient.setConfigurationSettingWithResponse(settings)
   .contextWrite(reactor.util.context.Context.of("trace-context", traceContext))

//...

Azure SDK 추적 규칙

SDK에서 내보내는 범위 및 특성을 확인하려면 Azure SDK 의미 체계 규칙 사양을 참조하세요. Azure SDK(및 OpenTelemetry) 의미 체계 규칙은 안정적이지 않으며 나중에 변경될 수 있습니다.

다음 단계

Java용 Azure SDK의 핵심 교차 기능에 대해 알아보았으므로, 이제 Java 및 Azure Identity로 Azure 인증에서 보안 애플리케이션을 만드는 방법을 알아보세요.