Creare un controllo dei link interrotti

Questo documento descrive come configurare un test periodico dei link contenuti in un URI creando un monitor sintetico. Specifichi le opzioni per il test, ad esempio l'URI di origine, il numero di link testati e il numero di tentativi di nuovo invio, quindi esegui il deployment di una funzione Cloud Run preconfigurata. Per supportare le attività di risoluzione dei problemi e di debug, i monitor sintetici salvano informazioni dettagliate su ogni test, inclusi gli screenshot. Gli screenshot ti consentono di visualizzare la risposta esatta visualizzata dai clienti della tua applicazione.

Per scoprire di più sui monitoraggi sintetici, consulta Informazioni sui monitoraggi sintetici.

Informazioni sui controlli dei link non funzionanti

Ogni strumento di controllo dei link interrotti testa i link in serie e esiste un timeout sintetico complessivo, che è configurabile.

Per impostazione predefinita, un controllore dei link interrotti esegue le seguenti operazioni:

  • Cerca nell'URI di origine gli elementi di ancoraggio HTML con attributi href.
  • Testa i primi 10 link trovati nell'URI di origine.
  • Per ogni link, lo strumento di controllo invia una richiesta e attende al massimo 30 secondi per una risposta. Quando viene ricevuta una risposta, lo strumento di controllo verifica che lo stato della risposta HTTP sia 200, il che indica che la risposta è andata a buon fine. Il controllo non esegue tentativi di nuovo.

Specifica l'URI di origine. Puoi configurare gli elementi HTML che il controllore dei link interrotti cerca, il numero massimo di elementi testati, il timeout per test e se vengono eseguiti i tentativi di nuovo. Puoi anche configurare i controlli dei link interrotti in modo che aspettino l'apparizione di un selettore.

I controlli dei link interrotti utilizzano il modello broken-links-ok. La configurazione di un controllore dei link interrotti è specificata dall'oggetto options del file index.js. Se crei il tuo checker utilizzando la console Google Cloud, ti verrà chiesto di specificare ogni opzione di configurazione e la funzione Cloud Run verrà aggiornata automaticamente. Tuttavia, se utilizzi l'API Cloud Monitoring o Terraform, devi compilare questo oggetto.

Dopo aver creato un controllore dei link interrotti, per modificare la configurazione, aggiorna l'oggetto options e esegui nuovamente il deployment della funzione Cloud Run.

Prima di iniziare

  1. Per ottenere le autorizzazioni necessarie per visualizzare e modificare i monitor sintetici utilizzando la console Google Cloud, chiedi all'amministratore di concederti i seguenti ruoli IAM nel tuo progetto:

    Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

  2. Enable the Cloud Monitoring API, Artifact Registry API, Cloud Build API, Cloud Functions API, Cloud Logging API, Pub/Sub API, and Cloud Run Admin API APIs.

    Enable the APIs

  3. Verifica che il tuo progetto Google Cloud contenga l'account di servizio Compute Engine predefinito. Questo account di servizio viene creato quando attivi l'API Compute Engine e ha un nome simile a 12345-compute@developer.gserviceaccount.com.

    Nella console Google Cloud, vai alla pagina Account di servizio:

    Vai ad Account di servizio.

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo IAM e amministrazione.

    Se l'account di servizio Compute Engine predefinito non esiste, fai clic su Crea account di servizio e completa la finestra di dialogo.

  4. Assicurati che all'account di servizio Compute Engine predefinito o all'account di servizio che hai creato sia stato assegnato il ruolo Editor (roles/editor).

    Per visualizzare i ruoli concessi al tuo account di servizio:

    1. Nella console Google Cloud, vai alla pagina IAM:

      Vai a IAM

      Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo IAM e amministrazione.

    2. Seleziona Includi concessioni di ruoli fornite da Google.
    3. Se l'account di servizio utilizzato dal monitor sintetico non è elencato o se non gli è stato concesso un ruolo che includa le autorizzazioni nel ruolo di Agente Cloud Trace (roles/cloudtrace.agent), concedi questo ruolo al tuo account di servizio.
  5. Configura i canali di notifica che vuoi utilizzare per ricevere le notifiche. Ti consigliamo di creare più tipi di canali di notifica. Per saperne di più, consulta Creare e gestire i canali di notifica e Creare e gestire i canali di notifica tramite API.

Creare un controllo dei link interrotti

Console

