Трассировка сообщений устройства в облако Azure IoT с помощью распределенной трассировки (предварительная версия)

Используйте распределенную трассировку (предварительная версия) в Центр Интернета вещей для мониторинга сообщений Интернета вещей при передаче через службы Azure. Центр Интернета вещей — это одна из первых служб Azure, поддерживающих функцию распределенной трассировки. Так как службы Azure поддерживают распределенную трассировку, вы можете отслеживать сообщения Интернета вещей (IoT) во всех службах Azure, участвующих в решении. Дополнительные сведения о функции см. в разделе "Что такое распределенная трассировка?".

Если включить распределенную трассировку для Центр Интернета вещей, можно:

• Отслеживайте поток каждого сообщения через Центр Интернета вещей с помощью контекста трассировки. Контекст трассировки включает идентификаторы корреляции, позволяющие сопоставлять события из одного компонента с событиями из другого компонента. Его можно применить для подмножества или всех сообщений устройства Интернета вещей с помощью двойника устройства.
• Зайдите в журналы трассировки в журналы Azure Monitor.
• Измерять и распознавать поток сообщений, отправляемых с устройств в Центр Интернета вещей и на конечные точки маршрутизации, и задержки.

Внимание

Распределенная трассировка Центр Интернета вещей Azure в настоящее время находится в предварительной версии. Юридические условия, применимые к функциям Azure, которые находятся в состоянии бета-версии, предварительной версии или иным образом еще не выпущены в общедоступной версии, см. на странице Дополнительные условия использования предварительных версий в Microsoft Azure.

Необходимые компоненты

• Центр Интернета вещей Azure, созданный в одном из следующих регионов.

  • Северная Европа
  • Юго-Восточная Азия
  • западная часть США 2

• Устройство, зарегистрированное в Центре Интернета вещей. Если у вас нет устройства, выполните действия, описанные в статье "Регистрация нового устройства в Центре Интернета вещей" и сохранение устройства строка подключения для использования в этой статье.

• В этой статье предполагается, что вы знаете, как отправлять сообщения телеметрии в Центр Интернета вещей.

• Последняя версия Git.

Ограничения общедоступной предварительной версии и рекомендации

Рассмотрим следующие ограничения, чтобы определить, подходит ли эта предварительная версия для ваших сценариев:

• Предложение для стандарта контекста трассировки W3C в настоящее время является рабочим проектом.

• Единственный язык разработки, поддерживаемый клиентским пакетом SDK, — C в общедоступной предварительной версии пакета SDK для устройств Интернета вещей Azure для C

• Возможность двойника "облако — устройство" недоступна для базового уровня Центр Интернета вещей. Однако Центр Интернета вещей по-прежнему регистрируется в Azure Monitor, если он видит правильный заголовок контекста трассировки.

• Чтобы обеспечить эффективную операцию, Центр Интернета вещей накладывает регулирование на скорость ведения журнала, которая может происходить в рамках распределенной трассировки.

• Функция распределенной трассировки поддерживается только для центров Интернета вещей, созданных в следующих регионах:

  • Северная Европа
  • Юго-Восточная Азия
  • западная часть США 2

Сведения о распределенной трассировке Интернета вещей Azure

Многие решения Интернета вещей, включая эталонную архитектуру Azure IoT, обычно следуют варианту архитектуры микрослужб. По мере усложнения решений Интернета вещей вам придется использовать дюжину или более микрослужб. Эти микрослужбы могут или не могут быть из Azure.

Определение того, где сообщения Интернета вещей удаляются или замедляется, могут быть сложной задачей. Например, представьте, что у вас есть решение Интернета вещей, использующее пять разных служб Azure и 1500 активных устройств. Каждое устройство отправляет 10 сообщений в облако в секунду в общей сложности 15 000 сообщений в секунду. Но вы заметили, что веб-приложение видит только 10 000 сообщений в секунду. Как найти причину?

