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

  • Статья

Область применения:IoT Edge 1.4 checkmark IoT Edge 1.4

Важно!

IoT Edge 1.4 является поддерживаемым выпуском. Если вы используете более ранний выпуск, см. статью Обновление 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"
    }

Screenshot of how to invoke direct method GetModuleLogs in the Azure portal.

Вы также можете передать выходные данные 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"
    }
Имя. Тип Описание
status строка Одно из значений 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"
    }

Screenshot of how to invoke direct method UploadModuleLogs in the Azure portal.

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

Используйте прямой метод 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"
    }
Имя. Тип Описание
status строка Одно из значений 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
    }

Screenshot showing how to invoke direct method UploadSupportBundle in the Azure portal.

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

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

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

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

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

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }
Имя. Тип Описание
status строка Одно из 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>"
    }

Screenshot showing how to invoke direct method GetTaskStatus in Azure portal .

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

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