Scrivere 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 la registrazione è attivata per un job, i log delle attività vengono generati dai messaggi stampati dai componenti eseguibili del job durante l'esecuzione. Configurando i file eseguibili per scrivere log delle attività, puoi visualizzare informazioni personalizzate in Cloud Logging, il che può contribuire a semplificare l'analisi e la risoluzione dei problemi dei job. Per scoprire di più sui log, consulta Analisi di un job utilizzando i log.

Prima di iniziare

  1. Se non hai mai utilizzato Batch, consulta la guida introduttiva all'utilizzo di Batch e attivalo completando i prerequisiti per progetti e utenti.

  2. Per ottenere le autorizzazioni necessarie per creare un job che scriva i log, chiedi all'amministratore di concederti i seguenti ruoli IAM:

    Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Crea ed esegui un job con log delle attività

Per creare ed eseguire un job per cui vuoi avere i log delle attività, segui questi passaggi quando crei il job:

  1. Attiva i log per il job. In questo modo, vengono generati tutti i log scritti per il job.

  2. Per ogni log delle attività che vuoi che il job abbia, aggiungi un comando che scriva un log delle attività in un file eseguibile. Quando il job viene eseguito, viene generato un log delle attività ogni volta che viene eseguito un comando per scrivere un log delle attività.

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

Scrivere log delle attività

Viene scritto un log dell'attività per tutti i contenuti stampati dagli elementi eseguibili di un job nell'stream di output standard (stdout) o nello stream di errori standard (stderr) durante l'esecuzione. Ad esempio, puoi scrivere i log delle attività utilizzando il comando echo. La struttura del log delle attività risultante varia in base alla formattazione dei contenuti stampati. Nello specifico, puoi scrivere ogni log delle attività utilizzando una delle seguenti opzioni:

Scrivere un log non strutturato stampando una stringa

I log non strutturati ti 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, supponiamo che tu voglia 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: il ID progetto del tuo progetto.

Puoi stampare una stringa utilizzando vari 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 strutturate, consulta Creare ed eseguire un job di base.

Scrivere un log strutturato stampando un oggetto JSON

I log strutturati ti consentono di definire uno dei seguenti elementi:

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

Esempio di log strutturato

Ad esempio, supponiamo che tu voglia un log delle attività contenente le informazioni riportate nel seguente oggetto JSON, che definisce un messaggio, una 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 quando visualizzi i log di un job. La gravità deve essere uno degli enumerati LogSeverity convertito in una stringa con solo la prima lettera in maiuscolo. Ad esempio, per l'enum 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 es. "the first custom field" e 2.
  • PROJECT_ID: il ID progetto del tuo progetto.

Puoi stampare questo esempio di oggetto JSON utilizzando diversi metodi. Ad esempio, i seguenti esempi mostrano 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, supponiamo di creare ed eseguire un job con il seguente eseguibile:

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

Il log dell'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, supponiamo di creare ed eseguire un job con il seguente 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))"
}

Il log dell'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