Получение журналов из развертываний IoT Edge

  • Статья

Область применения:IoT Edge 1.5 проверка mark IoT Edge 1.5 IoT Edge 1.4 проверка mark IoT Edge 1.4

Внимание

Поддерживаются выпуски IoT Edge 1.5 LTS и IoT Edge 1.4 LTS. IoT Edge 1.4 LTS заканчивается жизнью 12 ноября 2024 года. Если вы используете более ранний выпуск, см. статью Обновление IoT Edge.

Получение журналов из развертываний IoT Edge без необходимости физического доступа или SSH-доступа к устройству с помощью прямых методов, предусмотренных в модуле агента IoT Edge. Прямые методы реализуются на устройстве, а затем могут вызываться из облака. Агент IoT Edge содержит прямые методы, помогающие удаленно отслеживать устройства IoT Edge и управлять ими. Прямые методы, описанные в этой статье, общедоступны в выпуске 1.0.10.

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

Имена этих прямых методов обрабатываются с учетом регистра.

Хотя это и не обязательно, для обеспечения лучшей совместимости с этой функцией рекомендуется использовать следующий формат ведения журнала:

<{Log Level}> {Timestamp} {Message Text}

{Timestamp} следует отформатировать как yyyy-MM-dd HH:mm:ss.fff zzz, и {Log Level} должен соответствовать таблице ниже, которая извлекает уровни серьезности из Кода серьезности согласно стандарту системного журнала.

Значение Важность
0 Экстренные ситуации
1 Предупреждение
2 Критически важно
3 Ошибка
4 Предупреждение
5 Примечание.
6 Информационный
7 Отладка

Класс Logger в IOT Edge выступает в качестве канонической реализации.

Получение журналов модуля

Используйте прямой метод GetModuleLogs для получения журналов модуля IOT Edge.

Совет

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

Страница устранения неполадок IoT Edge на портале Azure упрощает просмотр журналов модулей. Дополнительные сведения см. в статье Мониторинг и устранение неполадок устройств IoT Edge на портале Azure.

Этот метод принимает полезные данные JSON со следующей схемой:

    {
       "schemaVersion": "1.0",
       "items": [
          {
             "id": "regex string",
             "filter": {
                "tail": "int",
                "since": "string",
                "until": "string",
                "loglevel": "int",
                "regex": "regex string"
             }
          }
       ],
       "encoding": "gzip/none",
       "contentType": "json/text" 
    }
Имя. Тип Описание
schemaVersion строка Установите значение 1.0
items Массив JSON Массив с кортежами id и filter.
id строка Регулярное выражение, предоставляющее имя модуля. Оно может сопоставлять несколько модулей на пограничном устройстве. Ожидается формат регулярных выражений .NET. Если есть несколько элементов, идентификатор которых соответствует одному модулю, к нему будут применены только параметры фильтра первого соответствующего идентификатора.
Фильтр Раздел JSON Фильтры журналов, применяемые к модулям, соответствующим регулярному выражению id в кортеже.
tail integer Число получаемых строк журнала за прошедший период, начиная с последней строки. OPTIONAL.
since строка Только возвращаемые журналы с этого времени в виде метки времени rfc3339, метки времени UNIX или длительности (часы (d) (ч) минут (m)). Например, длительность в течение одного дня, 12 часов и 30 минут может быть указана как 1 день 12 часов 30 минут или 1d 12h 30m. Если указаны tail и since, журналы извлекаются сначала со значением since. Затем значение tail применяется к результату и возвращается окончательный результат. OPTIONAL.
до строка Возвращает только журналы до указанного времени в виде метки времени rfc3339, метки времени UNIX или длительности (часы (d) (ч) минут (m)). Например, длительность 90 минут может быть указана как 90 минут или 90 млн. Если указаны tail и since, журналы извлекаются сначала со значением since. Затем значение tail применяется к результату и возвращается окончательный результат. OPTIONAL.
Loglevel integer Фильтрация строк журнала, равных указанному уровню журнала. Строки журнала должны соответствовать рекомендуемому формату ведения журнала и использовать стандарт уровня серьезности syslog. Если необходимо фильтровать по нескольким значениям серьезности уровня журнала, а затем полагаться на соответствие регулярных выражений, если модуль соответствует определенному согласованному формату при ведении журнала различных уровней серьезности. OPTIONAL.
regex строка Фильтровать строки журнала, которые имеют содержимое, совпадающее с указанным регулярным выражением, с использованием формата регулярных выражений .NET. OPTIONAL.
encoding строка gzip или none. По умолчанию — none.
contentType строка json или text. По умолчанию — text.

