Monitoraggio e risoluzione dei problemi

Questa pagina descrive come ottenere informazioni sugli errori che si sono verificati nelle importazioni di cataloghi ed eventi utente e in altre operazioni dell'API in Vertex AI Search per la vendita al dettaglio.

Per assistenza sulla configurazione degli avvisi, vedi Configurare gli avvisi di Cloud Monitoring.

Introduzione

Fornire all'API informazioni accurate sul catalogo ed eventi utente è importante per ottenere risultati della massima qualità. Monitorare e comprendere la fonte degli errori ti aiuta a trovarli e correggerli sul tuo sito.

Visualizzare gli errori di integrazione aggregati

Per visualizzare gli errori aggregati generati dalle procedure di caricamento dei dati e dalle richieste di previsione o di ricerca, utilizza la pagina Monitoraggio.

Questa pagina mostra tutti gli errori dell'API Vertex AI Search for Retail. Puoi visualizzare gli errori relativi al catalogo dei prodotti, agli eventi utente, alle previsioni dei consigli, ai risultati di ricerca e ai modelli. Il sistema registra anche gli errori delle importazioni, ad esempio una riga con formato non corretto nel file Cloud Storage. Il sistema registra fino a 100 errori per file di importazione. Puoi definire il periodo di tempo per cui vengono visualizzati gli errori e filtrare in base al tipo di errore.

Puoi fare clic su un singolo errore per visualizzare i relativi log in Cloud Logging.

Puoi aprire i singoli log degli errori espandendoli. I log degli errori forniscono maggiori dettagli sulla richiesta, inclusi i payload di richiesta e risposta e i dettagli dell'errore. Queste informazioni possono aiutarti a determinare dove si trova la chiamata al metodo errata nel tuo sito.

Per gli errori JSON non validi, puoi ottenere ulteriori informazioni sul problema espandendo il campo status.

Visualizzare lo stato di un'operazione di integrazione specifica

Puoi visualizzare lo stato di un'operazione di integrazione specifica nella finestra Stato attività:

1. Vai alla pagina Dati> nella console Ricerca per la vendita al dettaglio.
   
   Vai alla pagina Dati

2. Fai clic su Stato dell'attività.

   La finestra Stato attività mostra lo stato delle operazioni a lunga esecuzione sul tuo catalogo di prodotti, sugli eventi utente e sui controlli.

   In questa finestra puoi esaminare gli errori relativi a operazioni di integrazione specifiche.

3. Fai clic su Visualizza log nella colonna Dettagli di qualsiasi operazione con un errore per esaminare i relativi file di log in Cloud Logging.

Visualizza i log in Cloud Logging

Per aprire i file di log direttamente in Cloud Logging, segui la procedura riportata di seguito. Per visualizzare i log, devi disporre del ruolo Visualizzatore log (roles/logging.viewer).

1. Vai a Esplora log nella console Google Cloud. Vai a Esplora log

2. Seleziona il progetto Vertex AI Search for Retail dal selettore di progetti.

3. Fai clic sul menu a discesa Risorsa e seleziona API consumata > Cloud per la vendita al dettaglio.

Per ulteriori informazioni su Esplora log, consulta Visualizza i log utilizzando Esplora log.

Ad esempio, questo link apre i log di tutti gli errori di Vertex AI Search for Retail nell'ora precedente:

Aprire i log di Vertex AI Search for Retail

Per configurare i log API da scrivere, consulta Configurare la registrazione.

Configura logging

Puoi configurare i log dei servizi da scrivere in Logging. La configurazione del logging consente di impostare i livelli di gravità a cui scrivere i log, attivare o disattivare il logging e ignorare le impostazioni di logging predefinite per servizi specifici.

Ogni richiesta API effettuata da un utente finale può generare una voce di log. Una voce contiene informazioni come il metodo API, la data e l'ora dell'invocazione, il codice risposta e i corpi della richiesta e della risposta. La configurazione di logging di un progetto specifica i tipi di log generati dall'API da scrivere in Logging, con la possibilità di specificare in modo granulare le configurazioni di logging per servizi API specifici.

Per aggiornare le configurazioni di logging, devi disporre del ruolo editor di Vertex AI Search per il retail.

