Configurare avvisi e notifiche

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. info

Le condizioni di avviso definiscono codici di stato specifici (ad esempio 404/502/2xx/4xx/5xx), la latenza e le soglie dei codici di errore che, se superate, attivano avvisi visivi nell'interfaccia utente e inviano notifiche tramite una serie di canali, come email, Slack, PagerDuty o webhook. Puoi configurare gli avvisi a livello di ambiente, proxy API, servizio target o regione. Quando viene attivato un avviso, riceverai una notifica utilizzando il metodo che hai definito quando hai aggiunto avvisi e notifiche.

Ad esempio, potresti attivare un avviso e inviare una notifica al team operativo quando il tasso di errori 5xx supera il 23% per un periodo di 5 minuti per il proxy dell'API orders-prod di cui è stato eseguito il deployment nell'ambiente di produzione.

La figura seguente mostra come vengono visualizzati gli avvisi nell'interfaccia utente:

Di seguito è riportato un esempio di notifica via email che potresti ricevere quando viene attivato un avviso.

Nel corpo della notifica di avviso, fai clic sui seguenti link per ulteriori informazioni:

• Visualizza dettagli per visualizzare ulteriori dettagli, tra cui le impostazioni di avviso e l'attività per ogni condizione nell'ultima ora.
• Definizione avviso per visualizzare la definizione dell'avviso.
• Cronologia avvisi per visualizzare ulteriori informazioni sul determinato avviso.
• Visualizza playbook per visualizzare le azioni consigliate, se fornite.
• Visualizza report API Analytics per visualizzare un report personalizzato per la condizione di avviso.

Le sezioni seguenti descrivono come configurare e gestire avvisi e notifiche.

Informazioni sui tipi di avvisi

La release iniziale di Monitoraggio API ti consente di creare regole basate su pattern che specificano quando generare un avviso in base a un insieme di condizioni predefinite. Questi tipi di avvisi sono chiamati fissi e sono stati l'unico tipo di avvisi supportato nella versione iniziale del monitoraggio API.

Ad esempio, puoi generare un avviso fisso quando:

• [Tasso di errori 5xx] [è superiore a] [10%] per [10 minuti] da [target mytarget1]
• [count of 2xx errors] [is less than] [50] for [5 minutes] in [region us-east-1]
• [Latenza p90] [è superiore a] [750 ms] per [10 minuti] su [proxy myproxy1]

La release beta di Security Reporting del 13/11/19 aggiunge nuovi tipi di avvisi:

• Avvisi sul traffico totale (beta). Un tipo di avviso che ti consente di inviare un avviso quando il traffico cambia in base a una percentuale specificata in un intervallo di tempo.
• Avvisi di anomalia (beta). Un tipo di avviso in cui Edge rileva problemi di traffico e prestazioni anziché doverli predeterminare autonomamente. A questo punto puoi generare un avviso per queste anomalie.
• Avvisi di scadenza TLS (beta). Un tipo di avviso che ti consente di inviare una notifica quando un certificato TLS sta per scadere.

Poiché il monitoraggio API ora supporta più tipi di avvisi, la finestra di dialogo Crea avviso ora mostra l'opzione per selezionare il tipo di avviso:

Visualizzare le impostazioni di avviso

Per visualizzare le impostazioni di avviso attualmente definite, fai clic su Analizza > Regole di avviso nell'interfaccia utente di Edge.

Viene visualizzata la pagina Avviso, come mostrato nella figura seguente:

Come evidenziato nella figura, la pagina Avviso ti consente di:

• Visualizzare un riepilogo delle impostazioni di avviso attualmente definite
• Visualizza la cronologia degli avvisi che sono stati attivati
• Aggiungere avvisi e notifiche
• Creare un report personalizzato da un avviso
• Attivare o disattivare un avviso
• Modificare un avviso
• Eliminare un avviso
• Cercare una determinata stringa nell'elenco di avvisi

Visualizzare la cronologia degli avvisi attivati per la tua organizzazione

Per visualizzare la cronologia degli avvisi attivati per la tua organizzazione nelle ultime 24 ore, fai clic su Analizza > Regole di avviso nell'interfaccia utente di Edge e poi sulla scheda Cronologia.

