Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzare i log della piattaforma per risolvere i problemi relativi agli argomenti di importazione di Cloud Storage

Questa guida spiega come utilizzare i log della piattaforma Google Cloud per risolvere i problemi che si verificano quando utilizzi gli argomenti di importazione di Cloud Storage per importare i dati.

Informazioni sull'errore di importazione nei problemi di importazione di Cloud Storage

Gli argomenti di importazione di Cloud Storage possono riscontrare problemi che impediscono l'importazione dei dati. Ad esempio, quando utilizzi un argomento di importazione di Cloud Storage, potresti riscontrare problemi di importazione di un oggetto o di parte di un oggetto di Cloud Storage.

L'elenco seguente descrive i motivi degli errori di importazione negli argomenti di importazione di Cloud Storage che generano log della piattaforma:

Dimensione messaggio
- I singoli messaggi non possono superare i 10 MB. In questo caso, l'intero messaggio viene ignorato.
- Se utilizzi il formato Avro o Avro di Pub/Sub, i blocchi di messaggi non possono superare i 16 MB. I blocchi di messaggi più grandi vengono ignorati.
Attributi del messaggio
- I messaggi possono avere un massimo di 100 attributi. Eventuali attributi aggiuntivi vengono eliminati al momento dell'importazione del messaggio.
- Le chiavi degli attributi non possono essere più grandi di 256 byte e i valori non possono essere più grandi di 1024 byte. Le chiavi o i valori più grandi vengono rimossi dal messaggio al momento dell'importazione.
  
  Per ulteriori informazioni sulle linee guida per l'utilizzo delle chiavi e degli attributi dei messaggi, consulta Utilizzare gli attributi per pubblicare un messaggio.
Formattazione Avro
- Assicurati che gli oggetti Avro siano formattati correttamente. La formattazione non corretta impedisce l'importazione del messaggio.
Formato dei dati
- Assicurati di utilizzare una versione Avro supportata. I formati non supportati non vengono elaborati.

Informazioni sui log della piattaforma

Un servizio Google Cloud supportato genera il proprio insieme di log della piattaforma, acquisendo eventi e attività pertinenti al funzionamento del servizio. Questi log della piattaforma contengono informazioni dettagliate su ciò che accade all'interno di un servizio, tra cui operazioni riuscite, errori, avvisi e altri eventi importanti.

I log della piattaforma fanno parte di Cloud Logging e condividono le stesse funzionalità. Ad esempio, di seguito è riportato un elenco di funzionalità importanti per i log della piattaforma:

I log sono in genere strutturati come oggetti JSON che consentono ulteriori query e filtri.
Puoi visualizzare i log della piattaforma utilizzando Logging nella console.
I log della piattaforma possono essere integrati anche con Cloud Monitoring e altri strumenti di monitoraggio per creare dashboard, avvisi e altri meccanismi di monitoraggio.
L'archiviazione dei log comporta costi in base al volume importato e al periodo di conservazione.

Per ulteriori informazioni sui log della piattaforma, consulta Log della piattaforma Google Cloud.

Ruoli e autorizzazioni richiesti per utilizzare i log della piattaforma

Prima di iniziare, verifica di avere accesso a Log. Devi disporre del ruolo IAM (Identity and Access Management) Visualizzatore dei log (roles/logging.viewer). Per ulteriori informazioni sull'accesso ai log, consulta Controllo dell'accesso con IAM.

Di seguito viene descritto come verificare e concedere l'accesso IAM:

Visualizza l'accesso corrente per verificare l'accesso di ogni entità.
Concedere un ruolo alle entità pertinenti del progetto.

Attivare i log della piattaforma

I log della piattaforma sono disattivati per impostazione predefinita per gli argomenti di importazione. Puoi attivare i log della piattaforma quando crei o aggiorni un argomento di importazione di Cloud Storage.

Per disattivare i log della piattaforma, aggiorna l'argomento di importazione di Cloud Storage.

