다음을 통해 공유

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

권한 문제

AmqpExceptionAmqpErrorCondition이 amqp:unauthorized-access 있는 경우 제공된 자격 증명은 Event Hubs로 작업(수신 또는 보내기)을 수행할 수 없습니다. 이 문제를 해결하려면 다음 작업을 수행합니다.

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

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

연결 문제

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

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

  • 클라이언트를 만들 때 지정된 연결 문자열 또는 정규화된 do기본 이름이 올바른지 확인합니다. 자세한 내용은 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 클라이언트 라이브러리에서 직접 사용할 수 없습니다. IoT커넥트ionString.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. 로깅 샘플 pom.xml의 종속성을 사용하여 pom.xml의 종속성을 "Log4j2에 필요한 종속성" 섹션에 추가합니다.
  2. src/기본/resources 폴더에 log4j2.xml을 추가합니다.

로그백 구성

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

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

AMQP 전송 로깅 사용

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

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

샘플 "logging.properties" 파일

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

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.eventhubscom.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 클라이언트 라이브러리를 사용할 때 문제를 해결하는 데 도움이 되지 않는 경우 Java GitHub 리포지토리용 Azure SDK에 문제를 제출하는 것이 좋습니다.