Viene visualizzata la pagina Cronologia avvisi.

Fai clic sul nome dell'avviso per visualizzarne i dettagli nella dashboard di indagine. Puoi filtrare l'elenco cercando tutto o parte del nome dell'avviso.

Aggiungere avvisi e notifiche

Per aggiungere avvisi e notifiche:

1. Fai clic su Analizza > Regole di avviso nell'interfaccia utente di Edge.
2. Fai clic su +Avviso.
3. Inserisci le seguenti informazioni generali sull'avviso:

   Campo	Descrizione
   Nome avviso	Nome dell'avviso. Utilizza un nome che descriva l'attivatore e che sia significativo per te. Il nome non può superare i 128 caratteri.
   Tipo di avviso:	Seleziona Fisso. Per saperne di più sui tipi di avvisi, consulta Informazioni sui tipi di avvisi.
   Descrizione	Descrizione dell'avviso.
   Ambiente	Seleziona l'ambiente dall'elenco a discesa.
   Stato	Attiva/disattiva l'avviso.

4. Definisci la metrica, la soglia e la dimensione per la prima condizione che attiverà l'avviso.

   Campo condizione	Descrizione
   Metrica	Seleziona una delle seguenti metriche: Codice di stato: seleziona un codice di stato dall'elenco, ad esempio 401, 404, 2xx, 4xx o 5xx HTTP. Nota: L'API ti consente di impostare una gamma più ampia di codici di stato. Utilizza l'API per specificare qualsiasi codice di stato compreso tra 200 e 299, 400 e 599 e i valori jolly 2xx, 4xx o 5xx. Consulta Creare un avviso. Per gli avvisi di limitazione della frequenza (codice di stato HTTP 429), imposta la metrica su un codice di errore di arresto picco. Puoi utilizzare il criterio Assegna messaggio per riscrivere il codice di risposta HTTP da un errore del proxy o da un errore del target. Il monitoraggio delle API ignora i codici riscritti e registra i codici di risposta HTTP effettivi. Latenza: seleziona un valore di latenza dall'elenco a discesa. Nello specifico: p50 (50° percentile), p90 (90° percentile), p95 (95° percentile) o p99 (99° percentile). Ad esempio, seleziona p95 per configurare un avviso che si attiva quando la latenza di risposta per il 95° percentile è maggiore della soglia impostata di seguito. Codice guasto: seleziona una categoria, una sottocategoria e un codice guasto dall'elenco. In alternativa, seleziona una delle seguenti opzioni all'interno di una categoria o sottocategoria: Tutti: il totale combinato di tutti i codici di errore in questa categoria/sottocategoria deve soddisfare i criteri delle metriche. Qualsiasi: il codice di errore singolo in questa categoria/sottocategoria deve soddisfare i criteri delle metriche. Per ulteriori informazioni, consulta la Guida ai codici di guasto. Traffico totale (beta): seleziona l'aumento o la diminuzione del traffico. Per saperne di più, consulta la sezione Avvisi sul traffico (beta).
   Soglia	Configura la soglia per la metrica selezionata: Codice stato: imposta la soglia come percentuale, conteggio o transazioni al secondo (TPS) nel tempo. Latenza: seleziona la soglia come durata della latenza totale o target (ms) nel tempo. In questo caso, viene attivato un avviso se la latenza percentile osservata specificata, aggiornata ogni minuto se è presente traffico, supera la condizione di soglia per l'intervallo di tempo che copre la durata specificata. In altre parole, la condizione di soglia non viene aggregata per l'intera durata del tempo. Codice errore: imposta la soglia come percentuale, conteggio o transazioni al secondo (TPS) nel tempo.
   Dimensione	Fai clic su + Aggiungi dimensione e specifica i dettagli della dimensione per cui restituire i risultati, inclusi il proxy API, il servizio target o l'app per sviluppatori e la regione. Se imposti una dimensione specifica su: Tutte: tutte le entità nella dimensione devono soddisfare i criteri della metrica. Non puoi selezionare Tutte per una metrica di tipo Latenza. Qualsiasi: applicabile solo alla regione. Un'entità nella dimensione deve soddisfare i criteri delle metriche per una singola regione. Nota: per i proxy API o i servizi target, seleziona una raccolta per supportare la funzionalità Qualsiasi. Raccolte: seleziona una raccolta dall'elenco per specificare l'insieme di proxy API o servizi target. In questo caso, qualsiasi entità nella raccolta deve soddisfare i criteri. Se imposti la dimensione su Target, puoi selezionare un servizio target o il servizio specificato da un criterio ServiceCallout. La destinazione di un criterio ServiceCallout viene visualizzata come valore preceduto da "sc://". Ad esempio, "sc://my.endpoint.net".