Attivare i log della piattaforma durante la creazione di un argomento di importazione di Cloud Storage

Assicurati di aver completato i prerequisiti per la creazione di un argomento di importazione da Cloud Storage.

Per creare un argomento di importazione Cloud Storage con i log della piattaforma abilitati, segui questi passaggi:

Console

Nella console Google Cloud, vai alla pagina Topic.

Vai ad Argomenti
Fai clic su Crea argomento.
Viene visualizzata la pagina dei dettagli dell'argomento.
Nel campo ID argomento, inserisci un ID per l'argomento di importazione Cloud Storage.
Per ulteriori informazioni sugli argomenti relativi alla denominazione, consulta le linee guida per i nomi.
Seleziona Aggiungi una sottoscrizione predefinita.
Seleziona Attiva importazione.
Specifica le opzioni per l'importazione seguendo le istruzioni riportate nell'articolo Creare un argomento di importazione da Cloud Storage.
Seleziona Attiva log della piattaforma.
Mantieni le altre impostazioni predefinite.
Fai clic su Crea argomento.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Per attivare i log della piattaforma, assicurati che il --ingestion-log-severity flag sia impostato su WARNING o su un valore superiore. Esegui il comando gcloud pubsub topics create:
```
gcloud pubsub topics create TOPIC_ID\
    --cloud-storage-ingestion-bucket=BUCKET_NAME\
    --cloud-storage-ingestion-input-format=INPUT_FORMAT\
    --ingestion-log-severity=WARNING
```
Sostituisci quanto segue:
- TOPIC_ID: il nome o l'ID dell'argomento.
- BUCKET_NAME: specifica il nome di un bucket esistente. Ad esempio, prod_bucket. Il nome del bucket non deve includere l'ID progetto. Per creare un bucket, consulta la sezione Creare bucket.
- INPUT_FORMAT: specifica il formato degli oggetti importati. Può essere text, avro o pubsub_avro. Per ulteriori informazioni su queste opzioni, consulta Formato di input.

Se riscontri problemi, consulta la sezione Risolvere i problemi di un argomento di importazione di Cloud Storage.

Attivare i log della piattaforma durante l'aggiornamento di un argomento di importazione di Cloud Storage

Procedi nel seguente modo:

Console

Nella console Google Cloud, vai alla pagina Topic.

Vai ad Argomenti
Fai clic sull'argomento relativo all'importazione da Cloud Storage.
Nella pagina dei dettagli dell'argomento, fai clic su Modifica.
Seleziona Attiva log della piattaforma.
Fai clic su Aggiorna.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Per evitare di perdere le impostazioni per l'argomento di importazione, assicurati di includerle tutte ogni volta che aggiorni l'argomento. Se ne ometti una, Pub/Sub reimposta l'impostazione sul valore predefinito originale.

Per attivare i log della piattaforma, assicurati che l'impostazione ingestion-log-severity sia impostata su WARNING. Esegui il comando gcloud pubsub topics update con tutti i flag menzionati nel seguente esempio:
```
gcloud pubsub topics update TOPIC_ID \
    --cloud-storage-ingestion-bucket=BUCKET_NAME\
    --cloud-storage-ingestion-input-format=INPUT_FORMAT\
    --cloud-storage-ingestion-text-delimiter=TEXT_DELIMITER\
    --cloud-storage-ingestion-minimum-object-create-time=MINIMUM_OBJECT_CREATE_TIME\
    --cloud-storage-ingestion-match-glob=MATCH_GLOB
    --ingestion-log-severity=WARNING
```
Sostituisci quanto segue:
- TOPIC_ID è l'ID o il nome dell'argomento. Questo campo non può essere aggiornato.
- BUCKET_NAME: specifica il nome di un bucket esistente. Ad esempio, prod_bucket. Il nome del bucket non deve includere l'ID progetto.
- INPUT_FORMAT: specifica il formato degli oggetti importati. Può essere text, avro o pubsub_avro. Per ulteriori informazioni su queste opzioni, consulta Formato di input.
- TEXT_DELIMITER: specifica il delimitatore con cui suddividere gli oggetti di testo in messaggi Pub/Sub. Deve essere costituito da un solo carattere e deve essere impostato solo quando INPUT_FORMAT è text. Il valore predefinito è il carattere di nuova riga (\n).
  
  Quando utilizzi gcloud CLI per specificare il delimitatore, presta molta attenzione alla gestione dei caratteri speciali come il nuovo riga \n. Utilizza il formato '\n' per assicurarti che il delimitatore venga interpretato correttamente. Se utilizzi semplicemente \n senza virgolette o sfugge, il delimitatore sarà "n".
