분산 추적을 사용하여 Azure IoT 디바이스-클라우드 메시지 추적(미리 보기)

아티클
03/08/2024

IoT Hub에서 분산 추적(미리 보기)을 사용하여 IoT 메시지가 Azure 서비스를 통과할 때 모니터링합니다. IoT Hub는 분산 추적을 지원하기 위한 첫 번째 Azure 서비스 중 하나입니다. 더 많은 Azure 서비스가 분산 추적을 지원하므로 솔루션에 관련된 Azure 서비스 전체에서 IoT(사물 인터넷) 메시지를 추적할 수 있습니다. 이 기능에 대한 자세한 내용은 분산 추적이란?을 참조하세요.

IoT Hub에 대한 분산 추적을 사용하도록 설정하면 다음을 수행할 수 있습니다.

추적 컨텍스트를 사용하여 IoT Hub를 통해 각 메시지의 흐름을 모니터링합니다. 추적 컨텍스트는 한 구성 요소의 이벤트와 다른 구성 요소의 이벤트 간에 상관 관계를 지정할 수 있는 상관 관계 ID를 포함합니다. 디바이스 쌍을 사용하여 하위 집합 또는 모든 IoT 디바이스 메시지에 추적 컨텍스트를 적용할 수 있습니다.
추적 컨텍스트를 Azure Monitor 로그에 기록합니다.
디바이스에서 IoT Hub 및 라우팅 엔드포인트로의 메시지 흐름과 대기 시간을 측정하고 이해합니다.

Important

Azure IoT Hub의 분산 추적은 현재 미리 보기 상태입니다. 베타, 미리 보기로 제공되거나 아직 일반 공급으로 릴리스되지 않은 Azure 기능에 적용되는 약관은 Microsoft Azure 미리 보기에 대한 추가 사용 약관을 참조하세요.

필수 조건

다음 지역 중 하나에서 만들어진 Azure IoT 허브입니다.
- 북유럽
- 동남 아시아
- 미국 서부 2
IoT Hub에 등록된 디바이스. IoT 허브에 디바이스가 없으면 디바이스 등록의 단계를 따르고 이 문서에서 사용할 디바이스 연결 문자열을 저장합니다.
이 문서에서는 사용자가 IoT Hub로 원격 분석 메시지를 전송하는 방법을 잘 알고 있다고 가정합니다.
Git의 최신 버전입니다.

공개 미리 보기 제한 및 고려 사항

이 미리 보기 기능이 시나리오에 적합한지 확인하려면 다음 제한 사항을 고려합니다.

W3C 추적 컨텍스트 표준에 대한 제안은 현재 작업 초안입니다.
클라이언트 SDK가 현재 지원하는 유일한 개발 언어는 C용 Azure IoT 디바이스 SDK의 공개 미리 보기 분기에 있는 C입니다.
IoT Hub 기본 계층에서는 클라우드-디바이스 쌍 기능을 사용할 수 없습니다. 그러나 IoT Hub는 적절히 구성된 추적 컨텍스트 헤더가 있으면 Azure Monitor에 기록됩니다.
효율적인 작업을 위해 IoT Hub는 분산 추적의 일부로 발생할 수 있는 로깅 속도를 제한합니다.
분산 추적 기능은 다음 지역에서 만들어진 IoT 허브에 대해서만 지원됩니다.
- 북유럽
- 동남 아시아
- 미국 서부 2

Azure IoT 분산 추적 이해

Azure IoT 참조 아키텍처를 포함한 많은 IoT 솔루션은 일반적으로 마이크로 서비스 아키텍처의 변형을 따릅니다. IoT 솔루션이 좀 더 복잡해지면서 결과적으로 수십 개가 넘는 마이크로 서비스를 사용하게 됩니다. 이 마이크로 서비스는 Azure에서 제공된 것일 수도 있고 그렇지 않을 수도 있습니다.