Quando crei un monitor sintetico utilizzando la console Google Cloud, viene eseguita il deployment di una nuova funzione Cloud Run (2ª generazione.) e viene creato il monitor per la funzione Cloud Run. Non puoi creare un monitoraggio sintetico che monitori una funzione Cloud Run esistente.

  1. Assicurati di aver attivato le API richieste, che il progetto contenga un account di servizio Compute Engine predefinito e che a questo account sia stato assegnato il ruolo Editor (roles/editor). Per ulteriori informazioni, consulta Prima di iniziare.

  2. Nella console Google Cloud, vai alla pagina  Monitoraggio sintetico:

    Vai a Monitoraggio sintetico

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

  3. Seleziona Crea monitoraggio sintetico.
  4. Per il modello, seleziona Strumento di controllo dei link inaccessibili.
  5. Inserisci un nome per il monitor sintetico.

  6. (Facoltativo) Aggiorna Timeout risposta, Frequenza controllo e aggiungi etichette definite dall'utente.

  7. Configura l'URI e gli elementi da testare:

    1. Fai clic su URI origine e inserisci un URI da testare. Il valore inserito deve essere un endpoint HTTP o HTTPS. Ad esempio, potresti inserire https://mywebsite.example.com.

    2. (Facoltativo) In Numero di link da seguire, aggiorna il numero massimo di link testati. Il valore predefinito di questo campo è 10.

    3. (Facoltativo) Nel campo Selettore elemento HTML, inserisci l'elemento HTML corrispondente come elenco separato da virgole. Il valore inserito viene convertito in una stringa e poi passato al metodo Document: querySelectorAll().

      Per impostazione predefinita, questo campo è impostato su a, che corrisponde alle ancore. Puoi inserire valori come a, img se vuoi trovare corrispondenze sia per gli ancoraggi sia per le immagini.

    4. (Facoltativo) Nel campo Attributi HTML da seguire, inserisci gli attributi HTML di cui vuoi che venga trovata una corrispondenza. I valori separati da virgole che inserisci vengono passati singolarmente al metodo getAttribute().

      Per impostazione predefinita, questo campo è impostato su href, che specifica l'URI per il link. Puoi inserire più attributi, ad esempio href, src. In questo esempio, il codice cerca l'attributo href e poi l'attributo src.

    5. (Facoltativo) Configura il selettore di attesa, il timeout per URI, i tentativi di nuovo invio e i codici di stato previsti:

      1. Fai clic su Mostra altre opzioni.

      2. Per configurare il controllo dei link interrotti in modo che attenda che un selettore specifico venga visualizzato nell'URI prima che i link vengano estratti, inserisci i selettori CSS nel campo Attendi selettore elemento. Il valore inserito viene convertito in una stringa e poi passato al metodo page.waitForSelector().

        Se il selettore non viene visualizzato prima della scadenza del timeout, l'errore viene registrato nei log.

      3. Aggiorna l'ordine in cui i link vengono selezionati per il test.

      4. Configura i nuovi tentativi.

        Per impostazione predefinita, viene inviata una richiesta a ogni collegamento e se la richiesta iniziale non va a buon fine per qualsiasi motivo, ad esempio il comando scade o il codice di stato HTTP non è 200, il collegamento viene contrassegnato come non riuscito.

        Questo campo specifica il numero di volte che lo strumento di controllo dei link interrotti può inviare una richiesta HTTP a un link prima di contrassegnarlo come non riuscito.

      5. Configura un timeout da applicare a ogni URI. Per impostazione predefinita, questo valore è impostato su 30 secondi.

      6. Per specificare il codice di stato e il timeout previsti per un URI specifico, fai clic su Aggiungi opzione per link e completa la finestra di dialogo.

  8. (Facoltativo) Configura se gli screenshot delle risposte devono essere raccolti e salvati. Se utilizzi le impostazioni predefinite, gli screenshot non vengono salvati. Se attivi la raccolta di screenshot, puoi raccogliere screenshot per tutti i test o solo per quelli non superati. Cloud Monitoring utilizza la seguente convenzione per assegnare un nome al bucket Cloud Storage:

    gcm-PROJECT_ID-synthetics-LOCATION

    Nell'espressione precedente:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • LOCATION: la posizione del bucket Cloud Storage.

    Puoi scegliere di utilizzare un bucket Cloud Storage esistente.

  9. Rivedi la configurazione e assicurati che sia corretta e completa, quindi crea la funzione Cloud Run:

    1. Fai clic su Crea funzione.

      I valori nei campi Configurazione URI vengono copiati nell'oggetto Options nel file index.js quando fai clic su Crea funzione. Dopo aver fatto clic su Crea funzione, per modificare la configurazione, modifica l'oggetto Options.

    2. Inserisci un nome visualizzato e seleziona una regione. I nomi devono essere univoci all'interno di una regione.

    3. Nella sezione Impostazioni di runtime, build, connessioni e sicurezza, segui questi passaggi:

      • Nella scheda Connessioni, assicurati che sia selezionata l'opzione Consenti tutto il traffico.

      • Esamina le impostazioni predefinite e aggiornale se necessario.

      • Nel campo Service account di runtime, seleziona un account di servizio.

    4. Fai clic su Applica funzione.

  10. Configura il criterio di avviso:

    1. (Facoltativo) Aggiorna il nome del criterio di avviso e la durata dell'errore prima dell'invio delle notifiche.

    2. Aggiungi i canali di notifica.

  11. Fai clic su Crea.

    La funzione Cloud Run che hai definito viene creata ed eseguita come 2ª generazione. e viene creato il monitor sintetico.

API

La procedura per creare un controllore dei link interrotti utilizzando l'API Cloud Monitoring è identica alla procedura per creare qualsiasi altro monitor sintetico. Per informazioni sull'utilizzo dell'API Cloud Monitoring per creare un monitor sintetico, consulta Creare un monitor sintetico e seleziona la scheda Cloud Monitoring.