- MINIMUM_OBJECT_CREATE_TIME: specifica il tempo minimo in cui è stato creato un oggetto affinché possa essere importato. Deve essere in UTC nel formato YYYY-MM-DDThh:mm:ssZ. Ad esempio: 2024-10-14T08:30:30Z.
  
  È valida qualsiasi data, passata o futura, compresa tra 0001-01-01T00:00:00Z e 9999-12-31T23:59:59Z.
- MATCH_GLOB: specifica il pattern glob da associare per consentire l'importazione di un oggetto. Quando utilizzi gcloud CLI, un pattern di corrispondenza con caratteri * deve avere il carattere * formattato come carattere di escape nel formato \*\*.txt o l'intero pattern di corrispondenza deve essere tra virgolette "**.txt" o '**.txt'. Per informazioni sulla sintassi supportata per i pattern glob, consulta la documentazione di Cloud Storage.

Disattivare i log della piattaforma

Procedi nel seguente modo:

Console

Nella console Google Cloud, vai alla pagina Topic.

Vai ad Argomenti
Fai clic sull'argomento relativo all'importazione da Cloud Storage.
Nella pagina dei dettagli dell'argomento, fai clic su Modifica.
Deseleziona Abilita log della piattaforma.
Fai clic su Aggiorna.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Per evitare di perdere le impostazioni per l'argomento di importazione, assicurati di includerle tutte ogni volta che aggiorni l'argomento. Se ne ometti una, Pub/Sub reimposta l'impostazione sul valore predefinito originale.

Per disattivare i log della piattaforma, assicurati che l'attributo ingestion-log-severity sia impostato su DISABLED. Esegui il comando gcloud pubsub topics update con tutti i flag menzionati nel seguente esempio:
```
gcloud pubsub topics update TOPIC_ID \
    --cloud-storage-ingestion-bucket=BUCKET_NAME\
    --cloud-storage-ingestion-input-format=INPUT_FORMAT\
    --cloud-storage-ingestion-text-delimiter=TEXT_DELIMITER\
    --cloud-storage-ingestion-minimum-object-create-time=MINIMUM_OBJECT_CREATE_TIME\
    --cloud-storage-ingestion-match-glob=MATCH_GLOB
    --ingestion-log-severity=DISABLED
```
Sostituisci quanto segue:
- TOPIC_ID è l'ID o il nome dell'argomento. Questo campo non può essere aggiornato.
- BUCKET_NAME: specifica il nome di un bucket esistente. Ad esempio, prod_bucket. Il nome del bucket non deve includere l'ID progetto.
- INPUT_FORMAT: specifica il formato degli oggetti importati. Può essere text, avro o pubsub_avro. Per ulteriori informazioni su queste opzioni, consulta Formato di input.
- TEXT_DELIMITER: specifica il delimitatore con cui suddividere gli oggetti di testo in messaggi Pub/Sub. Deve essere costituito da un solo carattere e deve essere impostato solo quando INPUT_FORMAT è text. Il valore predefinito è il carattere di nuova riga (\n).
  
  Quando utilizzi gcloud CLI per specificare il delimitatore, presta molta attenzione alla gestione dei caratteri speciali come il nuovo riga \n. Utilizza il formato '\n' per assicurarti che il delimitatore venga interpretato correttamente. Se utilizzi semplicemente \n senza virgolette o sfugge, il delimitatore sarà "n".
