메시지 라우팅 문제 해결
이 문서에서는 IoT Hub 메시지 라우팅에 대한 일반적인 문제를 모니터링하는 방법과 문제 해결 지침을 제공합니다.
메시지 라우팅 모니터링
전송된 메시지의 개요를 파악할 수 있도록 메시지 라우팅 및 엔드포인트와 관련된 IoT Hub 메트릭을 모니터링하는 것이 좋습니다. 또한 진단 설정을 만들어 IoT Hub 리소스 로그 내 경로에 대한 작업을 Azure Monitor 로그, 이벤트 허브 또는 Azure Storage로 전송하여 사용자 지정 처리할 수 있습니다. 메트릭, 리소스 로그 및 진단 설정에 대해 자세히 알아보려면 IoT Hub 모니터링을 참조하세요. 자습서에서는 IoT Hub를 사용하여 메트릭 및 리소스 로그 설정 및 사용을 참조하세요.
또한 어느 경로의 쿼리이든 쿼리와 일치하지 않는 메시지를 유지하려면 대체 경로를 사용하도록 설정하는 것이 좋습니다. 이러한 메시지는 구성된 보존 기간(일)에 대한 기본 제공 엔드포인트에 보존 할 수 있습니다.
주요 문제
다음은 메시지 라우팅과 관련하여 가장 일반적으로 발생하는 문제입니다. 문제 해결을 시작하려면 세부 단계별로 문제를 선택하세요.
내 디바이스의 메시지가 예상대로 라우팅되지 않습니다.
이 문제를 해결하려면 다음 정보를 분석합니다.
이 엔드포인트에 대한 라우팅 메트릭
라우팅과 관련된 모든 IoT Hub 메트릭은 라우팅으로 시작합니다. 여러 메트릭의 정보를 결합하여 문제의 근본 원인을 식별할 수 있습니다. 예를 들어 라우팅 전달 메트릭을 사용하면 엔드포인트에 전달된 메시지의 수 또는 어느 경로의 쿼리이든 쿼리와 일치하지 않고 대체 경로가 사용되지 않았을 때 손실된 메시지의 수를 식별할 수 있습니다. 라우팅 대기 시간 메트릭을 검사하면 메시지 전달 대기 시간이 안정적인지 아니면 증가하는지 확인할 수 있습니다. 대기 시간이 증가하는 것은 특정 엔드포인트에 문제가 있음을 나타낼 수 있으므로 엔드포인트의 상태를 확인하는 것이 좋습니다. 이러한 라우팅 메트릭에는 엔드포인트 유형, 특정 엔드포인트 이름 및 메시지가 전달되지 않는 이유와 같은 메트릭에 대한 세부 정보를 제공하는 차원이 있습니다.
운영 문제에 대한 리소스 로그
경로 리소스 로그를 관찰하여 라우팅 및 엔드포인트 작업에 대한 추가 정보를 얻거나 오류 및 관련 오류 코드를 식별하여 문제를 보다 자세히 이해할 수 있습니다. 예를 들어 로그의 작업 이름 RouteEvaluationError는 메시지 형식의 문제로 인해 경로를 평가할 수 없음을 나타냅니다. 특정 작업 이름에 대해 제공된 팁을 사용하여 문제를 완화할 수 있습니다. 이벤트가 오류로 기록되면 로그는 평가에 실패한 이유에 대한 자세한 정보도 제공합니다. 예를 들어 작업 이름이 EndpointUnhealthy인 경우 오류 코드 403004는 엔드포인트에 공간이 부족했음을 나타냅니다.
엔드포인트의 상태
REST API Get Endpoint Health를 사용하여 엔드포인트의 상태 정보를 가져올 수 있습니다. 또한 이 API는 메시지가 엔드포인트에 성공적으로 전송된 마지막 시간, 마지막으로 알려진 오류, 마지막으로 알려진 오류 시간 및 이 엔드포인트에 대한 전송 시도가 있었던 마지막 시간에 대한 정보를 제공합니다. 특정 마지막으로 알려진 오류에 대해 제공된 완화 방법을 사용하세요.
기본 제공 엔드포인트에서 갑자기 메시지 가져오기가 중단되었습니다.
이 문제를 해결하려면 다음 정보를 분석합니다.
새 경로를 만들었나요?
일단 경로가 생성되면 경로가 해당 엔드포인트에 대해 생성되어 있지 않은 한, 데이터가 기본 제공 엔드포인트로 흐르는 것을 멈춥니다. 새 경로가 추가된 경우에도 메시지가 기본 제공 엔드포인트로 계속 흐르도록 하려면 이벤트 엔드포인트에 대한 경로를 구성합니다.
대체 경로를 비활성화 했나요?
대체 경로는 기존 경로에서 모든 쿼리 조건을 충족하지 않는 모든 메시지를 Event Hubs와 호환되는 기본 제공 Event Hubs(messages/events)로 전송합니다. 메시지 라우팅이 설정되어 있으면 대체 경로 기능을 사용하도록 설정할 수 있습니다. 기본 제공 엔드포인트에 대한 경로가 없고 대체(fallback) 경로를 사용할 수 있는 경우 경로의 모든 쿼리 조건을 충족하지 않는 메시지만 기본 제공 엔드포인트로 전송됩니다. 또한 기존 경로가 모두 삭제된 경우에는 대체(fallback) 경로가 기본 제공 엔드포인트에서 모든 데이터를 수신하도록 설정되어 있어야 합니다.
Azure Portal에서 IoT Hub에 대한 메시지 라우팅 블레이드를 사용하여 대체 경로를 사용 또는 사용 안 함으로 설정할 수 있습니다. FallbackRouteProperties에 Azure Resource Manager를 사용하여 대체(fallback) 경로에 대해 사용자 지정 엔드포인트를 사용할 수도 있습니다.
IoT Hub 라우팅 엔드포인트에 대해 마지막으로 알려진 오류
REST API에서 엔드포인트 상태 가져오기는 엔드포인트의 상태와 마지막으로 알려진 오류를 제공하여 엔드포인트가 정상이 아닌 이유를 식별합니다. 이 표에는 가장 일반적인 오류가 나열되어 있습니다.
| 마지막으로 알려진 오류 | 설명/발생 시기 | 가능한 완화 방법 |
|---|---|---|
| Transient | 일시적인 오류가 발생하여 IoT Hub가 작업을 다시 시도합니다. | 경로 리소스 로그를 관찰합니다. |
| InternalError | 엔드포인트에 메시지를 전달하는 동안 오류가 발생했습니다. | 이 오류는 내부 예외이지만 경로 리소스 로그도 관찰합니다. |
| Unauthorized | IoT Hub는 지정된 엔드포인트에 메시지를 보낼 권한이 없습니다. | 엔드포인트에 대한 연결 문자열이 최신 상태인지 확인합니다. 변경된 경우 IoT Hub에 대한 업데이트를 고려하세요. 엔드포인트에서 관리 ID를 사용하는 경우 IoT Hub 보안 주체에 대상에 대한 필수 권한이 있는지 확인합니다. |
| Throttled | IoT Hub는 엔드포인트에 메시지를 쓰는 동안 제한됩니다. | 영향을 받는 엔드포인트의 제한 한도를 검토합니다. 필요에 따라 확장할 엔드포인트의 구성을 수정합니다. |
| 시간 제한 | 작업 시간이 초과되었습니다. | 작업을 다시 시도하세요. |
| Not Found | 대상 리소스가 없습니다. | 대상 리소스가 있는지 확인합니다. |
| 컨테이너를 찾을 수 없음 | 스토리지 컨테이너가 존재하지 않습니다. | 스토리지 컨테이너가 있는지 확인합니다. |
| 컨테이너 사용 안 함 | 스토리지 컨테이너가 비활성화되었습니다. | 스토리지 컨테이너가 활성화되었는지 확인합니다. |
| MaxMessageSizeExceeded | 메시지 라우팅의 메시지 크기 제한은 256Kb입니다. 라우팅되는 메시지 크기가 이 제한을 초과했습니다. | 더 적은 애플리케이션 속성을 사용하거나 더 적은 메시지 강화를 사용하여 메시지 크기를 줄일 수 있는지 확인합니다. |
| PartitioningAndDuplicateDetectionNotSupported | Service Bus에 중복 검색이 활성화되어 있지 않을 수 있습니다. | Service Bus에서 중복 검색을 비활성화하거나 중복 검색 없이 엔터티를 사용하는 것을 고려하세요. |
| SessionfulEntityNotSupported | Service Bus에 세션이 활성화되어 있지 않을 수 있습니다. | Service Bus에서 세션을 비활성화하거나 세션이 없이 엔터티를 사용하는 것을 고려하세요. |
| NoMatchingSubscriptionsForMessage | Service Bus 토픽에 메시지를 쓸 구독이 없습니다. | 라우팅할 IoT Hub 메시지에 대한 구독을 만듭니다. |
| EndpointExternallyDisabled | 엔드포인트가 활성 상태가 아니므로 IoT Hub에서 메시지를 보낼 수 있습니다. | 엔드포인트를 활성 상태로 전환되도록 설정합니다. |
| DeviceMaximumQueueDepthExceeded | Service Bus 크기 제한에 도달했습니다. | 새 메시지를 Event Hubs로 수집할 수 있도록 대상 Event Hubs에서 메시지를 제거하는 것이 좋습니다. |
경로 리소스 로그
다음은 경로 리소스 로그에 기록된 작업 이름 및 오류 코드입니다.
작업 이름
| 작업 이름 | 수준 | 설명 |
|---|---|---|
| UndefinedRouteEvaluation | 정보 | 메시지를 지정된 조건으로 평가할 수 없습니다. 예를 들어 경로 쿼리 조건의 속성이 메시지에 없는 경우입니다. 쿼리 구문 라우팅에 대해 자세히 알아보세요. |
| RouteEvaluationError | 오류 | 메시지 형식 문제로 인해 메시지를 평가하는 동안 오류가 발생했습니다. 예를 들어 콘텐츠 인코딩이 지정되지 않았거나 메시지에서 콘텐츠 형식이 유효하지 않은 경우 이 오류가 기록됩니다. 시스템 속성에서 설정해야 합니다. |
| DroppedMessage | 오류 | 메시지가 삭제되었으며 라우팅되지 않습니다. 이는 메시지가 라우팅 쿼리와 일치하지 않거나 엔드포인트가 중단되었고 몇 번의 재시도 후 메시지를 전달할 수 없는 등의 이유로 인해 발생할 수 있습니다. 엔포인트 상태 가져오기 REST API를 사용하여 엔드포인트에 대한 자세한 정보를 가져오는 것이 좋습니다. |
| EndpointUnhealthy | 오류 | 엔드포인트가 IoT Hub의 메시지를 수락하지 않았으므로 IoT Hub 메시지를 다시 보내려고 합니다. REST API 엔드포인트 상태 가져오기를 통해 마지막으로 알려진 오류를 확인하는 것이 좋습니다. |
| EndpointDead | 오류 | 엔드포인트가 한 시간 넘게 IoT Hub의 메시지를 수락하지 않았습니다. REST API 엔드포인트 상태 가져오기를 통해 마지막으로 알려진 오류를 확인하는 것이 좋습니다. |
| EndpointHealthy | 정보 | 엔드포인트가 정상이며 IoT Hub에서 메시지를 수신합니다. 이 메시지는 지속적으로 기록되지 않지만 엔드포인트가 다시 정상 상태가 될 때만 기록됩니다. 이 메시지는 IoT Hub가 엔드포인트에 메시지를 보낼 수 없었지만 이제 엔드포인트가 정상 상태임을 의미합니다. |
| OrphanedMessage | 정보 | 메시지가 어떤 경로와도 일치하지 않습니다. |
| InvalidMessage | 오류 | 엔드포인트와 호환되지 않아 메시지가 잘못되었습니다. 엔드포인트의 구성을 확인하는 것이 좋습니다. |
UndefinedRouteEvaluation, RouteEvaluationError 및 OrphanedMessage 작업이 제한되어 IoT Hub당 1분에 한 번만 기록됩니다.
일반적인 오류 코드
| 오류 코드 | 설명 |
|---|---|
| 401002 | Iot Hub 무단 액세스 |
| 413001 | 메시지가 너무 큼 |
| 403004 | 디바이스 최대 큐 크기를 초과했음 |
| 503008 | 수신 링크가 제한됨 |
| 500000 | 일반 서버 오류 |
| 401 | Unauthorized |
| 503 | Service Unavailable |
| 500001 | 서버 오류 |
| 400103 | 잘못된 콘텐츠 인코딩 또는 콘텐츠 형식 |
| 404001 | 디바이스를 찾을 수 없음 |
다음 단계
도움이 더 필요하면 Microsoft Q&A 및 Stack Overflow 포럼의 Azure 전문가에게 문의하세요. 또는 Azure 기술 지원 인시던트를 제출할 수 있습니다. Azure 지원 사이트 로 가서 지원 받기를 선택합니다.