다음을 통해 공유

Azure Event Hubs 문제 해결

이 문서에서는 오류 조사 기술, Event Hubs 라이브러리의 자격 증명 유형에 대한 일반적인 오류 및 이러한 오류를 해결하기 위한 완화 단계를 설명합니다. Event Hubs 사용 사례에 관계없이 적용되는 일반적인 문제 해결 기술 및 지침 외에도 다음 문서에서는 Event Hubs 라이브러리의 특정 기능을 다룹니다.

이 문서의 나머지 부분에서는 Event Hubs 라이브러리의 모든 사용자에게 적용되는 일반적인 문제 해결 기술 및 지침을 다룹니다.

Event Hubs 예외 처리

모든 Event Hubs 예외는 AmqpException에 포함됩니다. 이러한 예외에는 오류를 다시 시도해야 하는지 여부를 지정하는 기본 AMQP 오류 코드가 있는 경우가 많습니다. 다시 시도 가능한 오류(즉, amqp:connection:forced 또는 amqp:link:detach-forced)의 경우 클라이언트 라이브러리는 클라이언트를 인스턴스화할 때 지정된 재시도 옵션에 따라 이러한 오류로부터 복구하려고 시도합니다. 다시 시도 옵션을 구성하려면 샘플 을 따라 특정 파티션에 이벤트를 게시하십시오. 오류가 재시도할 수 없는 경우, 해결해야 할 몇 가지 구성 문제가 있습니다.

AMQP 예외가 나타내는 특정 예외를 해결하는 권장 방법은 Event Hubs 메시징 예외 지침을 따르는 것입니다.

예외 메시지에서 관련 정보 찾기

AmqpException 오류를 설명하는 다음 세 개의 필드가 포함되어 있습니다.

  • getErrorCondition: 근본적인 AMQP 오류입니다. 오류에 대한 설명은 AmqpErrorCondition 열거형 문서나 OASIS AMQP 1.0 사양을 참조하십시오.
  • isTransient: 동일한 작업을 수행할 수 있는지 여부를 나타내는 값입니다. SDK 클라이언트는 오류가 일시적일 때 재시도 정책을 적용합니다.
  • getErrorContext: AMQP 오류가 발생한 위치에 대한 다음 정보를 포함합니다.

일반적으로 발생하는 예외

amqp:connection:forced 및 amqp:link:detach-forced

Event Hubs에 대한 연결이 유휴 상태이면 서비스가 잠시 후 클라이언트의 연결을 끊습니다. 서비스 작업이 요청되면 클라이언트가 연결을 다시 설정하기 때문에 이 문제는 문제가 되지 않습니다. 자세한 내용은 AMQP 오류에 대해 Azure Service Bus을 참조하세요.

권한 문제

AmqpException에서 AmqpErrorCondition의 amqp:unauthorized-access은(는) 제공된 자격 증명이 Event Hubs에서 동작(수신 또는 송신)을 수행할 수 없음을 의미합니다. 이 문제를 해결하려면 다음 작업을 수행합니다.

  • 올바른 연결 문자열이 있는지 다시 확인합니다. 자세한 내용은 Event Hubs 연결 문자열가져오기를 참조하세요.
  • SAS(공유 액세스 서명) 토큰이 올바르게 생성되었는지 확인합니다. 자세한 내용은 공유 액세스 서명사용하여 Event Hubs 리소스에 대한 액세스 권한 부여를 참조하세요.

다른 가능한 해결 방법은 Event Hubs인증 및 권한 부여 문제 해결을 참조하세요.

연결 문제

서비스에 연결할 때 시간 제한

시간 제한 문제를 해결하려면 다음 작업을 수행합니다.

  • 클라이언트를 만들 때 지정된 연결 문자열 또는 정규화된 도메인 이름이 올바른지 확인합니다. 자세한 내용은 Event Hubs 연결 문자열가져오기를 참조하세요.
  • 호스팅 환경에서 방화벽 및 포트 권한을 확인하고 AMQP 포트 5671 및 5762가 열려 있는지 확인합니다.
    • 방화벽을 통해 엔드포인트가 허용되는지 확인합니다.
  • 포트 443에서 연결하는 WebSockets를 사용해 보세요. 자세한 내용은 PublishEventsWithWebSocketsAndProxy.java 샘플을 참조하세요.
  • 네트워크에서 특정 IP 주소를 차단하고 있는지 확인합니다. 자세한 내용은 허용해야 하는 IP 주소를 참조하세요.
  • 해당하는 경우 프록시 구성을 확인합니다. 자세한 내용은 PublishEventsWithWebSocketsAndProxy.java 샘플을 참조하세요.
  • 네트워크 연결 문제 해결에 대한 자세한 내용은 연결 문제 해결 - Azure Event Hubs참조하세요.

TLS/SSL 핸드셰이크 오류

이 오류는 절편 프록시를 사용할 때 발생할 수 있습니다. 확인하려면 프록시를 사용하지 않도록 설정한 상태에서 호스팅 환경에서 테스트하는 것이 좋습니다.

소켓 고갈 오류

애플리케이션은 Event Hubs 클라이언트를 싱글톤으로 처리하고 애플리케이션 수명 동안 단일 인스턴스를 만들고 사용하는 것을 선호해야 합니다. 각 클라이언트 유형이 연결을 관리하기 때문에 이 권장 사항이 중요합니다. 새 Event Hubs 클라이언트를 만들면 소켓을 사용하는 새 AMQP 연결이 생성됩니다. 또한 클라이언트가 java.io.Closeable상속해야 하므로 애플리케이션은 클라이언트 사용을 완료할 때 close() 호출해야 합니다.