- MINIMUM_OBJECT_CREATE_TIME: specifica il tempo minimo in cui è stato creato un oggetto affinché possa essere importato. Deve essere in UTC nel formato YYYY-MM-DDThh:mm:ssZ. Ad esempio: 2024-10-14T08:30:30Z.
  
  È valida qualsiasi data, passata o futura, compresa tra 0001-01-01T00:00:00Z e 9999-12-31T23:59:59Z.
- MATCH_GLOB: specifica il pattern glob da associare per consentire l'importazione di un oggetto. Quando utilizzi gcloud CLI, un pattern di corrispondenza con caratteri * deve avere il carattere * formattato come carattere di escape nel formato \*\*.txt o l'intero pattern di corrispondenza deve essere tra virgolette "**.txt" o '**.txt'. Per informazioni sulla sintassi supportata per i pattern glob, consulta la documentazione di Cloud Storage.

Visualizza i log della piattaforma

Per visualizzare i log della piattaforma per l'argomento di importazione di Cloud Storage, procedi nel seguente modo:

Console Google Cloud

Nella console Google Cloud, vai a Esplora log.

Vai a Esplora log
Seleziona un progetto Google Cloud.
Se necessario, dal menu Esegui l'upgrade, passa da Visualizzatore log legacy a Esplora log.
Per filtrare i log in modo da visualizzare solo le voci relative agli argomenti di importazione di Cloud Storage, digita resource.type="resource.type=pubsub_topic AND severity=WARNING nel campo della query e fai clic su Esegui query.
Nel riquadro Risultati delle query, fai clic su Modifica ora per modificare il periodo di tempo per cui restituire i risultati.

Per ulteriori informazioni sull'utilizzo di Esplora log, consulta Utilizzo di Esplora log.

Interfaccia a riga di comando gcloud

Per utilizzare gcloud CLI per cercare i log della piattaforma per gli argomenti di importazione di Cloud Storage, utilizza il comando gcloud logging read.

Specifica un filtro per limitare i risultati ai log della piattaforma per gli argomenti di importazione di Cloud Storage.

gcloud logging read "resource.type=pubsub_topic AND severity=WARNING"

API Cloud Logging

Utilizza il metodo entries.list dell'API Cloud Logging.

Per filtrare i risultati in modo da includere solo i log della piattaforma per gli argomenti di importazione di Cloud Storage, utilizza il campo filter. Di seguito è riportato un esempio di oggetto richiesta JSON.

{
"resourceNames":
  [
    "projects/my-project-name"
  ],
  "orderBy": "timestamp desc",
  "filter": "resource.type=\"pubsub_topic\" AND severity=WARNING"
}

Visualizzare e comprendere il formato dei log della piattaforma

La sezione seguente include log di piattaforma di esempio e descrive i campi per i log di piattaforma.

Tutti i campi specifici dei log della piattaforma sono contenuti in un oggetto jsonPayload.

Errore Avro

{
  "insertId": "1xnzx8md4768",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "cloudStorageFailure": {
      "objectGeneration": "1661148924738910",
      "bucket": "bucket_in_avro_format",
      "objectName": "counts/taxi-2022-08-15T06:10:00.000Z-2022-08-15T06:15:00.000Z-pane-0-last-00-of-01",
      "avroFailureReason": {}
    },
    "topic": "projects/interpod-p2-management/topics/avro_bucket_topic",
    "errorMessage": "Unable to parse the header of the object. The object won't be ingested."
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "project_id": "interpod-p2-management",
      "topic_id": "avro_bucket_topic"
    }
  },
  "timestamp": "2024-10-07T18:55:45.650103193Z",
  "severity": "WARNING",
  "logName": "projects/interpod-p2-management/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-07T18:55:46.678221398Z"
}

