Monitora e risolvi i problemi

Questa pagina descrive come ottenere informazioni sugli errori che si sono verificati nelle importazioni di cataloghi ed eventi utente e in altre operazioni API in AI Commerce Search.

Per assistenza nella configurazione degli avvisi, consulta Configurare gli avvisi di Cloud Monitoring.

Introduzione

Fornire informazioni accurate sul catalogo e sugli eventi utente all'API è importante per ottenere risultati di massima qualità. Il monitoraggio e la comprensione della fonte degli errori ti aiutano a trovare e correggere eventuali errori nel tuo sito.

Visualizzare gli 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 AI Commerce Search. Puoi visualizzare gli errori relativi al catalogo dei prodotti, agli eventi utente, alle previsioni dei suggerimenti, ai risultati di ricerca e ai modelli. Il sistema registra anche gli errori delle importazioni, ad esempio una riga con formato errato nel file di 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 log relativi a quell'errore 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 degli errori. Queste informazioni possono aiutarti a determinare la posizione della chiamata al metodo errato nel tuo sito.

Per gli errori JSON non validi, puoi ottenere maggiori 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 AI Commerce Search su Gemini Enterprise for Customer Experience.
   
   Vai alla pagina Dati

2. Fai clic su Stato attività.

   La finestra Stato 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 relativi a operazioni di integrazione specifiche.

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

Visualizzare i log in Cloud Logging

Per aprire i file di log direttamente in Cloud Logging, segui questa procedura. Devi disporre del ruolo Visualizzatore log (roles/logging.viewer) per visualizzare i log.

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

2. Seleziona il progetto AI Commerce Search dal selettore di progetti.

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

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

Ad esempio, questo link apre i log di tutti gli errori di AI Commerce Search nell'ultima ora:

Apri i log di AI Commerce Search

Per configurare i log API da scrivere, consulta Configurare il logging.

Configurare il logging

Puoi configurare i log dei servizi da scrivere in Logging. La configurazione del logging consente di impostare i livelli di gravità in 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 log. Una voce contiene informazioni come il metodo API, quando è stato richiamato, il codice di risposta e i corpi di richiesta e risposta. La configurazione del logging di un progetto specifica i tipi di log generati dall'API che vengono 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 AI Commerce Search.

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

Console

Per aggiornare le configurazioni di logging nella console, segui questi passaggi:

1. Vai alla pagina Monitoring nella console AI Commerce Search su Gemini Enterprise for Customer Experience.
   
   Vai alla pagina Monitoring

2. Fai clic su Configurazione del 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 seleziona il relativo livello di logging. Questa impostazione esegue l'override della configurazione di logging globale.

curl

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 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 tuo progetto.

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

   Questo esempio utilizza loggingConfig.Patch per impostare la configurazione di logging globale su LOG_WARNINGS_AND_ABOVE. Imposta anche 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 di alcuni livelli di gravità. Le impostazioni del livello di logging determinano i log generati da un metodo API che vengono scritti in Logging.

Se 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 del livello di logging predefinita è 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 INFO.

Frequenza di campionamento per i log riusciti

Se imposti il livello di logging su LOG_ALL, ma non vuoi registrare tutti i log riusciti, puoi specificare una frequenza di campionamento. Ad esempio, potresti decidere di monitorare periodicamente i log per la conferma dello stato riuscito o di 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 float 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 logging non è impostato su LOG_ALL, il info_log_sample_rate campo deve rimanere non specificato.

Configurazioni a livello di servizio

Puoi impostare le configurazioni di logging per servizi specifici. Questa impostazione esegue l'override dell'impostazione di logging globale per il servizio. Ad esempio, potresti impostare il livello di logging globale su LOG_WARNINGS_AND_ABOVE, ma impostare il livello di logging del servizio UserEventService su LOG_ALL in modo da poter verificare l'integrazione degli eventi utente riuscita.

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 il valore di un campo obbligatorio. Ad esempio, a catalog item 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 è più basso del 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 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 di 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 l'ID utente associato alla richiesta ha inviato un numero anomalo di eventi in un breve periodo di tempo.

• FILTER_TOO_STRICT: il filtro della richiesta di previsione ha bloccato tutti i risultati di previsione. Vengono restituiti gli articoli popolari generici (non personalizzati), a meno che la chiamata non abbia specificato strictFiltering come false, nel qual caso non vengono restituiti articoli. 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 di filtro può richiedere fino a un giorno per avere effetto.
  • Il filtro è troppo ristretto.

Visualizzare le metriche di caricamento dei dati

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

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

   Vai alla pagina Monitoring

2. Una volta che il sistema di caricamento dei dati è in esecuzione, utilizza le schede Catalogo ed Evento nella pagina Dati per visualizzare le informazioni aggregate sul 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 informino 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 le statistiche dei dati di alto livello per ogni ramo del catalogo. Questa pagina mostra quanti prodotti hai importato, quanti sono disponibili e quando hai importato l'ultima volta i prodotti per ogni ramo del catalogo dei prodotti.

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

Puoi importare i dati in rami diversi per preparare e visualizzare in anteprima i suggerimenti o i 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 AI Commerce Search vengano generati correttamente prima di pubblicarli sul tuo sito web.

Statistiche di registrazione degli eventi utente

Per ogni tipo di evento utente, nella scheda Evento puoi vedere quanti ne hai registrati, quanti non sono stati associati a un prodotto (eventi non combinati) e come i numeri sono cambiati 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 in base al 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 ieri a mezzanotte del fuso orario del Pacifico a oggi a mezzanotte del fuso orario del Pacifico.

Metriche di 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 di qualità dei dati consigliati 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 rendimento della ricerca.

Per ulteriori informazioni sui livelli di rendimento della ricerca e sul controllo della qualità dei dati, consulta Sbloccare i livelli di rendimento della ricerca.

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

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

Eventi non combinati

Quando un evento utente o una richiesta API fa riferimento a un prodotto che non è stato caricato in AI Commerce Search, si tratta di un evento non combinato. Gli eventi utente non combinati vengono comunque registrati e le richieste non combinate vengono gestite, ma nessuna delle due può essere utilizzata 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 utente sia per le richieste di previsione.

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

Errori API

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

Monitorare l'attività del metodo API

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

Per visualizzare maggiori dettagli su ogni grafico:

• Sotto un grafico, fai clic sul nome di un metodo per isolarlo nel grafico.
• Passa il mouse sopra un grafico per visualizzare una didascalia con ogni metodo e i relativi valori in quel momento.
• Fai clic e trascina il cursore su una sezione qualsiasi del grafico per ingrandire quel periodo di tempo.

Passaggi successivi

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