Для восстановления потока сообщения Интернета вещей между службами каждая служба должна распространять идентификатор корреляции, который однозначно идентифицирует сообщение. После сбора идентификаторов корреляции в централизованной системе Azure Monitor можно использовать эти идентификаторы для просмотра потока сообщений. Этот метод называется шаблоном распределенной трассировки.

Для поддержки более широкого внедрения распределенной трассировки, корпорация Майкрософт вносит свой вклад в разработку стандартного предложения W3C по распределенной трассировке. Если включена поддержка распределенной трассировки для Центр Интернета вещей, он следует этому потоку для каждого созданного сообщения:

1. На устройстве Интернета вещей формируется сообщение.
2. Устройство Интернета вещей решает (с помощью облака), что это сообщение должно быть назначено контекстом трассировки.
3. Пакет SDK добавляет tracestate значение в свойство сообщения, содержащее метку времени для создания сообщения.
4. Устройство Интернета вещей отправляет сообщение в Центр Интернета вещей.
5. Сообщение поступает в шлюз Центр Интернета вещей.
6. Центр Интернета вещей ищет tracestate значение в свойствах сообщения и проверка, имеет ли он правильный формат. В этом случае Центр Интернета вещей создает глобально уникальное trace-id значение для сообщения и span-id значение прыжка. Центр Интернета вещей записывает эти значения в Центр Интернета вещей распределенные журналы трассировки в рамках DiagnosticIoTHubD2C операции.
7. После завершения обработки сообщений Центр Интернета вещей создает другое span-id значение и регистрирует его вместе с существующим trace-id значением DiagnosticIoTHubIngress в ходе операции.
8. Если маршрутизация включена для сообщения, Центр Интернета вещей записывает его в пользовательскую конечную точку. Центр Интернета вещей регистрирует другое span-id значение с тем же trace-id значением DiagnosticIoTHubEgress в категории.

Настройка распределенной трассировки в Центре Интернета вещей

В этом разделе описана настройка Центра Интернета вещей для регистрации атрибутов распределенной трассировки (идентификаторы корреляции и метки времени).

1. Перейдите в центр Интернета вещей в портал Azure.

2. На левой панели центра Интернета вещей прокрутите вниз до раздела "Мониторинг " и выберите параметры диагностики.

3. Выберите Добавить параметр диагностики.

4. В поле имени параметра диагностики введите имя нового параметра диагностики. Например, введите DistributedTracing Параметры.

   

5. Выберите один или несколько следующих параметров в разделе "Сведения о назначении", чтобы определить, куда отправлять данные ведения журнала:

   • Архивация в учетную запись хранения. Настройте учетную запись хранения, в которой будут храниться данные журнала.
   • Настройка потока в концентратор событий. Настройте концентратор событий, в котором будут храниться данные журнала.
   • Отправка в Log Analytics. Настройка рабочей области Log Analytics для хранения сведений о ведении журнала.

6. В разделе "Журналы" выберите операции, которые требуется регистрировать.

   Включите распределенную трассировку и настройте период хранения в течение нескольких дней, которые требуется сохранить в журнале. Хранение журналов влияет на затраты на хранение.

   

7. Выберите Сохранить.

8. (Необязательно) Чтобы настроить отправку потока сообщений в разные места, установите правила маршрутизации по крайней мере на две разные конечные точки.

После включения ведения журнала Центр Интернета вещей записывает журнал при обнаружении сообщения, содержащего допустимые свойства трассировки, в любой из следующих ситуаций:

• Сообщение поступает в шлюз Центра Интернета вещей.
• Центр Интернета вещей обрабатывает сообщение.
• сообщение маршрутизируется на пользовательские конечные точки (необходимо включить маршрутизацию).

Дополнительные сведения об этих журналах и их схемах см. в статье Мониторинг центра Интернета вещей и Распределенная трассировка в журналах ресурсов центра Интернета вещей.

Обновление параметров выборки

Чтобы изменить процентную долю трассируемых из облака сообщений, необходимо обновить двойник устройства. Обновления можно сделать с помощью редактора JSON в портал Azure или пакете SDK службы Центр Интернета вещей. Примеры приведены в следующих подразделах.