Puoi utilizzare la console o l'API LoggingConfig per configurare Logging.

Console

Per aggiornare le configurazioni di logging nella console:

1. Vai alla pagina Monitoraggio nella console Ricerca per la vendita al dettaglio.
   
   Vai alla pagina Monitoraggio

2. Fai clic su Configurazione di logging.

3. Per impostare una configurazione di logging globale, seleziona un livello di logging. Se selezioni LOG_ALL, inserisci anche una frequenza di campionamento per i log riusciti.

4. Per impostare una configurazione a livello di servizio, seleziona un servizio da aggiornare e il relativo livello di logging. Questa impostazione sostituisce la configurazione del logging globale.

curl

Per aggiornare le configurazioni di logging utilizzando l'API, utilizza la risorsa LoggingConfig. Consulta il riferimento all'API LoggingConfig.

1. Per visualizzare la configurazione di logging corrente, utilizza loggingConfig.Get.

   curl -X GET \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json" \
       "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/loggingConfig"
   

   • PROJECT_ID: l'ID del progetto.

2. Per aggiornare la configurazione di registrazione, utilizza il metodo loggingConfig.Patch. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API LoggingConfig.

   In questo esempio viene utilizzato loggingConfig.Patch per impostare la configurazione di logging globale su LOG_WARNINGS_AND_ABOVE. Imposta inoltre due configurazioni a livello di servizio: CatalogService è impostato su LOG_WARNINGS_AND_ABOVE e ControlService su LOG_ALL.

   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/loggingConfig" \
     --data '{
       "name": "projects/PROJECT_ID/loggingConfig",
       "default_log_generation_rule": {"logging_level": "LOG_ERRORS_AND_ABOVE"},
       "service_log_generation_rules": [
         {
           "service_name": "CatalogService",
           "log_generation_rule": {
             "logging_level": "LOG_WARNINGS_AND_ABOVE"
             }
         },
         {
           "service_name": "ControlService",
           "log_generation_rule": {
               "logging_level": "LOG_ALL", "info_log_sample_rate": "0.1"
               }
           }
         ]
       }'
   

Livelli di logging

Solo i log di alcuni livelli di gravità vengono scritti in Logging. Le impostazioni del livello di logging determinano quali log generati da un metodo dell'API vengono scritti in Logging.

Quando non è impostata alcuna configurazione di logging a livello di servizio per un metodo API, viene utilizzata l'impostazione del livello di logging globale.

L'impostazione predefinita del livello di logging è LOG_WARNINGS_AND_ABOVE.

Il campo logging_level accetta i seguenti valori:

• LOGGING_DISABLED: nessun log scritto.
• LOG_ERRORS_AND_ABOVE: registra solo gli errori.
• LOG_WARNINGS_AND_ABOVE: registra solo errori e avvisi.
• LOG_ALL: registra tutto, inclusi i log di successo come i log INFO.

Frequenza di campionamento per i log riusciti

Se imposti il livello di logging su LOG_ALL, ma non vuoi registrare ogni log riuscito, puoi specificare una frequenza di campionamento. Ad esempio, potresti decidere di monitorare periodicamente i log per verificare lo stato di esecuzione o visualizzare una percentuale di log riusciti. La specifica di una frequenza di campionamento può aiutarti a farlo senza scrivere un volume elevato di voci di log INFO in Logging, il che può comportare costi di Logging più elevati.

Per specificare una frequenza di campionamento, imposta info_log_sample_rate su un valore in virgola mobile valido maggiore di 0 e minore o uguale a 1. La frequenza di campionamento determina la probabilità che un log INFO venga scritto in Logging. Il valore predefinito è 1 (vengono scritti tutti i log INFO).

Attenzione: se il livello di registrazione non è impostato su LOG_ALL, il info_log_sample_rate campo deve rimanere non specificato.

Configurazioni a livello di servizio

Puoi impostare configurazioni di logging per servizi specifici. In questo modo viene sovrascritta l'impostazione di logging globale per il servizio in questione. Ad esempio, potresti avere impostato il livello di logging globale su LOG_WARNINGS_AND_ABOVE, ma impostare il livello di logging del servizio UserEventService su LOG_ALL per verificare se le integrazioni degli eventi utente sono state eseguite correttamente.

