Cómo escribir registros de tareas

En este documento, se describe cómo escribir registros de tareas y cómo crear y ejecutar un trabajo de Batch que tenga registros de tareas.

Cuando se habilita el registro para un trabajo, se generan registros de tareas a partir de los mensajes que imprimen los ejecutables del trabajo durante el tiempo de ejecución. Si configuras tus objetos ejecutables para que escriban registros de tareas, puedes mostrar información personalizada en Cloud Logging, lo que puede facilitar el análisis y la solución de problemas de tus trabajos. Para obtener más información sobre los registros, consulta Analiza un trabajo con registros.

Antes de comenzar

  1. Si nunca usaste Batch, revisa Cómo comenzar a usar Batch y habilita Batch completando los requisitos previos para proyectos y usuarios.

  2. Para obtener los permisos que necesitas para crear un trabajo que escriba registros, pídele a tu administrador que te otorgue los siguientes roles de IAM:

    Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

    También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Crea y ejecuta un trabajo que tenga registros de tareas

Para crear y ejecutar un trabajo del que deseas tener registros de tareas, haz lo siguiente cuando crees el trabajo:

  1. Habilita los registros para el trabajo. Esto permite que se generen todos los registros escritos para el trabajo.

  2. Para cada registro de tareas que desees que tenga el trabajo, agrega un comando que escriba un registro de tareas en un ejecutable. Cuando se ejecuta el trabajo, se genera un registro de tareas cada vez que se ejecuta un comando para escribir un registro de tareas.

    Para aprender a escribir registros de tareas, consulta Escribe registros de tareas en este documento.

Escribe registros de tareas

Se escribe un registro de tareas para cualquier contenido que los ejecutables de un trabajo impriman en la transmisión de salida estándar (stdout) o en la transmisión de errores estándar (stderr) durante el tiempo de ejecución. Por ejemplo, puedes escribir registros de tareas con el comando echo. La estructura del registro de tareas resultante varía según el formato que le hayas dado al contenido impreso. Específicamente, puedes escribir cada registro de tareas con una de las siguientes opciones:

Escribe un registro no estructurado imprimiendo una cadena

Los registros no estructurados te permiten definir un mensaje, que es una cadena que aparece en el campo textPayload del registro.

Para escribir un registro no estructurado, imprime una cadena sin formato como se muestra en las siguientes secciones.

Ejemplo de registro no estructurado

Por ejemplo, supongamos que deseas un registro de tareas que contenga la siguiente cadena:

MESSAGE

La impresión de esta cadena de ejemplo genera un registro de tareas similar al siguiente:

insertId: ...
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: INFO
textPayload: MESSAGE
timestamp: ...

Reemplaza lo siguiente:

  • MESSAGE: Es el mensaje, que es una cadena que resume el propósito del registro de tareas, por ejemplo, The summary for a task log..
  • PROJECT_ID: Es el ID del proyecto de tu proyecto.

Puedes imprimir una cadena con varios métodos, como incluir el siguiente comando echo en un ejecutable:

echo MESSAGE

Para ver ejemplos completos de trabajos que usan el comando echo para escribir registros de tareas no estructurados, consulta Crea y ejecuta un trabajo básico.

Escribe un registro estructurado imprimiendo un objeto JSON

Los registros estructurados te permiten definir cualquiera de los siguientes elementos:

Para escribir un registro estructurado, imprime un objeto JSON. En las siguientes secciones, se muestra cómo definir un registro con algunos de los campos estándar y personalizados. Si deseas obtener información para definir un registro con eventos de estado personalizados, consulta también Configura eventos de estado personalizados.

Ejemplo de registro estructurado

Por ejemplo, supongamos que deseas un registro de tareas que contenga la información del siguiente objeto JSON, que define un mensaje, un nivel de gravedad y dos campos personalizados.

{
  "message": "MESSAGE"
  "severity": "SEVERITY"
  "CUSTOM_FIELD_1": CUSTOM_VALUE_1
  "CUSTOM_FIELD_2": CUSTOM_VALUE_2
}