5. Fai clic su Mostra dati condizione per visualizzare i dati recenti relativi alla condizione nell'ultima ora.
   Il tasso di errore nel grafico viene visualizzato in rosso quando supera la soglia della condizione di avviso.
   

   Fai clic su Nascondi dati condizione per nascondere i dati.

6. Fai clic su + Aggiungi condizione per aggiungere altre condizioni e ripeti i passaggi 4 e 5.

   Nota: se specifichi più condizioni, l'avviso verrà attivato quando tutte le condizioni sono soddisfatte.

7. Fai clic su Crea un report di analisi API in base alle condizioni di avviso se vuoi creare un report personalizzato in base alle condizioni di avviso che hai configurato. Questa opzione non è selezionabile se non sei un amministratore dell'organizzazione.

   Per saperne di più, consulta Creare un report personalizzato da un avviso.

   Nota: puoi modificare il report personalizzato dopo aver salvato l'avviso, come descritto in Gestire i report personalizzati.

8. Fai clic su + Notifica per aggiungere una notifica di avviso.

   Dettagli notifica	Descrizione
   Canale	Seleziona il canale di notifica che vuoi utilizzare e specifica la destinazione: email, Slack, PagerDuty o webhook.
   Destinazione	Specifica la destinazione in base al tipo di canale selezionato: Email: indirizzo email, ad esempio joe@company.com Slack: URL del canale Slack, ad esempio https://hooks.slack.com/services/T00000000/B00000000/XXXXX PagerDuty: codice PagerDuty, ad esempio abcd1234efgh56789 Webhook: URL webhook, ad esempio https://apigee.com/test-webhook. Consulta la sezione Formato dell'oggetto webhook per una descrizione dell'oggetto inviato all'URL. Passa eventuali informazioni sulle credenziali nell'URL del webhook. Ad esempio: https://apigee.com/test-webhook?auth_token=1234_abcd. Puoi specificare l'URL di un endpoint che può analizzare l'oggetto webhook per modificarlo o elaborarlo. Ad esempio, puoi specificare l'URL di un'API, ad esempio un'API Edge, o di qualsiasi altro endpoint in grado di elaborare l'oggetto. Nota: puoi specificare una sola destinazione per notifica. Per specificare più destinazioni per lo stesso tipo di canale, aggiungi altre notifiche.

9. Per aggiungere altre notifiche, ripeti il passaggio 8.
10. Se hai aggiunto una notifica, imposta i seguenti campi:

    Campo	Descrizione
    Playbook	(Facoltativo) Campo di testo in formato libero per fornire una breve descrizione delle azioni consigliate per risolvere gli avvisi quando vengono attivati. Puoi anche specificare un link alla tua pagina della community o della wiki interna in cui fai riferimento alle best practice. Le informazioni in questo campo verranno incluse nella notifica. I contenuti di questo campo non possono superare i 1500 caratteri.
    Limitazione	La frequenza con cui inviare le notifiche. Seleziona un valore dall'elenco a discesa. I valori validi sono: 15 minuti, 30 minuti e 1 ora.

11. Fai clic su Salva.

Formato dell'oggetto webhook

{
  "alertInstanceId": "event-id",
  "alertName": "name",
  "org": "org-name",
  "description": "alert-description",
  "alertId": "alert-id",
  "alertTime": "alert-timestamp",
  "thresholdViolations":{"Count0": "Duration=threshold-duration Region=region Status Code=2xx Proxy=proxy Violation=violation-description"
  },
  "thresholdViolationsFormatted": [
    {
      "metric": "count",
      "duration": "threshold-duration",
      "proxy": "proxy",
      "region": "region",
      "statusCode": "2xx",
      "violation": "violation-description"
    }
  ],
  "playbook": "playbook-link"
}