Обновление одного устройства

Вы можете использовать портал Azure или расширение Центр Интернета вещей Azure для Visual Studio Code (VS Code), чтобы обновить частоту выборки одного устройства.

Портал Azure

1. Перейдите в центр Интернета вещей в портал Azure, а затем выберите "Устройства" в разделе управления устройствами в меню.

2. Выберите устройство.

3. Выберите значок шестеренки в разделе Распределенная трассировка (предварительная версия). На открывающейся панели:

   1. Выберите параметр "Включить".
   2. Для частоты выборки выберите процент от 0 до 100.
   3. Выберите Сохранить.

   

4. Подождите несколько секунд, а затем нажмите кнопку "Обновить". Если устройство успешно подтверждает изменения, появится значок синхронизации с проверка меткой.

VS Code

1. После установки Visual Studio Code установите последнюю версию расширения Центр Интернета вещей Azure для Visual Studio Code.

2. Откройте Visual Studio Code и перейдите на вкладку Обозреватель и раздел Центр Интернета вещей Azure.

3. Щелкните многоточие (...) рядом с Центр Интернета вещей Azure, чтобы просмотреть подменю. Выберите параметр "Выбрать Центр Интернета вещей", чтобы получить центр Интернета вещей из Azure.

   Во всплывающем окне, появившемся в верхней части Visual Studio Code, можно выбрать подписку и Центр Интернета вещей.

   Демонстрация на странице GitHub vscode-azure-iot-toolkit .

4. Разверните устройство в разделе "Устройства". Щелкните правой кнопкой мыши параметр распределенной трассировки (предварительная версия) и выберите пункт "Обновить параметр распределенной трассировки" (предварительная версия).

5. В всплывающей области, которая появится в верхней части окна, нажмите кнопку "Включить".

   

   Включить распределенную трассировку: теперь включен параметр распределенной трассировки (предварительная версия)>Desired.

6. Во всплывающей области, которая отображается для частоты выборки, введите целое число от 0 до 100, а затем нажмите клавишу ВВОД.

   

   Частота выборки: 100(%) теперь отображается в разделе "Параметр распределенной трассировки (предварительная версия)>Требуемое значение".

Массовое обновление нескольких устройств

Чтобы обновить конфигурацию выборки распределенной трассировки нескольких устройств, используйте автоматическую конфигурацию устройства. Выполните следующую схему двойника:

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

Имя элемента	Обязательное поле	Type	Описание
sampling_mode	Да	Целое	Для включения и отключения выборки в настоящее время поддерживается два режима. 1 включен и 2 отключен.
sampling_rate	Да	Целое	Это значение является процентной долей. Разрешены только значения в диапазоне от 0 до 100 включительно.

Запрос и визуализация трассировок

Чтобы просмотреть все трассировки, зарегистрированные центром Интернета вещей, отправьте запрос к хранилищу журналов, выбранному в параметрах диагностики. В этом разделе показано, как запрашивать с помощью 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:

Время создания	Наименование операции	Категория	Уровень	Идентификатор корреляции	Длительность в миллисекундах	Свойства
2018-02-22T03:28:28.633Z	DiagnosticIoTHubD2C	DistributedTracing	Информационный	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	Информационный	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	20	{"isRoutingEnabled":"false","parentSpanId":"0144d2590aacd909"}
2018-02-22T03:28:48.633Z	DiagnosticIoTHubEgress	DistributedTracing	Информационный	00-8cd869a412459a25f5b4f31311223344-349810a9bbd28730-01	23	{"endpointType":"EventHub","endpointName":"myEventHub", "parentSpanId":"0144d2590aacd909"}

Сведения о типах журналов см. в разделе Центр Интернета вещей Azure распределенных журналов трассировки.

Запуск примера приложения

В этом разделе вы подготовите среду разработки для использования с пакетом SDK Azure IoT для C. Затем вы измените один из примеров, чтобы включить распределенную трассировку в сообщениях телеметрии устройства.

