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 de una tarea, se generan registros de tareas a partir de los mensajes que imprimen los elementos ejecutables de la tarea durante el tiempo de ejecución. Si configuras tus elementos ejecutables para que escriban registros de tareas, puedes mostrar información personalizada en Cloud Logging, lo que puede ayudarte a analizar y solucionar problemas de tus tareas más fácilmente. Para obtener más información sobre los registros, consulta Analizar un trabajo con registros.

Antes de empezar

  1. Si no has usado Batch antes, consulta el artículo Empezar 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, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:

    Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

    También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Crear y ejecutar una tarea que tenga registros de tareas

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

  1. Habilita los registros del trabajo. De esta forma, se pueden generar los registros escritos para el trabajo.

  2. Por cada registro de tareas que quieras que tenga el trabajo, añade un comando que escriba un registro de tareas en un elemento 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 saber cómo escribir registros de tareas, consulta Escribir registros de tareas en este documento.

Escribir registros de tareas

Se escribe un registro de tareas para cualquier contenido que los elementos ejecutables de una tarea impriman en el flujo de salida estándar (stdout) o en el flujo de error 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 en función del formato que hayas aplicado al contenido impreso. En concreto, puedes escribir cada registro de tareas con una de las siguientes opciones:

Escribir 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 secciones siguientes.

Ejemplo de registro no estructurado

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

MESSAGE

Al imprimir esta cadena de ejemplo, se 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: ...

Haz los cambios siguientes:

  • MESSAGE: 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: el ID de proyecto de tu proyecto.

Puedes imprimir una cadena de texto de varias formas. Por ejemplo, puedes incluir el siguiente comando echo en un elemento ejecutable:

echo MESSAGE

Para ver ejemplos completos de tareas que usan el comando echo para escribir registros de tareas no estructurados, consulta Crear y ejecutar una tarea básica.

Escribir 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 campos personalizados. Si quiere saber cómo definir un registro con eventos de estado personalizados, consulte también Configurar eventos de estado personalizados.

Ejemplo de registro estructurado

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

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

Al imprimir este objeto JSON, se obtiene 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: ...

Haz los cambios siguientes:

  • MESSAGE: el mensaje, que es una cadena que resume el propósito del registro de tareas. Por ejemplo, The summary for a task log..
  • SEVERITY: la gravedad del registro, que puedes usar como filtro cuando consultes los registros de un trabajo. La gravedad debe ser uno de los LogSeverityenums convertidos en una cadena con solo la primera letra en mayúscula. Por ejemplo, en el caso del enum ERROR, especifica Error.
  • CUSTOM_FIELD_1 y CUSTOM_FIELD_2: los nombres de los campos personalizados del registro de tareas, como custom_field_1 y custom_field_2.
  • CUSTOM_VALUE_1 y CUSTOM_VALUE_2: 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: el ID de proyecto de tu proyecto.

Puedes imprimir este objeto JSON de ejemplo con varios métodos. Por ejemplo, en los siguientes ejemplos 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 crea y ejecuta un trabajo con el siguiente elemento ejecutable:

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

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 el siguiente ejemplo en un archivo 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 crea y ejecuta un trabajo con el siguiente elemento 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))"
}

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: ...

Siguientes pasos