IoT 메시지가 삭제되거나 느려지는 지점을 찾아내는 일은 어려워질 수 있습니다. 예를 들어, 5개의 다른 Azure 서비스와 1,500개의 활성 디바이스를 사용하는 IoT 솔루션이 있다고 가정합니다. 각 디바이스는 초당 총 15,000개의 메시지에 대해 초당 10개의 디바이스-클라우드 메시지를 보냅니다. 그러나 웹앱에는 초당 10,000개 메시지만 표시됩니다. 원인은 어떻게 찾을 수 있을까요?

여러 서비스에서 IoT 메시지의 흐름을 다시 구성하려면 각 서비스가 메시지를 고유하게 식별하는 상관 관계 ID를 전파해야 합니다. Azure Monitor가 중앙 집중식 시스템에서 상관 관계 ID를 수집한 후 해당 ID를 사용하여 메시지 흐름을 볼 수 있습니다. 이 방법을 분산 추적 패턴이라고 합니다.

분산 추적이 보다 광범위하게 채택되도록 하기 위해 Microsoft는 분산 추적에 대한 W3C 표준 제안에 참가하고 있습니다. IoT Hub에 대한 분산 추적 지원이 사용하도록 설정되면 생성된 각 메시지에 대해 다음 흐름을 따릅니다.

메시지가 IoT 디바이스에서 생성됩니다.
IoT 디바이스가 클라우드의 지원을 받아, 이 메시지에 추적 컨텍스트를 할당해야 하는지 결정합니다.
SDK는 메시지 생성을 위한 타임스탬프를 포함하는 tracestate 값을 메시지 속성에 추가합니다.
IoT 디바이스는 IoT Hub에 메시지를 보냅니다.
메시지가 IoT Hub 게이트웨이에 도착합니다.
IoT Hub가 메시지 속성에서 tracestate 값을 검색하고 올바른 형식인지 확인합니다. 올바른 형식이면 메시지에 대한 전역으로 고유한 trace-id 값과 “홉”에 대한 span-id 값을 생성합니다. IoT Hub는 DiagnosticIoTHubD2C 작업에서 IoT Hub 분산 추적 로그에 이 값을 기록합니다.
메시지 처리가 완료되면 IoT Hub는 DiagnosticIoTHubIngress 작업에서 기존 trace-id 값과 함께 다른 span-id 값을 생성하고 로그합니다.
메시지에 대한 라우팅을 사용하도록 설정하면, IoT Hub는 사용자 지정 엔드포인트에 씁니다. IoT Hub는 DiagnosticIoTHubEgress 범주 아래에 동일한 trace-id 값과 함께 또 다른 span-id 값을 로그합니다.

IoT 허브에서 분산 추적 구성

이 섹션에서는 분산 추적 특성(상관 관계 ID 및 타임스탬프)을 로그하도록 IoT 허브를 구성합니다.

Azure Portal에서 IoT 허브로 이동합니다.
IoT 허브의 왼쪽 창에서 모니터링 섹션으로 아래로 스크롤하고 진단 설정을 선택합니다.
진단 설정 추가를 선택합니다.
진단 설정 이름 상자에 새 진단 설정의 이름을 입력합니다. 예를 들어, DistributedTracingSettings를 입력합니다.
대상 세부 정보에서 다음 옵션 중 하나 이상을 선택하여 로깅 정보 전송 위치를 결정합니다.
- 스토리지 계정에 보관: 로깅 정보를 포함하도록 스토리지 계정을 구성합니다.
- 이벤트 허브로 스트림: 로깅 정보를 포함하도록 이벤트 허브를 구성합니다.
- Log Analytics에 보내기: 로깅 정보를 포함하도록 Log Analytics 작업 영역을 구성합니다.
로그 섹션에서 로그하려는 작업을 선택합니다.

분산 추적을 포함하고 로깅을 보존하려는 기간(일)으로 보존 기간을 구성합니다. 로그 보존은 스토리지 비용에 영향을 줍니다.
저장을 선택합니다.
(선택 사항) 다른 위치에 대한 메시지 흐름을 보려면 두 개 이상의 다른 엔드포인트에 대한 라우팅 규칙을 설정합니다.