Эти инструкции предназначены для создания примера в операционной системе Windows. Сведения о других средах см. в разделах о компиляции пакета SDK для C или предварительно собранном пакете SDK для C для разработки на определенной платформе.

Клонирование исходного кода и инициализация

1. Установите разработку классических приложений с рабочей нагрузкой C++ для Visual Studio 2022. Visual Studio 2019 также поддерживается.

2. Установка CMake. Убедитесь, что он находится в PATHcmake -version вашей командной строке.

3. Откройте командную строку или оболочку Git Bash. Выполните следующие команды, чтобы клонировать последний выпуск общедоступной предварительной версии репозитория GitHub пакета SDK для Azure IoT C:

   git clone -b public-preview https://github.com/Azure/azure-iot-sdk-c.git
   cd azure-iot-sdk-c
   git submodule update --init
   

   Ожидается, что эта операция займет несколько минут.

4. Выполните следующие команды из 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
   

Измените пример телеметрии, чтобы включить распределенную трассировку

В этом разделе описано, как изменить пример iothub_ll_telemetry_sample.c в репозитории SDK, чтобы включить распределенную трассировку. Кроме того, можно скопировать уже измененную версию примера из репозитория azure-iot-distributed-tracing-sample .

1. Используйте редактор, чтобы открыть исходный файл azure-iot-sdk-c/iothub_client/samples/iothub_ll_telemetry_sample/iothub_ll_telemetry_sample.c.

2. Найдите объявление константы 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 константы строка подключения устройства, сохраненного в разделе "Регистрация устройства" краткого руководства по отправке данных телеметрии.

3. Найдите строку, вызывающую 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 включает политики для определенных Центр Интернета вещей функций, настроенных с помощью двойников устройств. После включения POLICY_CONFIGURATION_DISTRIBUTED_TRACING с помощью дополнительной строки кода поведение трассировки устройства будет отражать изменения распределенной трассировки, внесенные в двойник устройства.

4. Чтобы сохранить пример приложения, выполняющегося без использования квоты, добавьте секундную задержку в конце цикла обработки отправки сообщений:

       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);
   

Компиляция и запуск

1. Перейдите в iothub_ll_telemetry_sample каталог проекта из созданного ранее каталогаazure-iot-sdk-c/cmake CMake и скомпилируйте пример:

   cd iothub_client/samples/iothub_ll_telemetry_sample
   cmake --build . --target iothub_ll_telemetry_sample --config Debug
   

2. Запустите приложение. Устройство отправляет данные телеметрии, поддерживающие распределенную трассировку.

   Debug/iothub_ll_telemetry_sample.exe
   

3. Не отключайте приложение. Вы можете наблюдать, как сообщения отправляются в Центр Интернета вещей в окне консоли.

Для клиентского приложения, которое может принимать решения выборки из облака, попробуйте пример iothub_devicetwin_sample.c в репозитории распределенной трассировки.

Обходное решение для клиентов, отличных от Майкрософт

Реализация функции распределенной трассировки без использования пакета SDK для C является более сложной. Это не рекомендуемый вариант.

Сначала необходимо реализовать все примитивы протокола Центр Интернета вещей в сообщениях, следуя руководству разработчика по созданию и чтению сообщений Центр Интернета вещей. Затем измените свойства протокола в сообщениях MQTT и AMQP, чтобы добавить tracestate в качестве системного свойства.

В частности:

• Для MQTT добавьте %24.tracestate=timestamp%3d1539243209 в раздел сообщения. Замените 1539243209 время создания сообщения в формате метки времени Unix. Например, обратитесь к реализации в пакете SDK для C.
• Для AMQP добавьте key("tracestate") и value("timestamp=1539243209") как заметки к сообщению. Эталонная реализация см. в файле uamqp_messaging.c .

Чтобы контролировать процент сообщений, содержащих это свойство, реализуйте логику для прослушивания событий, инициированных облаком, таких как обновления двойников.

Следующие шаги

• Дополнительные сведения об общем шаблоне распределенной трассировки в микрослужбах см. в этой статье.