IoT Edge 배포에서 로그 검색

아티클
04/11/2024

적용 대상: IoT Edge 1.4

Important

IoT Edge 1.4는 지원되는 릴리스입니다. 이전 릴리스에 있는 경우 IoT Edge 업데이트를 참조하세요.

IoT Edge 에이전트 모듈에 포함된 직접 메서드를 사용하여 디바이스에 대한 물리적 또는 SSH 액세스 없이 IoT Edge 배포에서 로그를 검색합니다. 직접 메서드는 디바이스에서 구현된 다음, 클라우드에서 호출할 수 있습니다. IoT Edge 에이전트에는 IoT Edge 디바이스를 원격으로 모니터링하고 관리하는 데 도움이 되는 직접 메서드가 포함되어 있습니다. 이 문서에서 설명하는 직접 메서드는 일반적으로 1.0.10 릴리스와 함께 사용할 수 있습니다.

직접 메서드, 그 사용 방법, 사용자 고유의 모듈에서 이를 구현하는 방법에 대한 자세한 내용은 IoT Hub에서의 직접 메서드 이해 및 호출을 참조하세요.

직접 메서드의 이름은 대/소문자를 구분하여 처리됩니다.

권장 로깅 형식

필수는 아니지만 이 기능과의 최상의 호환을 위해 권장되는 로깅 형식은 다음과 같습니다.

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

{Timestamp}는 yyyy-MM-dd HH:mm:ss.fff zzz로 형식이 지정되어야 하며, {Log Level}은 아래 표를 따라야 합니다. 이 표는 Syslog 표준의 심각도 코드에서 해당 심각도 수준을 파생시킵니다.

값	심각도
0	긴급
1	경고
2	위험
3	Error
4	Warning
5	알림
6	Informational
7	디버그

IoT Edge의 로거 클래스는 정식 구현으로 사용됩니다.

모듈 로그 검색

GetModuleLogs 직접 메서드를 사용하여 IoT Edge 모듈의 로그를 검색합니다.

팁

검색된 로그 범위를 제한하려면 since 및 until 필터 옵션을 사용합니다. 경계 없이 이 직접 메서드를 호출하면 크거나, 시간이 오래 걸리거나, 비용이 많이 들 수 있는 로그가 모두 검색됩니다.

Azure Portal의 IoT Edge 문제 해결 페이지는 모듈 로그를 보기 위한 간소화된 환경을 제공합니다. 자세한 내용은 Azure Portal에서 IoT Edge 디바이스 모니터링 및 문제 해결을 참조하세요.

이 메서드는 다음 스키마를 사용하여 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	string	`1.0`
항목	JSON 배열	`id` 및 `filter` 튜플이 포함된 배열입니다.
id	string	모듈 이름을 제공하는 정규식입니다. Edge 디바이스에서 여러 모듈을 일치시킬 수 있습니다. .NET 정규식 형식이 필요합니다. ID가 동일한 모듈과 일치하는 항목이 여럿 있는 경우 일치하는 첫 번째 ID의 필터 옵션만 해당 모듈에 적용됩니다.
필터링	JSON 섹션	튜플의 `id` 정규식과 일치하는 모듈에 적용할 로그 필터입니다.
tail	정수	최근부터 검색하는 과거의 로그 줄 수입니다. 옵션.
since	string	이 시간 이후의 로그만 rfc3339 타임스탬프, UNIX 타임스탬프 또는 기간(일(d) 시간(h) 분(m))으로 반환합니다. 예를 들어 1일, 12시간, 30분의 기간은 1일 12시간 30분 또는 1d 12h 30m로 지정할 수 있습니다. `tail` 및 `since`를 모두 지정하는 경우에는 먼저 `since` 값을 사용하여 로그를 검색합니다. 그런 다음, `tail` 값이 결과에 적용되고 최종 결과가 반환됩니다. 옵션.
~	string	지정된 시간 이전의 로그만 rfc3339 타임스탬프, UNIX 타임스탬프 또는 기간(일(d) 시간(h) 분(m))으로 반환합니다. 예를 들어 90분의 기간은 90분 또는 90m로 지정할 수 있습니다. `tail` 및 `since`를 모두 지정하는 경우에는 먼저 `since` 값을 사용하여 로그를 검색합니다. 그런 다음, `tail` 값이 결과에 적용되고 최종 결과가 반환됩니다. 옵션.
loglevel	정수	지정된 로그 수준과 같은 로그 라인을 필터링합니다. 로그 줄은 권장되는 로깅 형식을 따르고 Syslog 심각도 수준 표준을 사용해야 합니다. 여러 개의 로그 수준 심각도 값을 기준으로 필터링해야 하는 경우 모듈이 서로 다른 심각도 수준을 로깅할 때 일관된 형식을 따른다면 정규식 일치를 사용합니다. 옵션.
regex	string	.NET 정규식 형식을 사용하여 지정된 정규식과 일치하는 내용이 있는 로그 줄을 필터링합니다. 옵션.
encoding	string	`gzip` 또는 `none` 중 하나입니다. 기본값은 `none`입니다.
contentType	string	`json` 또는 `text` 중 하나입니다. 기본값은 `text`입니다.

참고 항목

로그 내용이 직접 메서드의 응답 크기 제한(현재 128 KB)을 초과하는 경우 응답에서 오류를 반환합니다.

