Recuperación de registros de implementaciones de IoT Edge
Se aplica a:
IoT Edge 1.5 IoT Edge 1.4
Importante
IoT Edge 1.5 LTS e IoT Edge 1.4 LTS son versiones compatibles. IoT Edge 1.4 LTS finaliza el ciclo de vida el 12 de noviembre de 2024. Si está usando una versión anterior, consulte Actualización de IoT Edge.
Recupere los registros de las implementaciones de IoT Edge sin necesidad de acceso físico o SSH al dispositivo mediante el uso de los métodos directos que se incluyen en el módulo del Agente de IoT Edge. Los métodos directos se implementan en el dispositivo y, a continuación, se pueden invocar desde la nube. El agente de IoT Edge incluye métodos directos que le ayudan a supervisar y administrar los dispositivos IoT Edge de forma remota. Los métodos directos descritos en este artículo están disponibles con carácter general con la versión 1.0.10.
Para obtener más información acerca de los métodos directos, cómo usarlos y cómo implementarlos en sus propios módulos, consulte Descripción e invocación de los métodos directos de IoT Hub.
Los nombres de estos métodos directos distinguen mayúsculas de minúsculas.
Formato de registro recomendado
Aunque no es necesario, para mejorar la compatibilidad con esta característica, el formato de registro recomendado es:
<{Log Level}> {Timestamp} {Message Text}
{Timestamp} debe tener el formato yyyy-MM-dd HH:mm:ss.fff zzz y {Log Level} debe usar la tabla siguiente, que deriva sus niveles de gravedad del código de gravedad del estándar Syslog.
| Valor | Gravedad |
|---|---|
| 0 | Emergencia |
| 1 | Alerta |
| 2 | Crítico |
| 3 | Error |
| 4 | Advertencia |
| 5 | Avisar |
| 6 | Informativo |
| 7 | Depuración |
La Clase de registrador de IoT Edge actúa como implementación canónica.
Recuperación de registros del módulo
Use el método directo GetModuleLogs para recuperar los registros de un módulo de IoT Edge.
Sugerencia
Use las opciones de filtro since y until para limitar el intervalo de registros recuperados. Al llamar a este método directo sin límites, se recuperan todos los registros que pueden ser grandes, lentos o costosos.
La página de solución de problemas de IoT Edge en Azure Portal proporciona una experiencia simplificada para ver los registros del módulo. Para más información, consulte Supervisión y solución de problemas de dispositivos IoT Edge desde Azure Portal.
Este método acepta una carga JSON con el siguiente esquema:
{
"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"
}
| Nombre | Escribir | Descripción |
|---|---|---|
| schemaVersion | string | Establézcala en 1.0 |
| items | Matriz JSON | Una matriz con las tuplas id y filter. |
| id | string | Expresión regular que proporciona el nombre del módulo. Puede coincidir con varios módulos en un dispositivo perimetral. Se espera un formato de expresiones regulares de .NET. En caso de que haya varios elementos cuyo identificador coincida con el mismo módulo, solo se aplicarán a ese módulo las opciones de filtro del primer identificador coincidente. |
| filter | Sección JSON | Filtros de registro que se aplicarán a los módulos que coincidan con la expresión regular id en la tupla. |
| tail | integer | Número de líneas de registro del pasado que se recuperarán a partir de la más reciente. OPCIONAL. |
| since | string | Solo se devuelven registros desde este momento, como una marca de tiempo rfc3339, una marca de tiempo UNIX o una duración (días [d] horas [h] minutos [m]). Por ejemplo, una duración de 1 día, 12 horas y 30 minutos se puede especificar como 1 día 12 horas 30 minutos o 1d 12h 30m. Si se especifica tanto tail como since, los registros se recuperan usando el valor since en primer lugar. A continuación, se aplica el valor tail al resultado y se devuelve el resultado final. OPCIONAL. |
| until | string | Solo se devuelven registros antes del tiempo especificado, como una marca de tiempo rfc3339, una marca de tiempo UNIX o una duración (días [d] horas [h] minutos [m]). Por ejemplo, se puede especificar una duración de 90 minutos como 90 minutos o 90m. Si se especifica tanto tail como since, los registros se recuperan usando el valor since en primer lugar. A continuación, se aplica el valor tail al resultado y se devuelve el resultado final. OPCIONAL. |
| loglevel | integer | Este elemento filtra las líneas que tengan un nivel de registro igual al especificado. Las líneas de registro deben seguir el formato de registro recomendado y usar el estándar de nivel de gravedad de Syslog. Si necesita filtrar las líneas en función de varios valores de gravedad de nivel de registro, utilice un método de coincidencia basado en expresiones regulares siempre que el módulo siga algún formato coherente a la hora de registrar los distintos niveles de gravedad. OPCIONAL. |
| regex | string | Filtre las líneas de registro que tengan contenido que se corresponda con la expresión regular especificada con el formato de expresiones regulares de .NET. OPCIONAL. |
| encoding | string | gzip o none. El valor predeterminado es none. |
| contentType | string | json o text. El valor predeterminado es text. |
Nota:
Si el contenido de los registros supera el límite del tamaño de respuesta de los métodos directos, que actualmente es de 128 KB, la respuesta devuelve un error.
Una recuperación correcta de registros devuelve un "estado": 200 seguido de una carga que contiene los registros recuperados del módulo, filtrados por la configuración especificada en la solicitud.
Por ejemplo:
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"
}
'
En el Azure Portal, invoque el método con el nombre de método GetModuleLogs y la siguiente carga útil de JSON:
{
"schemaVersion": "1.0",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
También puede canalizar la salida de la CLI en utilidades de Linux, como gzip, para procesar una respuesta comprimida. Por ejemplo:
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
Carga de registros del módulo
Use el método directo UploadModuleLogs para enviar los registros solicitados a un contenedor de Azure Blob Storage especificado.
Nota:
Use las opciones de filtro since y until para limitar el intervalo de registros recuperados. Al llamar a este método directo sin límites, se recuperan todos los registros que pueden ser grandes, lentos o costosos.
Si desea cargar registros desde un dispositivo detrás de un dispositivo de puerta de enlace, debe tener los módulos de proxy de API y de almacenamiento de blobs configurados en el dispositivo de nivel superior. Estos módulos enrutan los registros desde el dispositivo de nivel inferior a través del dispositivo de puerta de enlace al almacenamiento en la nube.
Este método acepta una carga JSON similar a GetModuleLogs, con la adición de la clave "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"
}
| Nombre | Escribir | Descripción |
|---|---|---|
| sasURL | cadena (URI) | URL de firma de acceso compartido con acceso de escritura al contenedor de Azure Blob Storage. |
Una solicitud correcta para cargar registros devuelve un "estado": 200 seguido de una carga con el esquema siguiente:
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| Nombre | Escribir | Descripción |
|---|---|---|
| estado | string | Uno de estos valores: NotStarted, Running, Completed, Failed o Unknown. |
| message | string | Mensaje si hay un error; cadena vacía en caso contrario. |
| correlationId | string | Identificador para consultar el estado de la solicitud de carga. |
Por ejemplo:
La invocación siguiente carga las últimas 100 líneas de registro de todos los módulos en formato JSON comprimido:
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"
}
'
La siguiente invocación carga las últimas 100 líneas de registro de edgeAgent y edgeHub con las últimas 1000 líneas de registro del módulo tempSensor en formato de texto sin comprimir:
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"
}
'
En Azure Portal, invoque el método con el nombre de método UploadModuleLogs y la siguiente carga útil de JSON después de cargar sasURL con su información:
{
"schemaVersion": "1.0",
"sasUrl": "<sasUrl>",
"items": [
{
"id": "edgeAgent",
"filter": {
"tail": 10
}
}
],
"encoding": "none",
"contentType": "text"
}
Cargar diagnóstico de conjunto de soporte
Use el método directo UploadSupportBundle para agrupar y cargar un archivo ZIP de registros del módulo de IoT Edge en un contenedor de Azure Blob Storage disponible. Este método directo ejecuta el comando iotedge support-bundle en el dispositivo IoT Edge para obtener los registros.
Nota:
Si desea cargar registros desde un dispositivo detrás de un dispositivo de puerta de enlace, debe tener los módulos de proxy de API y de almacenamiento de blobs configurados en el dispositivo de nivel superior. Estos módulos enrutan los registros desde el dispositivo de nivel inferior a través del dispositivo de puerta de enlace al almacenamiento en la nube.
Este método acepta una carga JSON con el siguiente esquema:
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
| Nombre | Escribir | Descripción |
|---|---|---|
| schemaVersion | string | Establézcala en 1.0 |
| sasURL | cadena (URI) | URL de firma de acceso compartido con acceso de escritura al contenedor de Azure Blob Storage |
| since | string | Solo se devuelven registros desde este momento, como una marca de tiempo rfc3339, una marca de tiempo UNIX o una duración (días [d] horas [h] minutos [m]). Por ejemplo, una duración de 1 día, 12 horas y 30 minutos se puede especificar como 1 día 12 horas 30 minutos o 1d 12h 30m. OPCIONAL. |
| until | string | Solo se devuelven registros antes del tiempo especificado, como una marca de tiempo rfc3339, una marca de tiempo UNIX o una duración (días [d] horas [h] minutos [m]). Por ejemplo, se puede especificar una duración de 90 minutos como 90 minutos o 90m. OPCIONAL. |
| edgeRuntimeOnly | boolean | Si es true, solo se devuelven los registros del Agente de Edge, el Centro de Edge y el demonio de seguridad de Edge. Valor predeterminado: false. OPCIONAL. |
Importante
El conjunto de soporte técnico de IoT Edge puede contener información de identificación personal.
Una solicitud correcta para cargar registros devuelve un "estado": 200 seguido de una carga con el mismo esquema que la respuestaUploadModuleLogs:
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| Nombre | Escribir | Descripción |
|---|---|---|
| estado | string | Uno de estos valores: NotStarted, Running, Completed, Failed o Unknown. |
| message | string | Mensaje si hay un error; cadena vacía en caso contrario. |
| correlationId | string | Identificador para consultar el estado de la solicitud de carga. |
Por ejemplo:
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
}
'
En Azure Portal, invoque el método con el nombre de método UploadSupportBundle y la siguiente carga útil de JSON después de cargar sasURL con su información:
{
"schemaVersion": "1.0",
"sasUrl": "Full path to SAS url",
"since": "2d",
"until": "1d",
"edgeRuntimeOnly": false
}
Obtención del estado de la solicitud de carga
Use el método directo GetTaskStatus para consultar el estado de una solicitud de registros de carga. La carga de la solicitud GetTaskStatus usa el valor de correlationId de la solicitud de registros de carga para obtener el estado de la tarea. El valor de correlationId se devuelve como respuesta a la llamada de método directo UploadModuleLogs.
Este método acepta una carga JSON con el siguiente esquema:
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
Una solicitud correcta para cargar registros devuelve un "estado": 200 seguido de una carga con el mismo esquema que la respuestaUploadModuleLogs:
{
"status": "string",
"message": "string",
"correlationId": "GUID"
}
| Nombre | Escribir | Descripción |
|---|---|---|
| estado | string | Uno de NotStarted, Running, Completed, Failed, "Cancelado" o Unknown. |
| message | string | Mensaje si hay un error; cadena vacía en caso contrario. |
| correlationId | string | Identificador para consultar el estado de la solicitud de carga. |
Por ejemplo:
az iot hub invoke-module-method --method-name 'GetTaskStatus' -n <hub name> -d <device id> -m '$edgeAgent' --method-payload \
'
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
'
En Azure Portal, invoque el método con el nombre de método GetTaskStatus y la siguiente carga útil de JSON después de cargar GUID con su información:
{
"schemaVersion": "1.0",
"correlationId": "<GUID>"
}
Pasos siguientes
Propiedades de los módulos gemelos del agente de IoT Edge y del centro de IoT Edge