Scrivi log delle attività

Questo documento descrive come scrivere i log delle attività e come creare ed eseguire un job batch con log delle attività.

Quando il logging è abilitato per un job, i log delle attività vengono generati dai messaggi stampati dagli elementi eseguibili del job durante il tempo di esecuzione. Se configuri gli elementi eseguibili per la scrittura dei log delle attività, puoi visualizzare informazioni personalizzate in Cloud Logging, che possono semplificare l'analisi e la risoluzione dei problemi dei job. Per saperne di più sui log, consulta Analisi di un job mediante i log.

Prima di iniziare

Crea ed esegui un job con log delle attività

Per creare ed eseguire un job che vuoi disporre dei log delle attività, segui questi passaggi quando crei il job:

  1. Abilita i log per il job. Ciò consente di generare qualsiasi log scritti per il job.

  2. Per ogni log delle attività che deve avere il job, aggiungi un comando che scriva un log delle attività in un elemento eseguibile. Durante l'esecuzione del job, viene generato un log delle attività ogni volta che viene eseguito un comando per scrivere il log.

    Per informazioni su come scrivere i log delle attività, consulta Scrivere log delle attività in questo documento.

Scrivi log delle attività

Viene scritto un log delle attività per tutti i contenuti stampati dagli eseguibili di un job nel flusso di output standard (stdout) o nel flusso di errori standard (stderr) durante il tempo di esecuzione. Ad esempio, puoi scrivere i log delle attività utilizzando il comando echo. La struttura del log delle attività risultante varia in base al modo in cui hai formattato i contenuti stampati. In particolare, puoi scrivere ogni log delle attività utilizzando una delle seguenti opzioni:

Scrivere un log non strutturato stampando una stringa

I log non strutturati consentono di definire un messaggio, ovvero una stringa visualizzata nel campo textPayload del log.

Per scrivere un log non strutturato, stampa una stringa non formattata, come mostrato nelle sezioni seguenti.

Esempio di log non strutturato

Ad esempio, supponi di volere un log delle attività contenente la seguente stringa:

MESSAGE

La stampa di questa stringa di esempio genera un log delle attività simile al seguente:

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

Sostituisci quanto segue:

  • MESSAGE: il messaggio, ovvero una stringa che riassume lo scopo del log delle attività, ad esempio The summary for a task log..
  • PROJECT_ID: l'ID progetto del progetto.

Puoi stampare una stringa utilizzando diversi metodi, ad esempio includendo il seguente comando echo in un file eseguibile:

echo MESSAGE

Per esempi completi di job che utilizzano il comando echo per scrivere log delle attività non strutturati, consulta Creare ed eseguire un job di base.

Scrivi un log strutturato stampando un oggetto JSON

I log strutturati ti consentono di definire quanto segue:

Per scrivere un log strutturato, stampa un oggetto JSON. Le seguenti sezioni mostrano come definire un log con alcuni dei campi standard e personalizzati. Per scoprire come definire un log con eventi di stato personalizzati, consulta anche Configurare gli eventi di stato personalizzati.

Esempio di log strutturato

Ad esempio, supponi di volere un log delle attività che contiene le informazioni nel seguente oggetto JSON, che definisce un messaggio, la gravità e due campi personalizzati.

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

La stampa di questo oggetto JSON genera un log delle attività simile al seguente:

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

Sostituisci quanto segue:

  • MESSAGE: il messaggio, ovvero una stringa che riassume lo scopo del log delle attività, ad esempio The summary for a task log..
  • SEVERITY: la gravità del log, che puoi utilizzare come filtro durante la visualizzazione dei log di un job. La gravità deve essere una delle enumerazioni LogSeverity convertite in una stringa con solo la prima lettera maiuscola. Ad esempio, per l'enumerazione ERROR, specifica Error.
  • CUSTOM_FIELD_1 e CUSTOM_FIELD_2: i nomi dei campi personalizzati per il log delle attività, ad esempio custom_field_1 e custom_field_2.
  • CUSTOM_VALUE_1 e CUSTOM_VALUE_2: i valori dei campi personalizzati per il log delle attività, che possono essere di vari tipi di dati e potrebbero richiedere virgolette, ad esempio "the first custom field" e 2.
  • PROJECT_ID: l'ID progetto del progetto.

Puoi stampare questo oggetto JSON di esempio utilizzando diversi metodi. Ad esempio, i seguenti esempi dimostrano alcuni dei possibili metodi per stampare l'oggetto JSON di esempio:

  • Stampa una stringa equivalente utilizzando il comando echo.

  • Stampa un dizionario equivalente utilizzando Python.

comando echo

Per stampare l'oggetto JSON di esempio utilizzando il comando echo e una stringa equivalente, includi il seguente comando in un file eseguibile:

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

Ad esempio, supponi di creare ed eseguire un job con il seguente elemento eseguibile:

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

Quindi, il log delle attività risultante è simile al seguente:

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

Per stampare l'oggetto JSON di esempio utilizzando Python e un dizionario equivalente, includi il seguente esempio in un file eseguibile:

#!/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))

Ad esempio, supponi di creare ed eseguire un job con il seguente elemento eseguibile:

"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))"
}

Quindi, il log delle attività risultante è simile al seguente:

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

Passaggi successivi