I controlli dei link interrotti utilizzano il modello broken-links-ok. La configurazione di un controllore dei link interrotti è specificata dall'oggetto options del file index.js.

Quando la struttura options.screenshot_options è definita, il controllore dei link interrotti raccoglie gli screenshot e li salva in un bucket Cloud Storage. Se il campo screenshot_options.storage_location non è definito o se il valore è una stringa vuota, Monitoraggio crea un bucket Cloud Storage in cui vengono salvati gli screenshot. Monitoring utilizza la seguente convenzione per assegnare un nome al bucket Cloud Storage:

gcm-PROJECT_ID-synthetics-LOCATION

Nell'espressione precedente:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud.
  • LOCATION: la posizione del bucket Cloud Storage.

Terraform

Per scoprire come applicare o rimuovere una configurazione Terraform, consulta Comandi Terraform di base. Per ulteriori informazioni, consulta la Terraform documentazione di riferimento del provider.

La procedura per creare un controllore dei link interrotti utilizzando Terraform è identica alla procedura per creare qualsiasi altro monitor sintetico. Per informazioni sull'utilizzo di Terraform per creare un monitoraggio sintetico, consulta Creare un monitoraggio sintetico e seleziona la scheda Terraform.

I controlli dei link interrotti utilizzano il modello broken-links-ok. La configurazione di un controllore dei link interrotti è specificata dall'oggetto options del file index.js.

Quando la struttura options.screenshot_options è definita, il controllore dei link interrotti raccoglie gli screenshot e li salva in un bucket Cloud Storage. Se il campo screenshot_options.storage_location non è definito o se il valore è una stringa vuota, Monitoraggio crea un bucket Cloud Storage in cui vengono salvati gli screenshot. Monitoring utilizza la seguente convenzione per assegnare un nome al bucket Cloud Storage:

gcm-PROJECT_ID-synthetics-LOCATION

Nell'espressione precedente:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud.
  • LOCATION: la posizione del bucket Cloud Storage.

Esplorare i risultati

Per ogni esecuzione, un controllore dei link interrotti esegue le seguenti operazioni:

  • Genera una tabella in cui ogni riga fornisce informazioni sul test di un URI specifico. Le informazioni di riepilogo includono l'URI target, la latenza, lo stato e l'identificatore dell'elemento HTML. Ad esempio, questa colonna elenca a quando viene testato un elemento di ancoraggio HTML. Quando la riga corrisponde all'URI di origine, il valore dell'identificatore dell'elemento HTML è -.

  • Raccoglie metriche, dati traccia e dati log.

  • Raccoglie gli screenshot, se configurato.

Per ulteriori informazioni su come esplorare i dati raccolti, consulta Esplorare i risultati del monitoraggio sintetico.

Risoluzione dei problemi

Questa sezione fornisce informazioni che puoi utilizzare per risolvere i problemi relativi ai controlli dei link interrotti.

Impossibile modificare la configurazione di un controllore dei link interrotti

Hai creato un controllore dei link interrotti utilizzando la console Google Cloud e vuoi cambiare gli elementi HTML sottoposti a test o modificare il timeout dell'URI, i tentativi di nuovo invio, l'attesa del selettore e le opzioni per link. Tuttavia, quando modifichi lo strumento di controllo dei link interrotti, la console Google Cloud non visualizza i campi di configurazione.

Per risolvere questo errore:

  1. Nella console Google Cloud, vai alla pagina  Monitoraggio sintetico:

    Vai a Monitoraggio sintetico

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Monitoring.

  2. Individua il monitoraggio sintetico da modificare, fai clic su Altre opzioni e poi seleziona Modifica.
  3. Fai clic su Modifica funzione.

  4. Modifica l'oggetto options nel file index.js e poi fai clic su Applica funzione.

    Per informazioni sui campi e sulla sintassi di questo oggetto, consulta broken-links-ok/index.js.

  5. Fai clic su Salva.

La console Google Cloud indica che i salvataggi degli screenshot non vanno a buon fine

Hai creato un controllo dei link interrotti e lo hai configurato per salvare gli screenshot. Tuttavia, la console Google Cloud mostra uno dei seguenti messaggi di avviso insieme a informazioni più dettagliate:

  • InvalidStorageLocation
  • StorageValidationError
  • BucketCreationError
  • ScreenshotFileUploadError

Per risolvere questi errori, prova quanto segue:

  • Se viene visualizzato il messaggio InvalidStorageLocation, verifica l'esistenza del bucket Cloud Storage specificato nel campo options.screenshot_options.storage_location.

  • Visualizza i log relativi alla funzione Cloud Run. Per ulteriori informazioni, consulta la sezione Trovare i log.

  • Verifica che l'account di servizio utilizzato nella funzione Cloud Run corrispondente abbia un ruolo Identity and Access Management che gli consenta di creare, accedere e scrivere nei bucket Cloud Storage.

Passaggi successivi