En este documento, se describe cómo escribir registros de tareas y cómo crear y ejecutar un trabajo por lotes que tenga registros de tareas.
Cuando el registro está habilitado para un trabajo, los registros de tareas se generan a partir de mensajes que los ejecutables del trabajo imprimen durante el tiempo de ejecución. Cuando configuras los ejecutables para que escriban registros de tareas, puedes mostrar información personalizada en Cloud Logging, lo que facilita el análisis y la solución de problemas de los trabajos. Para obtener más información sobre los registros, consulta Usa registros para analizar un trabajo.
Antes de comenzar
- Si no has usado Batch antes, revisa Comienza a usar Batch y completa los requisitos previos para los proyectos y usuarios a fin de habilitar Batch.
-
Si quieres 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 crear un trabajo, sigue estos pasos:
-
Editor de trabajos por lotes (
roles/batch.jobsEditor
) en el proyecto -
Usuario de cuenta de servicio (
roles/iam.serviceAccountUser
) en la cuenta de servicio del trabajo, que de forma predeterminada es la cuenta de servicio predeterminada de Compute Engine
-
Editor de trabajos por lotes (
-
Para ver los registros, usa el Visor de registros (
roles/logging.viewer
) del proyecto.
Si quieres obtener más información para otorgar roles, consulta Administra el acceso.
Es posible que también puedas obtener los permisos necesarios a través de los roles personalizados o de otros roles predefinidos.
-
Para crear un trabajo, sigue estos pasos:
Crea y ejecuta un trabajo que tenga registros de tareas
Para crear y ejecutar un trabajo que quieras tener registros de tareas, haz lo siguiente cuando crees el trabajo:
- Habilita los registros para el trabajo. Esto permite generar cualquier registro escrito para el trabajo.
Por 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
Un registro de tareas se escribe 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 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 según el formato del contenido impreso. Específicamente, puedes escribir cada registro de tareas con una de las siguientes opciones:
Imprime una cadena para escribir un registro no estructurado. Los registros no estructurados son simples y solo te permiten definir el campo
textPayload
del registro.Escribe un registro estructurado imprimiendo JSON. Los registros estructurados requieren el formato JSON, que te permite definir varios campos, incluidos algunos campos de registro estándar, campos personalizados y eventos de estado personalizados.
Por ejemplo, puedes usar registros estructurados de tareas para definir la gravedad del registro, que puedes usar como filtro cuando visualizas los registros de un trabajo.
Imprime una cadena para escribir un registro no estructurado
Los registros no estructurados te permiten definir un mensaje, que es una string que aparece en el campo textPayload
del registro.
Para escribir un registro no estructurado, imprime una string 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
Cuando se imprime 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: ...
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.
Cómo imprimir una cadena
Puedes imprimir una cadena con una variedad de métodos, por ejemplo, si incluyes el siguiente comando echo
en un ejecutable:
echo MESSAGE
Si deseas 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.
Escribir un registro estructurado imprimiendo un objeto JSON
Los registros estructurados te permiten definir cualquiera de las siguientes opciones:
- Campos estándar que admite el agente de Cloud Logging
- Campos personalizados
- Eventos de estado personalizados
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 quieres aprender a definir un registro con eventos de estado personalizados, consulta Configura eventos de estado personalizados.
Ejemplo de registro estructurado
Por ejemplo, supongamos que deseas un registro de tareas que contenga la información en el siguiente objeto JSON, que define un mensaje, una gravedad y dos campos personalizados.
{
"message": "MESSAGE"
"severity": "SEVERITY"
"CUSTOM_FIELD_1": CUSTOM_VALUE_1
"CUSTOM_FIELD_2": CUSTOM_VALUE_2
}
Cuando se imprime este objeto JSON, se 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
: La gravedad del registro, que puedes usar como filtro cuando visualizas los registros de un trabajo. La gravedad debe ser una de las enumsLogSeverity
convertidas en una cadena en la que solo la primera letra esté en mayúscula. Por ejemplo, para la enumERROR
, especificaError
.CUSTOM_FIELD_1
yCUSTOM_FIELD_2
: Son los nombres de los campos personalizados para el registro de tareas, por ejemplo,custom_field_1
ycustom_field_2
.CUSTOM_VALUE_1
yCUSTOM_VALUE_2
: Son los valores de los campos personalizados del registro de tareas, que pueden ser de varios tipos de datos y podrían necesitar comillas, por ejemplo,"the first custom field"
y2
.PROJECT_ID
: Es el ID del proyecto.
Cómo imprimir un objeto JSON
Puedes imprimir este objeto JSON de ejemplo con una variedad de métodos. En los siguientes ejemplos, se muestran algunos de los métodos posibles para imprimir el objeto JSON de ejemplo:
- Imprime una string 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 string 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 el siguiente ejemplo 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?
- Para obtener más información sobre el formato de los registros, consulta Registro estructurado en la documentación de Cloud Logging.
- Obtén información para escribir registros estructurados de tareas que incluyan eventos de estado personalizados.
- Aprende a ver los registros de tareas de un trabajo.
- Obtén más información sobre las opciones de creación de trabajos.