Monitoraggio e risoluzione dei problemi

Questa pagina descrive come ottenere informazioni sugli errori che si sono verificati nelle importazioni degli eventi utente e del catalogo, nonché in altre operazioni dell'API in Vertex AI Search per la vendita al dettaglio.

Per informazioni sulla configurazione degli avvisi, consulta Configurare gli avvisi di Cloud Monitoring.

Introduzione

Fornire informazioni di catalogo ed eventi utente accurati all'API è importante per ottenere risultati di qualità ottimale. Il monitoraggio e la comprensione dell'origine degli errori consentono di trovare e correggere eventuali errori nel sito.

Visualizza errori di integrazione aggregati

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

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

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

Puoi aprire i singoli log degli errori espandendo il log. I log degli errori forniscono ulteriori dettagli sulla richiesta, tra cui i payload di richiesta e risposta e i dettagli degli errori. 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.

Vedere lo stato di una specifica operazione di integrazione

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

1. Vai alla pagina Dati> nella console di Search for Retail.
   
   Vai alla pagina Dati

2. Fai clic su Stato attività.

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

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

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

Visualizza i log in Cloud Logging

Per aprire i file di log direttamente in Cloud Logging, utilizza 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 per la vendita al dettaglio dal selettore di progetti.

3. Fai clic sul menu a discesa Risorsa e seleziona API utilizzata > Cloud Retail.

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

Ad esempio, questo link apre i log per tutti gli errori di vendita al dettaglio di Vertex AI Search nell'ultima ora:

Apri Vertex AI Search per i log di retail

Per configurare quali log API vengono scritti, consulta Configurare il logging.

Configura logging

Puoi configurare quali log di servizio vengono scritti in Logging. La configurazione di Logging consente di impostare i livelli di gravità a cui scrivere i log, attivare o disattivare il logging ed eseguire l'override delle impostazioni di logging predefinite per servizi specifici.

Ogni richiesta API effettuata da un utente finale può generare una voce di logging. Una voce contiene informazioni come il metodo API, quando è stata richiamata, il codice di risposta e i corpi della richiesta e della risposta. La configurazione del logging di un progetto specifica quali tipi di log generati dall'API devono essere scritti 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 di editor di Vertex AI Search per la vendita al dettaglio.

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

Console

Per aggiornare le configurazioni di logging nella console:

1. Vai alla pagina Monitoring nella console di Search for Retail.
   
   Vai alla pagina Monitoring

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 di successo.

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

arricciatura

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

1. Per visualizzare la configurazione del logging attuale, 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 del logging, utilizza il metodo loggingConfig.Patch. Per saperne di più, consulta la documentazione di riferimento dell'API LoggingConfig.

   Questo esempio utilizza loggingConfig.Patch per impostare la configurazione del logging globale su LOG_WARNINGS_AND_ABOVE. Inoltre, imposta due configurazioni a livello di servizio: CatalogService è impostato su LOG_WARNINGS_AND_ABOVE e ControlService è impostato 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

In Logging vengono scritti solo i log con alcuni livelli di gravità. Le impostazioni a livello di logging determinano quali log generati da un metodo API vengono scritti in Logging.

Se per un metodo API non è impostata alcuna configurazione di logging a livello di servizio, 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 riusciti come i log di INFO.

Frequenza di campionamento per i log riusciti

Se imposti l'impostazione del 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 la conferma dello stato di esito positivo o di visualizzare una percentuale di log riusciti. Specificare una frequenza di campionamento può aiutarti a farlo senza scrivere un volume elevato di voci di log INFO in Logging, con conseguente rischio di 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 (tutti i log INFO vengono scritti).

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

Configurazioni del livello di servizio

Puoi impostare configurazioni di logging per servizi specifici. L'impostazione di logging globale per quel servizio verrà sovrascritta. Ad esempio, potresti avere il livello di logging globale impostato su LOG_WARNINGS_AND_ABOVE, ma impostare il livello di logging del servizio UserEventService su LOG_ALL, in modo da poter verificare la corretta integrazione degli eventi utente.

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 errore che possono essere visualizzati nei log:

• MISSING_FIELD: non è stato impostato un valore di campo obbligatorio; ad esempio, un articolo di catalogo è privo del titolo.
• INVALID_TIMESTAMP: il timestamp non è valido, ad esempio è troppo lontano nel futuro o non è formattato correttamente.
• FIELD_VALUE_TOO_SMALL: il valore nel campo è inferiore al minimo richiesto; ad esempio, un prezzo negativo.
• INCORRECT_JSON_FORMAT: il formato JSON nella richiesta non è corretto, ad esempio una parentesi { mancante.
• INVALID_LANGUAGE_CODE: il formato del codice lingua non è corretto.
• FIELD_VALUE_EXCEEDED: il valore nel campo è superiore al limite massimo consentito.
• INVALID_RESOURCE_ID: l'ID risorsa non è valido, ad esempio un 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 non è corretto, ad esempio una stringa con formato non corretto
• RESOURCE_ALREADY_EXISTS: hai provato a creare una risorsa già esistente, ad esempio un elemento di catalogo creato in precedenza.
• INVALID_API_KEY: la chiave API non corrisponde al progetto nella richiesta.
• INSUFFICIENT_PERMISSIONS: non hai l'autorizzazione per eseguire la richiesta. Questo errore è in genere correlato alla mancanza di un'autorizzazione IAM richiesta.
• 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 più errori; ad esempio, un'importazione in linea con 10 elementi che non superano la convalida per diversi motivi.
• INACTIVE_RECOMMENDATION_MODEL: hai eseguito la query su un modello non attivo per la pubblicazione.
• ABUSIVE_ENTITY: l'ID visitatore o l'ID utente associati 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 della previsione. Vengono restituiti articoli popolari generici (non personalizzati), a meno che la chiamata non abbia specificato strictFiltering come falso, nel qual caso nessun elemento viene restituito. Ecco alcuni motivi comuni per cui si verifica questo problema:

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

Visualizzare le metriche di carico dei dati

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

1. Visualizza le metriche di errore per l'importazione dati sugli eventi utente e del catalogo nella pagina Monitoring.

   Vai alla pagina Monitoring

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

   Vai alla pagina Dati

3. Per creare avvisi utili in caso di problemi 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 alto livello sui dati per ogni ramo del catalogo. In questa pagina è visualizzato il numero di prodotti importati, il numero di prodotti disponibili e l'ultima volta che hai importato i prodotti per ogni ramo del catalogo dei prodotti.

Puoi anche visualizzare un'anteprima degli articoli del catalogo che hai caricato e applicare un filtro in base ai campi del prodotto.

Puoi importare i dati in rami diversi per organizzare e visualizzare l'anteprima di consigli o risultati di ricerca. Ad esempio, per prepararti per le festività, potresti caricare nuovi dati del catalogo in un ramo non predefinito e assicurarti che i risultati di Vertex AI Search per la vendita al dettaglio vengano generati correttamente prima di renderli disponibili sul tuo sito web.

Statistiche relative alla registrazione di eventi utente

Per ogni tipo di evento utente, nella scheda Eventi puoi vedere quanti di questi eventi hai registrato, quanti non sono stati associati a un prodotto (eventi non uniti) e in che modo i numeri differiscono dai 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 si basano sul fuso orario del Pacifico. Ad esempio, le statistiche giornaliere rappresentano i dati da ieri alla mezzanotte del fuso orario del Pacifico a oggi alla mezzanotte del fuso orario del Pacifico.

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 quali dati devi importare o aggiornare per migliorare la qualità dei risultati di ricerca e sbloccare i livelli di prestazioni della ricerca.

Per ulteriori informazioni sui livelli di prestazioni della ricerca e sul controllo della qualità dei dati, consulta Sbloccare i livelli di prestazioni 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 relativi agli eventi utente e i consigli relativi a consigli e ricerca, consulta Best practice e requisiti relativi agli eventi utente.

Eventi non uniti

Quando un evento utente o una richiesta API fa riferimento a un prodotto che non è stato caricato su Vertex AI Search per la vendita al dettaglio, si tratta di un evento non associato. Gli eventi utente non uniti vengono comunque registrati e le richieste non unite vengono gestite, ma nessuno dei due può essere utilizzato per migliorare ulteriormente il modello per previsioni future. Per questo motivo, devi assicurarti che la percentuale di eventi non registrati sia molto bassa sia per gli eventi utente sia per le richieste di previsione.

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

Errori relativi all'API

Puoi visualizzare un grafico degli errori dell'API nel corso del tempo, visualizzati per nome del metodo, facendo clic su Visualizza metriche API sulla barra dei pulsanti della pagina Monitoring.

Monitora l'attività dei metodi API

Per visualizzare il traffico, gli errori e la latenza per metodo API, vai alla pagina Monitoring. Puoi selezionare un periodo di tempo predefinito 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 su un grafico per visualizzare un callout con ogni metodo e i relativi valori in quel momento.
• Fai clic e trascina su una sezione del grafico per aumentare lo zoom sul periodo di tempo in questione.

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.