로깅이 켜진 후 IoT Hub는 다음 상황에서 유효한 추적 속성을 포함하는 메시지가 발생할 때 로그를 기록합니다.

메시지가 IoT 허브의 게이트웨이에 도착합니다.
IoT 허브는 메시지를 처리합니다.
메시지가 사용자 지정 엔드포인트로 라우팅됩니다. 라우팅을 사용하도록 설정해야 합니다.

해당 로그 및 해당 스키마에 관한 자세한 내용은 IoT Hub 모니터링 및 IoT Hub 리소스 로그의 분산 추적을 참조하세요.

샘플링 옵션 업데이트

클라우드에서 추적할 메시지의 비율을 변경하려면 디바이스 쌍을 업데이트해야 합니다. Azure Portal 또는 IoT Hub 서비스 SDK에서 JSON 편집기를 사용하여 업데이트할 수 있습니다. 다음 하위 섹션에서 예제를 제공합니다.

단일 디바이스 업데이트

Azure Portal 또는 VS Code(Visual Studio Code)용 Azure IoT Hub 확장을 사용하여 단일 디바이스의 샘플링 속도를 업데이트할 수 있습니다.

Azure Portal
VS Code

Azure Portal의 IoT 허브로 이동한 다음 메뉴의 디바이스 관리 섹션에서 디바이스를 선택합니다.
디바이스를 선택합니다.
분산 추적(미리 보기)에서 기어 아이콘을 선택합니다. 열리는 패널에서:
1. 사용 옵션을 선택합니다.
2. 샘플링 속도의 경우 0~100 사이 백분율을 선택합니다.
3. 저장을 선택합니다.
몇 초 정도 기다렸다가 새로 고침을 선택합니다. 디바이스에서 변경 내용을 성공적으로 승인하면 확인 표시가 있는 동기화 아이콘이 나타납니다.

여러 디바이스 일괄 업데이트

여러 디바이스에 대해 분산 추적 샘플링 구성을 업데이트하려면 자동 디바이스 구성을 사용합니다. 다음 쌍 스키마를 따릅니다.

{
    "properties": {
        "desired": {
            "azureiot*com^dtracing^1": {
                "sampling_mode": 1,
                "sampling_rate": 100
            }
        }
    }
}

요소 이름	필수	Type	설명
`sampling_mode`	예	정수	샘플링을 켜고 끄기 위해 현재 두 가지 모드 값이 지원됩니다. `1`은 켜기이고 `2`는 끄기입니다.
`sampling_rate`	예	정수	이 값은 백분율입니다. `0`~`100`(경계값 포함) 사이의 값만 허용됩니다.

추적 쿼리 및 시각화

IoT Hub에서 기록된 모든 추적을 보려면 진단 설정에서 선택한 로그 저장소를 쿼리합니다. 이 섹션에서는 Log Analytics를 사용하여 쿼리하는 방법을 보여 줍니다.

리소스 로그를 사용하여 Log Analytics를 설정한 경우 DistributedTracing 범주에서 로그를 찾아 쿼리합니다. 예를 들어, 이 쿼리는 로그된 모든 추적을 보여 줍니다.

// All distributed traces 
AzureDiagnostics 
| where Category == "DistributedTracing" 
| project TimeGenerated, Category, OperationName, Level, CorrelationId, DurationMs, properties_s 
| order by TimeGenerated asc

Log Analytics의 몇 가지 예제 로그는 다음과 같습니다.