Примечание.

Если содержимое журнала превышает предельное значение для размера ответа для прямых методов, которое в настоящее время составляет 128 КБ, ответ возвращает ошибку.

Успешное получение журналов возвращает "status": 200, за которым следуют полезные данные, содержащие журналы, полученные из модуля, отфильтрованные по параметрам, указанным в запросе.

Например:

az iot hub invoke-module-method --method-name 'GetModuleLogs' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
    {
       "schemaVersion": "1.0",
       "items": [
          {
             "id": "edgeAgent",
             "filter": {
                "tail": 10
             }
          }
       ],
       "encoding": "none",
       "contentType": "text"
    }
'

На портале Azure вызовите метод с именем GetModuleLogs и следующими полезными данными JSON:

    {
       "schemaVersion": "1.0",
       "items": [
          {
             "id": "edgeAgent",
             "filter": {
                "tail": 10
             }
          }
       ],
       "encoding": "none",
       "contentType": "text"
    }

Снимок экрана: вызов прямого метода GetModuleLogs в портал Azure.

Вы также можете передать выходные данные CLI в служебные программы Linux, например gzip, для обработки сжатого ответа. Например:

az iot hub invoke-module-method \
  --method-name 'GetModuleLogs' \
  -n <hub name> \
  -d <device id> \
  -m '$edgeAgent' \
  --method-payload '{"contentType": "text","schemaVersion": "1.0","encoding": "gzip","items": [{"id": "edgeHub","filter": {"since": "2d","tail": 1000}}],}' \
  -o tsv --query 'payload[0].payloadBytes' \
  | base64 --decode \
  | gzip -d

Отправка журналов модулей

Используйте прямой метод UploadModuleLogs, чтобы отправить запрошенные журналы в указанный контейнер Хранилища BLOB-объектов Azure.

Примечание.

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

Если вы хотите передать журналы с устройства, расположенного за устройством шлюза, вам потребуются модули API прокси-сервера и Хранилища BLOB-объектов, настроенные на устройстве верхнего уровня. Эти модули направляют журналы с устройства более низкого уровня через устройство шлюза в хранилище в облаке.

Этот метод принимает полезные данные JSON, аналогичные GetModuleLogs, с добавлением ключа "sasUrl":

    {
       "schemaVersion": "1.0",
       "sasUrl": "Full path to SAS URL",
       "items": [
          {
             "id": "regex string",
             "filter": {
                "tail": "int",
                "since": "string",
                "until": "string",
                "loglevel": "int",
                "regex": "regex string"
             }
          }
       ],
       "encoding": "gzip/none",
       "contentType": "json/text" 
    }
Имя. Тип Описание
sasURL строковое значение (URI) URL-адрес подписи общего доступа с доступом на запись к контейнеру Хранилища BLOB-объектов Azure.

Успешный запрос на отправку журналов возвращает "status": 200, за которым следуют полезные данные со следующей схемой:

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }
Имя. Тип Описание
статус строка Одно из значений NotStarted, Running, Completed, Failed или Unknown.
message строка Сообщение в случае ошибки, пустая строка в противном случае.
correlationId строка Идентификатор для запроса состояния запроса на отправку.

Например:

Показанный ниже вызов передает последние 100 строк журнала из всех модулей в сжатом формате JSON:

az iot hub invoke-module-method --method-name UploadModuleLogs -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
    {
        "schemaVersion": "1.0",
        "sasUrl": "<sasUrl>",
        "items": [
            {
                "id": ".*",
                "filter": {
                    "tail": 100
                }
            }
        ],
        "encoding": "gzip",
        "contentType": "json"
    }
'

Следующий вызов передает последние 100 строк журнала из edgeAgent и edgeHub с последними 1000 строк из модуля tempSensor в несжатом текстовом формате:

az iot hub invoke-module-method --method-name UploadModuleLogs -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
    {
        "schemaVersion": "1.0",
        "sasUrl": "<sasUrl>",
        "items": [
            {
                "id": "edge",
                "filter": {
                    "tail": 100
                }
            },
            {
                "id": "tempSensor",
                "filter": {
                    "tail": 1000
                }
            }
        ],
        "encoding": "none",
        "contentType": "text"
    }
'

На портале Azure вызовите метод с именем UploadModuleLogs и следующими полезными данными JSON после заполнения sasURL данными:

    {
       "schemaVersion": "1.0",
       "sasUrl": "<sasUrl>",
       "items": [
          {
             "id": "edgeAgent",
             "filter": {
                "tail": 10
             }
          }
       ],
       "encoding": "none",
       "contentType": "text"
    }

