적용 대상:
IoT Edge 1.5
중요합니다
IoT Edge 1.5 LTS는 지원되는 릴리스입니다. IoT Edge 1.4 LTS는 2024년 11월 12일부터 수명이 종료됩니다. 이전 릴리스에 있는 경우 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} 기반으로 다음 표의 값을 사용합니다.
| 값 | 심각도 |
|---|---|
| 0 | 긴급 |
| 1 | 경고 |
| 2 | 위험 |
| 3 | 오류 |
| 4 | 경고 |
| 5 | 알림 |
| 6 | 정보 제공 |
| 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"
}
| 이름 | 타입 | 설명 |
|---|---|---|
| 스키마 버전 | 문자열 | 설정함 1.0 |
| 항목 | JSON 배열 |
id 및 filter 튜플이 포함된 배열입니다. |
| 아이디 | 문자열 | 모듈 이름을 지정하는 정규식입니다. Edge 디바이스에서 여러 모듈을 일치시킬 수 있습니다. .NET 정규식 형식이 필요합니다. 여러 항목에 동일한 모듈과 일치하는 ID가 있는 경우 일치하는 첫 번째 ID의 필터 옵션만 해당 모듈에 적용됩니다. |
| 필터링 | JSON 섹션 | 튜플의 id 정규식과 일치하는 모듈에 적용할 로그 필터입니다. |
| 꼬리 | 정수 | 시작점은 최신이며 조회할 과거의 로그 라인 수입니다. 선택 사항입니다. |
| 이래 | 문자열 | rfc3339 타임스탬프, UNIX 타임스탬프 또는 기간(일), 시간(h), 분(m)으로 이 시간 이후의 로그만 반환합니다. 예를 들어 1일, 12시간, 30분의 기간은 1일 12시간 30분 또는 1d 12h 30m로 지정할 수 있습니다.
tail와 since가 모두 지정된 경우, 먼저 since 값을 사용해 로그를 필터링하고, 그 결과에 tail 값을 적용합니다. 선택 사항 |
| 까지 | 문자열 | rfc3339 타임스탬프, UNIX 타임스탬프 또는 기간(일), 시간(h), 분(m)으로 지정된 시간 이전의 로그만 반환합니다. 예를 들어 90분의 지속 시간은 90분 또는 90m로 지정할 수 있습니다.
tail와 since가 모두 지정된 경우, 먼저 since 값을 사용해 로그를 필터링하고, 그 결과에 tail 값을 적용합니다. 선택 사항 |
| 로그 레벨 | 정수 | 지정된 로그 수준과 같은 로그 줄을 필터링합니다. 로그 줄은 권장되는 로깅 형식을 따르고 Syslog 심각도 수준 표준을 사용해야 합니다. 여러 로그 수준 심각도 값을 필터링해야 하는 경우 모듈이 서로 다른 심각도 수준에 일관된 형식을 사용하는 경우 regex 일치를 사용합니다. 선택 사항. |
| 정규식 | 문자열 | .NET 정규식 형식을 사용하여 지정된 정규식과 일치하는 로그 줄을 필터링합니다. 옵션. |
| 인코딩 | 문자열 |
gzip 또는 none 중 하나입니다. 기본값은 none입니다. |
| 콘텐츠 유형 | 문자열 |
json 또는 text 중 하나입니다. 기본값은 text입니다. |
참고
로그 콘텐츠가 현재 128KB인 직접 메서드의 응답 크기 제한을 초과하면 응답은 오류를 반환합니다.
성공적인 로그 검색은 '상태': 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"
}
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 컨테이너로 보냅니다.
참고
검색된 로그 범위를 제한하려면 since 및 until 필터 옵션을 사용합니다. 경계 없이 이 직접 메서드를 호출하면 모든 로그가 검색되며, 이 로그는 크거나, 시간이 많이 걸리거나, 비용이 많이 들 수 있습니다.
게이트웨이 디바이스 뒤에 있는 디바이스에서 로그를 업로드하려면 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"
}
| 이름 | 타입 | 설명 |
|---|---|---|
| sas URL | 문자열(URI) | Azure Blob Storage 컨테이너에 대한 쓰기 권한이 있는 공유 액세스 서명 URL입니다. |
로그 업로드 요청이 성공하면 "status": 200 뒤에 다음 스키마가 포함된 페이로드가 반환됩니다.
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| 이름 | 타입 | 설명 |
|---|---|---|
| 상태 | 문자열 |
NotStarted, Running, Completed, Failed, Unknown 중 하나입니다. |
| 메시지 | 문자열 | 오류가 있거나 빈 문자열이 있으면 메시지를 표시합니다. |
| 코릴레이션 ID | 문자열 | 업로드 요청의 상태를 확인하는 ID입니다. |
예를 들어 다음 호출은 압축된 JSON 형식의 모든 모듈에서 마지막 100개의 로그 줄을 업로드합니다.
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 모듈의 마지막 1,000개 로그 줄을 압축되지 않은 텍스트 형식으로 업로드합니다.
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"
}
지원 번들의 진단 정보 업로드
UploadSupportBundle 직접 메서드를 사용하여 IoT Edge 모듈 로그의 zip 파일을 번들화하고 사용 가능한 Azure Blob Storage 컨테이너에 업로드할 수 있습니다. 이 직접 메서드는 IoT Edge 디바이스에서 iotedge support-bundle 명령을 실행하여 로그를 가져옵니다.
참고
게이트웨이 디바이스 뒤에 있는 디바이스에서 로그를 업로드하려면 API 프록시 및 Blob Storage 모듈 이 최상위 계층 디바이스에 설정되어 있는지 확인합니다. 이러한 모듈은 하위 계층 디바이스에서 게이트웨이 디바이스를 통해 클라우드의 스토리지로 로그를 라우팅합니다.
이 메서드는 다음 스키마를 사용하여 JSON 페이로드를 허용합니다.
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
| 이름 | 타입 | 설명 |
|---|---|---|
| 스키마 버전 | 문자열 |
1.0로 설정합니다. |
| sasURL | 문자열(URI) | Azure Blob Storage 컨테이너에 대한 쓰기 권한이 있는 공유 액세스 서명 URL입니다. |
| 이래 | 문자열 | 이 시간 이후의 로그를 RFC 3339 타임스탬프, UNIX 타임스탬프 또는 기간(일(d), 시간(h), 분(m)으로 반환합니다. 예를 들어 1일, 12시간, 30분을 1일 12시간 30분 또는 1d 12시간 30m로 지정합니다. 선택 사항입니다. |
| 까지 | 문자열 | 이 시간 이전의 로그를 RFC 3339 타임스탬프, UNIX 타임스탬프 또는 기간(일(d), 시간(h), 분(m)으로 반환합니다. 예를 들어 90분을 90분 또는 90m로 지정합니다. 선택 사항입니다. |
| 엣지 런타임 전용 | 불리언 | true이면 Edge 에이전트, Edge Hub 및 Edge 보안 디먼에서만 로그를 반환합니다. 기본값: false입니다. 선택 사항입니다. |
중요합니다
IoT Edge 지원 번들에는 개인 식별 정보가 포함될 수 있습니다.
성공적인 업로드 로그 요청은 UploadModuleLogs 응답과 동일한 스키마를 가진 "상태": 200 및 페이로드를 반환합니다.
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| 이름 | 타입 | 설명 |
|---|---|---|
| 상태 | 문자열 |
NotStarted, Running, Completed, Failed, Unknown 중 하나입니다. |
| 메시지 | 문자열 | 오류가 발생하면 메시지이고, 그러지 않으면 빈 문자열입니다. |
| 상관 관계 ID | 문자열 | 업로드 요청의 상태를 쿼리할 ID입니다. |
다음 예제에서는 자리 표시자 텍스트를 <hub name><device 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에서 고유한 SAS URL을 바꾼 후 메서드 이름과 UploadSupportBundle 다음 JSON 페이로드를 사용하여 메서드를 호출합니다.
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
업로드 요청 상태 가져오기
GetTaskStatus 직접 메서드를 사용하여 업로드 로그 요청의 상태를 확인합니다.
GetTaskStatus 요청 페이로드는 업로드 로그 요청의 페이로드를 사용하여 correlationId 작업 상태를 가져옵니다.
correlationId 직접 메서드 호출의 응답에서 가 나옵니다.
이 메서드는 다음 스키마를 사용하여 JSON 페이로드를 허용합니다.
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
로그 업로드 요청이 성공하면 "status": 200 뒤에 UploadModuleLogs 응답과 동일한 스키마를 가진 페이로드가 반환됩니다.
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| 이름 | 타입 | 설명 |
|---|---|---|
| 상태 | 문자열 |
NotStarted, Running, Completed, Failed, Cancelled 또는 Unknown 중 하나입니다. |
| 메시지 | 문자열 | 오류가 발생하면 메시지이고, 그러지 않으면 빈 문자열입니다. |
| 상관 관계 ID | 문자열 | 업로드 요청의 상태를 쿼리할 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에서 메서드 이름과 GetTaskStatus 다음 JSON 페이로드를 사용하여 메서드를 호출합니다.
<GUID>을 고유한 값으로 바꿉니다.
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
