Scrivere log delle attività

Questo documento descrive come scrivere i log delle attività e come creare ed eseguire un job Batch che contenga i log delle attività.

Quando la registrazione è abilitata per un job, i log delle attività vengono generati dai messaggi che i runnable del job stampano durante l'esecuzione. Configurando i runnable per scrivere i log delle attività, puoi visualizzare informazioni personalizzate in Cloud Logging, il che può semplificare l'analisi e la risoluzione dei problemi dei job. Per saperne di più sui log, vedi Analizzare un job utilizzando i log.

Prima di iniziare

  1. Se non hai mai utilizzato Batch, consulta la sezione Guida introduttiva a Batch e attiva Batch completando i prerequisiti per progetti e utenti.

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

    Per saperne di più sulla concessione dei ruoli, consulta Gestisci 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 il quale vuoi avere i log delle attività, procedi nel seguente modo 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 scrive un log delle attività in un 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 la sezione Scrivere i log delle attività di questo documento.

Scrittura di log delle attività

Un log delle attività viene scritto per qualsiasi contenuto che gli elementi eseguibili di un job stampano nel flusso di output standard (stdout) o nel flusso di errore 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 che viene visualizzata nel campo textPayload del log.

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

Esempio di log non strutturato

Ad esempio, supponiamo che tu voglia un log delle attività che contenga 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 tuo progetto.

Puoi stampare una stringa utilizzando vari metodi, ad esempio includendo il seguente comando echo in un 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 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 campi 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 di voler creare un log delle attività che contenga 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 quando visualizzi i log di un job. La gravità deve essere uno degli enum LogSeverity convertiti in una stringa con solo la prima lettera in maiuscolo. 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 registro delle attività, che possono essere vari tipi di dati e potrebbero richiedere virgolette, ad esempio "the first custom field" e 2.
  • PROJECT_ID: l'ID progetto del tuo progetto.

Puoi stampare questo oggetto JSON di esempio 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 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 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 runnable:

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