여러 클라이언트를 만들 때 동일한 AMQP 연결을 사용하려면 EventHubClientBuilder.shareConnection() 플래그를 사용하고, 해당 EventHubClientBuilder대한 참조를 유지하고, 동일한 작성기 인스턴스에서 새 클라이언트를 만들 수 있습니다.

IoT 연결 문자열을 사용하여 연결

연결 문자열을 변환하려면 IoT Hub 서비스를 쿼리해야 하므로 Event Hubs 클라이언트 라이브러리는 직접 사용할 수 없습니다. IoTConnectionString.java 샘플에서는 IoT Hub를 쿼리하여 IoT 연결 문자열을 Event Hubs와 함께 사용할 수 있는 문자열로 변환하는 방법을 설명합니다.

자세한 내용은 다음 문서를 참조하세요.

연결 문자열에 구성 요소를 추가할 수 없습니다.

레거시 Event Hubs 클라이언트를 통해 고객은 Azure Portal에서 검색된 연결 문자열에 구성 요소를 추가할 수 있습니다. 레거시 클라이언트는 com.microsoft.azure:azure-eventhubs 패키지와 com.microsoft.azure:azure-eventhubs-eph 패키지 및에 있습니다. 현재 세대는 Azure Portal에서 게시한 양식에서만 연결 문자열을 지원합니다.

"TransportType=AmqpWebSockets" 추가

웹 소켓을 사용하려면 PublishEventsWithSocketsAndProxy.java 샘플을 참조하세요.

"Authentication=Managed Identity"을 추가하세요.

관리 ID를 사용하여 인증하려면 샘플 PublishEventsWithAzureIdentity.java참조하세요.

Azure.Identity 라이브러리에 대한 자세한 내용은 인증 및 Azure SDK 블로그 게시물을 확인하세요.

로깅 사용 및 구성

Java용 Azure SDK는 애플리케이션 오류 문제를 해결하고 해결을 신속하게 하는 데 도움이 되는 일관된 로깅 스토리를 제공합니다. 생성된 로그는 근본 문제를 찾는 데 도움이 되도록 터미널 상태에 도달하기 전에 애플리케이션의 흐름을 캡처합니다. 로깅에 대한 지침은 Java용 Azure SDK 구성 및 문제 해결 개요참조하세요.

로깅을 사용하도록 설정하는 것 외에도 로그 수준을 VERBOSE 또는 DEBUG 설정하면 라이브러리의 상태에 대한 인사이트를 제공합니다. 다음 섹션에서는 상세 로깅이 사용될 때 과도한 메시지를 줄이도록 하는 log4j2 및 logback의 샘플 구성을 보여 줍니다.

Log4J 2 구성

다음 단계를 사용하여 Log4J 2를 구성합니다.

  1. "Log4j2에 필요한 종속성" 섹션의 로깅 샘플 pom.xml에서 사용하는 종속성을 활용하여 pom.xml에 종속성을 추가합니다.
  2. log4j2.xml를 src/main/resources 폴더에 추가합니다.

로그백 구성

다음 단계를 사용하여 로그백을 구성합니다.

  1. 로깅 샘플 pom.xml의 "로그백에 필요한 종속성" 섹션에 있는 종속성을 사용하여 pom.xml에 종속성을 추가합니다.
  2. logback.xml를 src/main/resources 폴더에 추가하세요.

AMQP 전송의 로깅 활성화

클라이언트 로깅을 사용해도 문제를 진단하기에 충분하지 않다면, 기본 AMQP 라이브러리 Qpid Proton-J의 파일로 로깅을 사용할 수 있습니다. Qpid Proton-J java.util.logging사용합니다. 다음 섹션에 표시된 내용이 포함된 구성 파일을 만들어 로깅을 사용하도록 설정할 수 있습니다. 또는 proton.trace.level=ALL 구현에 대해 java.util.logging.Handler 및 원하는 구성 옵션을 설정합니다. 구현 클래스 및 해당 옵션은 Java 8 SDK 설명서의 Package java.util.logging 참조하세요.

AMQP 전송 프레임을 추적하려면 PN_TRACE_FRM=1 환경 변수를 설정합니다.

샘플 "logging.properties" 파일

다음 구성 파일은 Proton-J의 TRACE 수준 출력을 proton-trace.log 파일에 기록합니다.

handlers=java.util.logging.FileHandler
.level=OFF
proton.trace.level=ALL
java.util.logging.FileHandler.level=ALL
java.util.logging.FileHandler.pattern=proton-trace.log
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format=[%1$tF %1$tr] %3$s %4$s: %5$s %n

벌목 줄이기

로그의 양을 줄이는 한 가지 방법은 상세 수준을 변경하는 것입니다. 또 다른 방법은 com.azure.messaging.eventhubs 또는 com.azure.core.amqp같은 로거 이름 패키지에서 로그를 제외하는 필터를 추가하는 것입니다. 예제는 Log4J 2 설정 및 로그백 설정 섹션의 XML 파일을 참조하세요.

버그를 제출할 때 다음 패키지의 클래스에서 보내는 로그 메시지는 흥미롭습니다.

  • com.azure.core.amqp.implementation
  • com.azure.core.amqp.implementation.handler
    • 예외적으로 onDelivery에 있는 ReceiveLinkHandler 메시지를 무시할 수 있습니다.
  • com.azure.messaging.eventhubs.implementation

다음 단계

문제 해결을 위한 이 문서의 지침이 Java용 Azure SDK 클라이언트 라이브러리에 대한 문제를 해결하는 데 도움이 되지 않는 경우, Azure SDK for Java GitHub 리포지토리에 문제를 하시기 바랍니다.

  • Last updated on