생성 시간	작업 이름	Category	Level	상관 관계 ID	기간(밀리초)	속성
2018-02-22T03:28:28.633Z	DiagnosticIoTHubD2C	DistributedTracing	Informational	00-8cd869a412459a25f5b4f31311223344-0144d2590aacd909-01		`{"deviceId":"AZ3166","messageSize":"96","callerLocalTimeUtc":"2018-02-22T03:27:28.633Z","calleeLocalTimeUtc":"2018-02-22T03:27:28.687Z"}`
2018-02-22T03:28:38.633Z	DiagnosticIoTHubIngress	DistributedTracing	Informational	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	20	`{"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"}`
2018-02-22T03:28:48.633Z	DiagnosticIoTHubEgress	DistributedTracing	Informational	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	23	`{"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"}`

다양한 유형의 로그를 이해하려면 Azure IoT Hub 분산 추적 로그를 참조하세요.

샘플 애플리케이션 실행

이 섹션에서는 Azure IoT C SDK를 빌드하는 데 사용할 개발 환경을 준비합니다. 그런 다음, 샘플 중 하나를 수정하여 디바이스의 원격 분석 메시지에서 분산 추적을 사용하도록 설정합니다.

이러한 지침은 Windows에서 샘플을 빌드하기 위한 것입니다. 다른 환경에 대해서는 C SDK 컴파일 또는 플랫폼 특정 개발용 사전 패키지 C SDK를 참조하세요.

소스 코드를 복제 및 초기화

Visual Studio 2022용 C++를 사용한 데스크톱 개발 워크로드를 설치합니다. Visual Studio 2019도 지원됩니다.
CMake를 설치합니다. 명령 프롬프트에서 cmake -version를 입력하여 PATH에 있는지 확인합니다.
명령 프롬프트 또는 Git Bash 셸을 엽니다. 다음 명령을 실행하여 Azure IoT C SDK GitHub 리포지토리 공용 미리 보기 분기의 최신 릴리스를 복제합니다.
```
git clone -b public-preview https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init
```
이 작업을 완료하는 데 몇 분 정도가 걸립니다.
azure-iot-sdk-c 디렉터리에서 다음 명령을 실행하여 cmake 하위 디렉터리를 만들고 cmake 폴더로 이동합니다.
```
mkdir cmake
cd cmake
cmake ..
```
CMake에서 C++ 컴파일러를 찾을 수 없으면 이전 명령을 실행하는 동안 빌드 오류가 발생할 수 있습니다. 이 경우에는 Visual Studio 명령 프롬프트에서 명령을 실행합니다.

빌드가 성공한 후 마지막 몇몇 출력 줄은 다음 출력과 유사하게 표시됩니다.
```
$ cmake ..
-- Building for: Visual Studio 15 2017
-- Selecting Windows SDK version 10.0.16299.0 to target Windows 10.0.17134.
-- The C compiler identification is MSVC 19.12.25835.0
-- The CXX compiler identification is MSVC 19.12.25835.0

...

-- Configuring done
-- Generating done
-- Build files have been written to: E:/IoT Testing/azure-iot-sdk-c/cmake
```

분산 추적을 사용하도록 원격 분석 샘플 편집

이 섹션에서는 SDK 리포지토리의 iothub_ll_telemetry_sample.c 샘플을 편집하여 분산 추적을 사용하도록 설정합니다. 또는 azure-iot-distributed-tracing-sample 리포지토리에서 이미 편집된 버전의 샘플을 복사할 수 있습니다.

편집기를 사용하여 azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c 소스 파일을 엽니다.

connectionString 상수의 선언을 찾습니다.

/* Paste in the your iothub connection string  */
static const char* connectionString = "[device connection string]";
#define MESSAGE_COUNT        5000
static bool g_continueRunning = true;
static size_t g_message_count_send_confirmations = 0;

connectionString 상수 값을 원격 분석 보내기에 대한 빠른 시작의 디바이스 등록 섹션에서 저장한 디바이스 연결 문자열로 바꿉니다.