Le proprietà thresholdViolations e thresholdViolationsFormatted contengono i dettagli sull'avviso. La proprietà thresholdViolations contiene una singola stringa con i dettagli, mentre thresholdViolationsFormatted contiene un oggetto che descrive l'avviso. In genere viene utilizzata la proprietà thresholdViolationsFormatted perché è più semplice da decodificare.

L'esempio riportato sopra mostra i contenuti di queste proprietà per un avviso fisso quando configuri la metrica di avviso in modo che si attivi in base al codice di stato HTTP 2xx, come indicato dalla proprietà statusCode.

I contenuti di queste proprietà dipendono dal tipo di avviso, ad esempio fisso o anomalo, e dalla configurazione specifica dell'avviso. Ad esempio, se crei un avviso fisso in base a un codice di errore, la proprietà thresholdViolationsFormatted contiene una proprietà faultCode instead of a statusCode property.

La tabella seguente mostra tutte le possibili proprietà della proprietà thresholdViolationsFormatted per diversi tipi di avviso:

metric, proxy, target, developerApp,
region, statusCode, faultCodeCategory, faultCodeSubCategory,
faultCode, percentile, comparisonType, thresholdValue,
triggerValue, duration, violation

metric, proxy, target, developerApp,
region, comparisonType, thresholdValue, triggerValue,
duration, violation

metric, proxy, target, region,
statusCode, faultCode, percentile, sensitivity,
violation

envName, certificateName, thresholdValue, violation

Creare un report personalizzato da un avviso

Per creare un report personalizzato da un avviso:

1. Quando crei un avviso, fai clic su Crea un report di analisi API in base alle condizioni di avviso, come descritto in Aggiunta di avvisi e notifiche.

   Dopo aver salvato l'avviso, l'interfaccia utente mostra il seguente messaggio:

   Alert alertName saved successfully. To customize the report generated, click here.

   Fai clic sul messaggio per aprire il report in una nuova scheda con i campi pertinenti precompilati. Per impostazione predefinita, il report personalizzato si chiama: API Monitoring Generated alertName

2. Modifica il report personalizzato, se necessario, e fai clic su Salva.
3. Fai clic sul nome del report nell'elenco ed esegui il report personalizzato.

Per gestire il report personalizzato creato in base alle condizioni di avviso:

1. Fai clic su Analizza > Regole di avviso nell'interfaccia utente di Edge.
2. Fai clic sulla scheda Impostazioni.
3. Nella colonna Report, fai clic sul report personalizzato associato all'avviso che vuoi gestire.

   La pagina del report personalizzato viene visualizzata in una nuova scheda. Se la colonna Report è vuota, significa che non è stato ancora creato un report personalizzato. Se vuoi, puoi modificare l'avviso per aggiungere un report personalizzato.

4. Modifica il report personalizzato, se necessario, e fai clic su Salva.
5. Fai clic sul nome del report nell'elenco ed esegui il report personalizzato.

Attivare o disattivare un avviso

Per attivare o disattivare un avviso:

1. Fai clic su Analizza > Regole di avviso nell'interfaccia utente di Edge.
2. Fai clic sul pulsante di attivazione/disattivazione nella colonna Stato associata all'avviso che vuoi attivare o disattivare.
   

Modificare un avviso

Per modificare un avviso:

1. Fai clic su Analizza > Regole di avviso nell'interfaccia utente di Edge.
2. Fai clic sul nome dell'avviso da modificare.
3. Modifica l'avviso, se necessario.
4. Fai clic su Salva.

Eliminare un avviso

Per eliminare un avviso:

1. Fai clic su Analizza > Regole di avviso nell'interfaccia utente di Edge.
2. Posiziona il cursore sull'avviso da eliminare e fai clic su nel menu delle azioni.

Avvisi suggeriti

Apigee consiglia di configurare i seguenti avvisi per ricevere notifiche sui problemi comuni. Alcuni di questi avvisi sono specifici per l'implementazione delle API e sono utili solo in determinate situazioni. Ad esempio, diversi avvisi riportati di seguito sono applicabili solo se utilizzi il criterio ServiceCallout o il criterio JavaCallout.