로그를 성공적으로 검색하면 "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 Portal에서 메서드 이름이 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 출력을 gzip과 같은 Linux 유틸리티로 파이프하여 압축된 응답을 처리할 수도 있습니다. 예시:

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 직접 메서드를 사용하여 요청된 로그를 지정된 Azure Blob Storage 컨테이너로 보냅니다.

참고 항목

게이트웨이 디바이스 뒤의 디바이스에서 로그를 업로드하려는 경우에는 최상위 계층 디바이스에서 API 프록시 및 Blob Storage 모듈을 구성해야 합니다. 이러한 모듈은 게이트웨이 디바이스를 통해 하위 계층 디바이스의 로그를 클라우드의 스토리지로 라우팅합니다.

이 메서드는 "sasUrl" 키를 추가하여 GetModuleLogs와 유사한 JSON 페이로드를 허용합니다.

    {
       "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)	Azure Blob Storage 컨테이너에 대한 쓰기 권한이 있는 공유 액세스 서명 URL입니다.

로그 업로드 요청이 성공하면 "status": 200 뒤에 다음 스키마가 포함된 페이로드가 반환됩니다.

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }

이름	형식	설명
status	string	`NotStarted`, `Running`, `Completed`, `Failed`, `Unknown` 중 하나입니다.
message	string	오류가 발생하면 메시지이고, 그러지 않으면 빈 문자열입니다.
correlationId	string	업로드 요청의 상태를 쿼리할 ID입니다.

예시:

다음 호출은 모든 모듈의 마지막 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"
    }
'

다음 호출에서는 edgeAgent 및 edgeHub의 마지막 100개 로그 줄과 tempSensor 모듈의 마지막 1000개 로그 줄을 압축되지 않은 텍스트 형식으로 업로드합니다.

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 Portal에서 sasURL을 사용자의 정보로 채운 후 메서드 이름이 UploadModuleLogs이며 다음 JSON 페이로드가 있는 메서드를 호출합니다.

    {
       "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 직접 메서드를 사용하여 IoT Edge 모듈 로그의 zip 파일을 번들화하고 사용 가능한 Azure Blob Storage 컨테이너에 업로드할 수 있습니다. 이 직접 메서드는 IoT Edge 디바이스에서 iotedge support-bundle 명령을 실행하여 로그를 가져옵니다.

참고 항목

이 메서드는 다음 스키마를 사용하여 JSON 페이로드를 허용합니다.

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

이름	형식	설명
schemaVersion	string	`1.0`
sasURL	문자열(URI)	Azure Blob Storage 컨테이너에 대한 쓰기 권한이 있는 공유 액세스 서명 URL입니다.
since	string	이 시간 이후의 로그만 rfc3339 타임스탬프, UNIX 타임스탬프 또는 기간(일(d) 시간(h) 분(m))으로 반환합니다. 예를 들어 1일, 12시간, 30분의 기간은 1일 12시간 30분 또는 1d 12h 30m로 지정할 수 있습니다. 옵션.
~	string	지정된 시간 이전의 로그만 rfc3339 타임스탬프, UNIX 타임스탬프 또는 기간(일(d) 시간(h) 분(m))으로 반환합니다. 예를 들어 90분의 기간은 90분 또는 90m로 지정할 수 있습니다. 옵션.
edgeRuntimeOnly	부울 값	true이면 Edge 에이전트, Edge 허브, Edge 보안 디먼의 로그만 반환합니다. 기본값: false입니다. 옵션.

Important

IoT Edge 지원 번들에는 개인 식별이 가능한 정보가 포함될 수 있습니다.

로그 업로드 요청이 성공하면 "status": 200 뒤에 UploadModuleLogs 응답과 동일한 스키마를 가진 페이로드가 반환됩니다.

    {
        "status": "string",
        "message": "string",
        "correlationId": "GUID"
    }

이름	형식	설명
status	string	`NotStarted`, `Running`, `Completed`, `Failed`, `Unknown` 중 하나입니다.
message	string	오류가 발생하면 메시지이고, 그러지 않으면 빈 문자열입니다.
correlationId	string	업로드 요청의 상태를 쿼리할 ID입니다.

예시:

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 Portal에서 sasURL을 사용자의 정보로 채운 후 메서드 이름이 UploadSupportBundle이며 다음 JSON 페이로드가 있는 메서드를 호출합니다.

    {
        "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	string	`NotStarted`, `Running`, `Completed`, `Failed`, 'Cancelled' 또는 `Unknown` 중 하나입니다.
message	string	오류가 발생하면 메시지이고, 그러지 않으면 빈 문자열입니다.
correlationId	string	업로드 요청의 상태를 쿼리할 ID입니다.

예시:

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 Portal에서 GUID를 사용자의 정보로 채운 후 메서드 이름이 GetTaskStatus이며 다음 JSON 페이로드가 있는 메서드를 호출합니다.

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

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

다음 단계

IoT Edge 에이전트 및 IoT Edge 허브 모듈 쌍의 속성

IoT Edge 배포에서 로그 검색

권장 로깅 형식

모듈 로그 검색

모듈 로그 업로드

지원 번들 진단 업로드

업로드 요청 상태 가져오기

다음 단계

추가 리소스