Utilizza l'oggetto ServiceLoggingLevel per impostare livelli di logging granulari.

Il campo service_name accetta i seguenti valori:

• CompletionService
• ControlService
• MerchantCenterStreaming
• ModelService
• PredictionService
• ProductService
• ServingConfigService
• UserEventService

Tipi di errore

Questa sezione fornisce le definizioni dei tipi di errori che possono comparire nei log:

• MISSING_FIELD: non è stato impostato il valore di un campo obbligatorio. Ad esempio, manca il titolo di un articolo del catalogo.
• INVALID_TIMESTAMP: il timestamp non è valido, ad esempio è troppo lontano nel futuro o ha un formato errato.
• FIELD_VALUE_TOO_SMALL: il valore nel campo è inferiore al minimo richiesto. Ad esempio, un prezzo negativo.
• INCORRECT_JSON_FORMAT: il formato del valore JSON nella richiesta è errato, ad esempio manca una parentesi { .
• INVALID_LANGUAGE_CODE: il formato del codice lingua è errato.
• FIELD_VALUE_EXCEEDED: il valore nel campo è superiore al valore massimo consentito.
• INVALID_RESOURCE_ID: l'ID risorsa non è valido. Ad esempio, un valore catalog_id inesistente nel nome della risorsa.
• FIELD_SIZE_EXCEEDED: il numero di voci nel campo supera il limite massimo.
• UNEXPECTED_FIELD: un campo che dovrebbe essere vuoto contiene un valore. Ad esempio, una transazione per un evento di visualizzazione della pagina dei dettagli.
• INVALID_FORMAT: il formato del campo è errato, ad esempio una stringa con formato errato
• RESOURCE_ALREADY_EXISTS: hai tentato di creare una risorsa già esistente, ad esempio un articolo di catalogo già creato in precedenza.
• INVALID_API_KEY: la chiave API non corrisponde al progetto nella richiesta.
• INSUFFICIENT_PERMISSIONS: non disponi dell'autorizzazione per eseguire la richiesta. Questo errore è generalmente correlato all'assenza di un'autorizzazione IAM.
• UNJOINED_WITH_CATALOG: la richiesta include un ID articolo di catalogo che non esiste nel catalogo. Assicurati che il catalogo sia aggiornato.
• BATCH_ERROR: la richiesta contiene diversi errori. Ad esempio, un'importazione in linea con 10 articoli che non superano la convalida per motivi diversi.
• INACTIVE_RECOMMENDATION_MODEL: hai eseguito query su un modello non attivo per il servizio.
• ABUSIVE_ENTITY: l'ID visitatore o utente associato alla richiesta ha inviato un numero anomalo di eventi in un breve periodo di tempo.

• FILTER_TOO_STRICT: il filtro delle richieste di previsione ha bloccato tutti i risultati di previsione. Vengono restituiti gli articoli generici (non personalizzati) più apprezzati, a meno che la chiamata non specifichi strictFiltering come false, nel qual caso non viene restituito alcun articolo. Ecco alcuni motivi comuni per cui si verifica questo problema:

  • Stai specificando un tag filtro che non esiste nel tuo catalogo. L'aggiornamento di un tag filtro può richiedere fino a un giorno.
  • Il filtro è troppo limitato.

Visualizzare le metriche relative al carico dei dati

Per monitorare l'importazione dati del catalogo e degli eventi utente nella console Google Cloud, segui questi passaggi:

1. Visualizza le metriche degli errori per l'importazione dati del catalogo e degli eventi utente nella pagina Monitoraggio.

   Vai alla pagina Monitoraggio

2. Una volta che il sistema di caricamento dei dati è in esecuzione correttamente, utilizza le schede Catalogo ed Evento nella pagina Dati per visualizzare informazioni aggregate sul tuo catalogo, visualizzare l'anteprima dei prodotti caricati e visualizzare le visualizzazioni delle metriche di integrazione degli eventi utente.

   Vai alla pagina Dati

3. Per creare avvisi che ti comunichino se si verifica un problema con i caricamenti dei dati, segui le procedure descritte in Configurare gli avvisi di Cloud Monitoring.

Riepilogo dei dati del catalogo

Utilizza la scheda Catalogo nella pagina Dati per visualizzare statistiche di dati di alto livello per ogni ramo del catalogo. Questa pagina mostra quanti prodotti hai importato, quanti sono disponibili e quando hai importato per l'ultima volta i prodotti per ogni ramo del catalogo.

Puoi anche visualizzare un'anteprima degli elementi del catalogo che hai caricato e filtrare in base ai campi del prodotto.

Puoi importare i dati in diversi branch per eseguire il commit e visualizzare l'anteprima di consigli o risultati di ricerca. Ad esempio, per prepararti alle festività, puoi caricare nuovi dati del catalogo in un ramo diverso da quello predefinito e assicurarti che i risultati di Vertex AI Search per la vendita al dettaglio vengano generati correttamente prima di pubblicarli sul tuo sito web.

Statistiche sulla registrazione degli eventi utente

Nella scheda Evento puoi vedere per ogni tipo di evento utente quanti ne hai registrato, quanti di questi non sono stati associati a un prodotto (eventi non uniti) e in che modo i numeri sono diversi rispetto ai periodi precedenti. Puoi selezionare un periodo di tempo preimpostato o inserire un intervallo di tempo personalizzato.

Il grafico delle metriche mostra gli eventi utente importati nel tempo, che puoi filtrare per tipo di evento utente.

Nota: i periodi di tempo per le statistiche sono nel fuso orario del Pacifico. Ad esempio, le statistiche giornaliere rappresentano i dati da mezzanotte del giorno prima a mezzanotte del giorno in corso (fuso orario del Pacifico USA).

Metriche sulla qualità dei dati

Nella pagina Qualità dei dati, puoi visualizzare le metriche che mostrano le percentuali di prodotti ed eventi utente che soddisfano gli standard consigliati di qualità dei dati per la ricerca. Utilizza questa pagina per valutare i dati da importare o aggiornare per migliorare la qualità dei risultati di ricerca e accedere ai livelli di rendimento della ricerca.

Per ulteriori informazioni sui livelli di rendimento della ricerca e sulla verifica della qualità dei tuoi dati, consulta Ottenere i livelli di rendimento della ricerca.

Per un elenco di tutte le metriche sulla qualità dei dati del catalogo, consulta Metriche sulla qualità dei dati del catalogo.

Per tutti i requisiti e i consigli relativi agli eventi utente per consigli e ricerca, consulta Requisiti e best practice per gli eventi utente.

Eventi non uniti

Quando una richiesta API o un evento utente fa riferimento a un prodotto che non è stato caricato in Vertex AI Search for Retail, si tratta di un evento non unito. Gli eventi degli utenti non associati vengono comunque registrati e le richieste non associate vengono gestite, ma nessuno dei due può essere utilizzato per migliorare ulteriormente il modello per le previsioni future. Per questo motivo, devi assicurarti che la percentuale di eventi non registrati sia molto bassa sia per gli eventi dell'utente sia per le richieste di previsione.

Puoi visualizzare la percentuale di eventi utente non associati nella scheda Evento della pagina Dati.

Errori dell'API

Puoi visualizzare un grafico degli errori relativi all'API nel tempo, visualizzato in base al nome del metodo, facendo clic su Visualizza le metriche dell'API nella barra dei pulsanti della pagina Monitoraggio.

Monitora l'attività dei metodi API

Per visualizzare traffico, errori e latenza per metodo API, vai alla pagina Monitoraggio. Puoi selezionare un periodo di tempo preimpostato o inserire un intervallo di tempo personalizzato.

Per visualizzare ulteriori dettagli su ciascun grafico:

• Sotto un grafico, fai clic sul nome di un metodo per isolarlo nel grafico.
• Passa il cursore sopra un grafico per visualizzare un callout con ciascun metodo e i relativi valori in quel momento.
• Fai clic e trascina una sezione del grafico per aumentare lo zoom del periodo di tempo corrispondente.

Passaggi successivi

• Scopri come impostare avvisi di errore per i feed di dati.
• Scopri di più su Error Reporting.
• Scopri di più sulla visualizzazione dei log in Logging.