Campo log	Descrizione
`insertId`	Un identificatore univoco per la voce di log.
`jsonPayload.@type`	Identifica il tipo di evento. Sempre `type.googleapis.com/google.pubsub.v1.IngestionFailureEvent`.
`jsonPayload.cloudStorageFailure.objectGeneration`	Il numero di generazione dell'oggetto Cloud Storage.
`jsonPayload.cloudStorageFailure.bucket`	Il bucket Cloud Storage contenente l'oggetto.
`jsonPayload.cloudStorageFailure.objectName`	Il nome dell'oggetto Cloud Storage.
`jsonPayload.cloudStorageFailure.avroFailureReason`	Contiene dettagli più specifici sugli errori di analisi Avro. Questo campo viene lasciato vuoto.
`jsonPayload.topic`	L'argomento Pub/Sub a cui era destinato il messaggio.
`jsonPayload.errorMessage`	Un messaggio di errore leggibile.
`resource.type`	Il tipo di risorsa. Sempre `pubsub_topic`.
`resource.labels.project_id`	L'ID progetto Google Cloud.
`resource.labels.topic_id`	L'ID argomento Pub/Sub.
`timestamp`	Timestamp di generazione della voce del log.
`severity`	Il livello di gravità è `WARNING`.
`logName`	Nome del log.
`receiveTimestamp`	Timestamp della voce di log ricevuta.

Errore di testo

{
  "insertId": "1kc4puoag",
  "jsonPayload": {
    "@type": "type.googleapis.com/google.pubsub.v1.IngestionFailureEvent",
    "cloudStorageFailure": {
      "bucket": "bucket_in_text_format",
      "apiViolationReason": {},
      "objectName": "counts/taxi-2022-08-15T06:10:00.000Z-2022-08-15T06:15:00.000Z-pane-0-last-00-of-01",
      "objectGeneration": "1727990048026758"
    },
    "topic": "projects/interpod-p2-management/topics/large_text_bucket_topic",
    "errorMessage": "The message has exceeded the maximum allowed size of 10000000 bytes. The message won't be published."
  },
  "resource": {
    "type": "pubsub_topic",
    "labels": {
      "topic_id": "large_text_bucket_topic",
      "project_id": "interpod-p2-management"
    }
  },
  "timestamp": "2024-10-09T14:09:07.760488386Z",
  "severity": "WARNING",
  "logName": "projects/interpod-p2-management/logs/pubsub.googleapis.com%2Fingestion_failures",
  "receiveTimestamp": "2024-10-09T14:09:08.483589656Z"
}

Campo log	Descrizione
`insertId`	Un identificatore univoco per la voce di log.
`jsonPayload.@type`	Identifica il tipo di evento. Sempre `type.googleapis.com/google.pubsub.v1.IngestionFailureEvent`.
`jsonPayload.cloudStorageFailure.objectGeneration`	Il numero di generazione dell'oggetto Cloud Storage.
`jsonPayload.cloudStorageFailure.bucket`	Il bucket Cloud Storage contenente l'oggetto.
`jsonPayload.cloudStorageFailure.objectName`	Il nome dell'oggetto Cloud Storage.
`jsonPayload.cloudStorageFailure.apiViolationReason`	Contiene i dettagli sulla violazione dell'API. Questo campo viene lasciato vuoto.
`jsonPayload.topic`	L'argomento Pub/Sub.
`jsonPayload.errorMessage`	Un messaggio leggibile.
`resource.type`	Tipo di risorsa, sempre `pubsub_topic`.
`resource.labels.project_id`	ID progetto Google Cloud.
`resource.labels.topic_id`	ID argomento Pub/Sub.
`timestamp`	Timestamp di generazione della voce del log.
`severity`	Il livello di gravità è `WARNING`.
`logName`	Nome del log.
`receiveTimestamp`	Ora in cui la voce di log è stata ricevuta da Logging.