IoTHubDeviceClient_LL_SetConnectionStatusCallback을 호출하는 코드의 줄을 찾아 메시지 보내기 루프 이전에 연결 상태 콜백 함수를 등록합니다. 해당 줄 아래에 코드를 추가하여 IoTHubDeviceClient_LL_EnablePolicyConfiguration을 호출하고 디바이스의 분산 추적을 사용하도록 설정합니다.
```
// Setting connection status callback to get indication of connection to iothub
(void)IoTHubDeviceClient_LL_SetConnectionStatusCallback(device_ll_handle, connection_status_callback, NULL);

// Enabled the distrubted tracing policy for the device
(void)IoTHubDeviceClient_LL_EnablePolicyConfiguration(device_ll_handle, POLICY_CONFIGURATION_DISTRIBUTED_TRACING, true);

do
{
    if (messages_sent < MESSAGE_COUNT)
```
IoTHubDeviceClient_LL_EnablePolicyConfiguration 함수는 디바이스 쌍을 통해 구성된 특정 IoT Hub 기능에 대한 정책을 사용하도록 설정합니다. 추가 코드 줄을 사용하여 POLICY_CONFIGURATION_DISTRIBUTED_TRACING을 사용하도록 설정한 후 디바이스의 추적 동작은 디바이스 쌍에 대해 수행된 분산 추적 변경 내용을 반영합니다.

할당량을 다 사용하지는 않으면서 샘플 앱을 계속 실행하려면 메시지 보내기 루프 끝에 1초의 지연을 추가합니다.

    else if (g_message_count_send_confirmations >= MESSAGE_COUNT)
    {
        // After all messages are all received stop running
        g_continueRunning = false;
    }

    IoTHubDeviceClient_LL_DoWork(device_ll_handle);
    ThreadAPI_Sleep(1000);

} while (g_continueRunning);

컴파일 및 실행

이전에 만든 CMake 디렉터리(azure-iot-sdk-c/cmake)에서 iothub_ll_telemetry_sample 프로젝트 디렉터리로 이동하고 샘플을 컴파일합니다.
```
cd iothub_client/samples/iothub_ll_telemetry_sample
cmake --build . --target iothub_ll_telemetry_sample --config Debug
```
애플리케이션을 실행합니다. 디바이스는 분산 추적을 지원하는 원격 분석을 보냅니다.
```
Debug/iothub_ll_telemetry_sample.exe
```
앱이 계속 실행되게 합니다. 콘솔 창에서 IoT Hub로 전송되는 메시지를 관찰할 수 있습니다.

클라우드에서 샘플링 결정을 수신할 수 있는 클라이언트 앱의 경우 분산 추적 샘플 리포지토리에서 iothub_devicetwin_sample.c 샘플을 사용해 보세요.

Microsoft 이외의 클라이언트에 대한 해결 방법

C SDK를 사용하지 않고 분산 추적 기능을 구현하는 것이 더 복잡합니다. 이는 권장되지 않습니다.

먼저 개발자 가이드 IoT Hub 메시지 만들기 및 읽기에 따라 메시지의 모든 IoT Hub 프로토콜 기본 요소를 구현해야 합니다. 그런 다음, MQTT 및 AMQP 메시지에서 프로토콜 속성을 편집하여 tracestate를 시스템 속성으로 추가합니다.

특별한 사항

MQTT의 경우 메시지 토픽에 %24.tracestate=timestamp%3d1539243209를 추가합니다. 1539243209를 Unix 타임스탬프 형식의 메시지 생성 시간으로 바꿉니다. 예제는 C SDK의 구현을 참조하세요.
AMQP의 경우 key("tracestate") 및 value("timestamp=1539243209")를 메시지 주석으로 추가합니다. 참조 구현은 uamqp_messaging.c 파일을 참조하세요.

이 속성을 포함하는 메시지의 백분율을 제어하려면 쌍 업데이트와 같은 클라우드 시작 이벤트를 수신 대기하는 논리를 구현합니다.

다음 단계

마이크로 서비스의 일반 분산 추적 패턴에 대한 자세한 내용은 마이크로 서비스 아키텍처 패턴: 분산 추적을 참조하세요.

다음을 통해 공유