Configurare un avviso relativo a un codice di stato 5xx per un proxy API

Di seguito è riportato un esempio di come configurare un avviso utilizzando l'interfaccia utente che viene attivato quando le transazioni al secondo (TPS) dei codici di stato 5xx per il proxy dell'API Hotels superano 100 per 10 minuti per qualsiasi regione. Per ulteriori informazioni, vedi Aggiungere avvisi e notifiche.

Per informazioni sull'utilizzo dell'API, consulta Configurare un avviso relativo a un codice di stato 5xx per un proxy utilizzando l'API.

Configurare un avviso di latenza P95 per un proxy API

Di seguito è riportato un esempio di come configurare un avviso utilizzando l'interfaccia utente che viene attivato quando la latenza di risposta totale per il 95° percentile è superiore a 100 ms per 5 minuti per il proxy dell'API hotels per qualsiasi regione. Per ulteriori informazioni, vedi Aggiungere avvisi e notifiche.

Per informazioni sull'utilizzo dell'API, consulta Configurare un avviso sulla latenza P95 per un proxy API utilizzando l'API

Configurare un avviso 404 (applicazione non trovata) per tutti i proxy API

Di seguito è riportato un esempio di come configurare un avviso utilizzando l'interfaccia utente che viene attivato quando la percentuale di codici di stato 404 per tutti i proxy API supera il 5% per 5 minuti per qualsiasi regione. Per ulteriori informazioni, vedi Aggiungere avvisi e notifiche.

Per informazioni sull'utilizzo dell'API, consulta Configurare un avviso 404 (applicazione non trovata) per tutti i proxy API che utilizzano l'API.

Configurare un avviso sul conteggio dei proxy API per le API

Di seguito è riportato un esempio di come configurare un avviso utilizzando l'interfaccia utente che viene attivato quando il conteggio dei codici 5xx per le API supera 200 per 5 minuti per qualsiasi regione. In questo esempio, le API vengono acquisite nella raccolta Proxy API critici. Per ulteriori informazioni, vedi:

• Aggiungere avvisi e notifiche
• Gestire le raccolte

Per informazioni sull'utilizzo dell'API, consulta Configurare un avviso sul conteggio dei proxy API per le API che utilizzano l'API.

Configurare un avviso sulla percentuale di errori per i servizi target

Di seguito è riportato un esempio di come configurare un avviso utilizzando l'interfaccia utente che viene attivato quando la frequenza di codice 500 per i servizi target supera il 10% per 1 ora per qualsiasi regione. In questo esempio, i servizi target vengono acquisiti nella raccolta Target critici. Per ulteriori informazioni, vedi:

• Aggiungere avvisi e notifiche
• Gestire le raccolte

Per informazioni sull'utilizzo dell'API, vedi Configurare un avviso sulla frequenza degli errori per i servizi di destinazione utilizzando l'API.

Configurare un avviso sul tasso di errore per il criterio ServiceCallout

Di seguito è riportato un esempio di come configurare un avviso utilizzando l'interfaccia utente che viene attivato quando la frequenza di codice 500 per il servizio specificato dal ServiceCallout policy supera il 10% per 1 ora per qualsiasi regione. Per ulteriori informazioni, vedi:

• Aggiungere avvisi e notifiche

Per informazioni sull'utilizzo dell'API, consulta Configurare un avviso relativo alla frequenza degli errori per i criteri di callout del servizio utilizzando l'API.

Configurare un avviso relativo al codice di errore del criterio

Di seguito è riportato un esempio di come configurare un avviso utilizzando l'interfaccia utente che si attiva quando il conteggio dei codici di errore JWT AlgorithmMismatch per il criterio VerifyJWT è superiore a 5 per 10 minuti per tutte le API. Per ulteriori informazioni, vedi:

• Aggiungere avvisi e notifiche
• Gestire le raccolte

Per informazioni sull'utilizzo dell'API, consulta Configurare un avviso relativo al codice di errore per il codice di errore del criterio utilizzando l'API.