Снимок экрана: вызов прямого метода UploadModuleLogs в портал Azure.

Диагностика отправки пакета поддержки

Используйте прямой метод UploadSupportBundle для объединения и передачи ZIP-файла журналов модуля IoT Edge в доступный контейнер Хранилища BLOB-объектов Azure. Этот прямой метод запускает команду iotedge support-bundle на устройстве IoT Edge для получения журналов.

Примечание.

Если вы хотите передать журналы с устройства, расположенного за устройством шлюза, вам потребуются модули API прокси-сервера и Хранилища BLOB-объектов, настроенные на устройстве верхнего уровня. Эти модули направляют журналы с устройства более низкого уровня через устройство шлюза в хранилище в облаке.

Этот метод принимает полезные данные JSON со следующей схемой:

    {
        "schemaVersion": "1.0",
        "sasUrl": "Full path to SAS url",
        "since": "2d",
        "until": "1d",
        "edgeRuntimeOnly": false
    }
Имя. Тип Описание
schemaVersion строка Установите значение 1.0
sasURL строковое значение (URI) URL-адрес подписи общего доступа с доступом на запись к контейнеру Хранилища BLOB-объектов Azure
since строка Только возвращаемые журналы с этого времени в виде метки времени rfc3339, метки времени UNIX или длительности (часы (d) (ч) минут (m)). Например, длительность в течение одного дня, 12 часов и 30 минут может быть указана как 1 день 12 часов 30 минут или 1d 12h 30m. OPTIONAL.
до строка Возвращает только журналы до указанного времени в виде метки времени rfc3339, метки времени UNIX или длительности (часы (d) (ч) минут (m)). Например, длительность 90 минут может быть указана как 90 минут или 90 млн. OPTIONAL.
edgeRuntimeOnly boolean Если значение — true, возвращаются только журналы из агента Edge, центра Edge и управляющей программы системы безопасности Edge. По умолчанию: false. OPTIONAL.

Внимание

Пакет поддержки IoT Edge может содержать персональные данные.

Успешный запрос на отправку журналов возвращает "status": 200, за которым следуют полезные данные с той же схемой, что и ответ UploadModuleLogs:

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }
Имя. Тип Описание
статус строка Одно из значений NotStarted, Running, Completed, Failed или Unknown.
message строка Сообщение в случае ошибки, пустая строка в противном случае.
correlationId строка Идентификатор для запроса состояния запроса на отправку.

Например:

az iot hub invoke-module-method --method-name 'UploadSupportBundle' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
    {
        "schemaVersion": "1.0",
        "sasUrl": "Full path to SAS url",
        "since": "2d",
        "until": "1d",
        "edgeRuntimeOnly": false
    }
'

На портале Azure вызовите метод с именем UploadSupportBundle и следующими полезными данными JSON после заполнения sasURL данными:

    {
        "schemaVersion": "1.0",
        "sasUrl": "Full path to SAS url",
        "since": "2d",
        "until": "1d",
        "edgeRuntimeOnly": false
    }

Снимок экрана: вызов прямого метода UploadSupportBundle в портал Azure.

Получение состояния запроса на отправку

Используйте прямой метод GetTaskStatus для запроса состояния запроса на отправку журналов. Полезные данные запроса GetTaskStatus используют объект correlationId из запроса на отправку журналов для получения состояния задачи. correlationIdВозвращается в ответ на вызов прямого метода UploadModuleLogs.

Этот метод принимает полезные данные JSON со следующей схемой:

    {
      "schemaVersion": "1.0",
      "correlationId": "<GUID>"
    }

Успешный запрос на отправку журналов возвращает "status": 200, за которым следуют полезные данные с той же схемой, что и ответ UploadModuleLogs:

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }
Имя. Тип Описание
статус строка Одно из NotStarted, Running, Completed, Failed"Отменено" или Unknown.
message строка Сообщение в случае ошибки, пустая строка в противном случае.
correlationId строка Идентификатор для запроса состояния запроса на отправку.

Например:

az iot hub invoke-module-method --method-name 'GetTaskStatus' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
    {
      "schemaVersion": "1.0",
      "correlationId": "<GUID>"
    }
'

На портале Azure вызовите метод с именем GetTaskStatus и следующими полезными данными JSON после заполнения GUID данными:

    {
      "schemaVersion": "1.0",
      "correlationId": "<GUID>"
    }

Снимок экрана: вызов прямого метода GetTaskStatus в портал Azure.

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

Свойства двойников модуля Центра IoT Edge и агента IoT Edge