La impresión de este objeto JSON genera un registro de tareas similar al siguiente:

insertId: ...
jsonPayload:
  "CUSTOM_FIELD_1": CUSTOM_VALUE_1
  "CUSTOM_FIELD_2": CUSTOM_VALUE_2
  message: MESSAGE
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: SEVERITY
timestamp: ...

Reemplaza lo siguiente:

  • MESSAGE: Es el mensaje, que es una cadena que resume el propósito del registro de tareas, por ejemplo, The summary for a task log..
  • SEVERITY: Es la gravedad del registro, que puedes usar como filtro cuando consultas los registros de un trabajo. La gravedad debe ser uno de los enums LogSeverity convertidos en una cadena con solo la primera letra en mayúscula. Por ejemplo, para la enumeración ERROR, especifica Error.
  • CUSTOM_FIELD_1 y CUSTOM_FIELD_2: Son los nombres de los campos personalizados del registro de tareas, por ejemplo, custom_field_1 y custom_field_2.
  • CUSTOM_VALUE_1 y CUSTOM_VALUE_2: Son los valores de los campos personalizados del registro de tareas, que pueden ser de varios tipos de datos y pueden necesitar comillas, por ejemplo, "the first custom field" y 2.
  • PROJECT_ID: Es el ID del proyecto de tu proyecto.

Puedes imprimir este objeto JSON de ejemplo con varios métodos. Por ejemplo, en las siguientes muestras, se muestran algunos de los métodos posibles para imprimir el objeto JSON de ejemplo:

  • Imprime una cadena equivalente con el comando echo.

  • Imprime un diccionario equivalente con Python.

Comando echo

Para imprimir el objeto JSON de ejemplo con el comando echo y una cadena equivalente, incluye el siguiente comando en un ejecutable:

echo '{\"message\":\"MESSAGE\", \"severity\":\"SEVERITY\", \"CUSTOM_FIELD_1\":CUSTOM_VALUE_1, \"CUSTOM_FIELD_2\":CUSTOM_VALUE_2}'

Por ejemplo, supongamos que creas y ejecutas un trabajo con el siguiente ejecutable:

"script": {
  "text": "echo '{\"message\":\"The message for a structured log.\", \"severity\":\"Error\", \"custom_field_1\":\"the first custom field\", \"custom_field_2\":2}'"
}

Luego, el registro de tareas resultante es similar al siguiente:

insertId: ...
jsonPayload:
  custom_field_1: the first custom field
  custom_field_2: 2
  message: The summary for a structured task log with error severity.
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: ERROR
timestamp: ...

Python

Para imprimir el objeto JSON de ejemplo con Python y un diccionario equivalente, incluye la siguiente muestra en un ejecutable:

#!/usr/bin/env python3

import json

entry = dict(
    severity="SEVERITY",
    message="MESSAGE",
    CUSTOM_FIELD_1=CUSTOM_VALUE_1,
    CUSTOM_FIELD_2=CUSTOM_VALUE_2,
)
print(json.dumps(entry))

Por ejemplo, supongamos que creas y ejecutas un trabajo con el siguiente ejecutable:

"script": {
  "text": "#!/usr/bin/env python3\n\nimport json\n\nentry = dict(\nseverity=\"Error\",\nmessage=\"The summary for a structured task log with error severity.\",\ncustom_field_1=\"the first custom field\",\ncustom_field_2=2,\n)\nprint(json.dumps(entry))"
}

Luego, el registro de tareas resultante es similar al siguiente:

insertId: ...
jsonPayload:
  custom_field_1: the first custom field
  custom_field_2: 2
  message: The summary for a structured task log with error severity.
labels: ...
logName: projects/PROJECT_ID/logs/batch_task_logs
receiveTimestamp: ...
resource: ...
severity: ERROR
timestamp: ...

¿Qué sigue?