Crea criteri di avviso con una condizione basata su PromQL (API)

Questa pagina descrive come creare un criterio di avviso con una condizione basata su PromQL utilizzando l'API Cloud Monitoring. Puoi utilizzare le query PromQL nei criteri di avviso per creare condizioni complesse con funzionalità come rapporti, soglie dinamiche e valutazione delle metriche.

Per informazioni generali, consulta Criteri di avviso con PromQL.

Se lavori in un ambiente Prometheus esterno a Cloud Monitoring e utilizzi regole di avviso di Prometheus, puoi utilizzare Google Cloud CLI per eseguirne la migrazione ai criteri di avviso di Monitoring con una query PromQL. Per maggiori informazioni, consulta Eseguire la migrazione delle regole di avviso e dei ricevitori da Prometheus.

crea criteri di avviso con query PromQL

Puoi utilizzare il metodo alertPolicies.create per creare criteri di avviso a livello di programmazione.

L'unica differenza tra la creazione di criteri di avviso con condizioni basate su PromQL e altri criteri di avviso è che il tipo Condition deve essere PrometheusQueryLanguageCondition. Questo tipo di condizione consente di definire criteri di avviso con PromQL.

Di seguito viene mostrata una query PromQL per una condizione del criterio di avviso che utilizza una metrica dell'esportatore kube-state per trovare il numero di volte in cui un container è stato riavviato negli ultimi 30 minuti:

rate(kube_pod_container_status_restarts[30m]) * 1800 > 1

Creazione del criterio di avviso

Per creare un criterio di avviso con una condizione basata su PromQL, utilizza il AlertPolicytipo di condizione PrometheusQueryLanguageCondition. PrometheusQueryLanguageCondition ha la seguente struttura:

{
  "query": string,
  "duration": string,
  "evaluationInterval": string,
  "labels": {string: string},
  "ruleGroup": string,
  "alertRule": string
}

I campi PrometheusQueryLanguageCondition hanno le seguenti definizioni:

  • query: l'espressione PromQL da valutare. Equivale al campo expr di una regola di avviso di Prometheus standard.
  • duration: specifica il periodo di tempo durante il quale ogni valutazione della query deve generare un valore true prima che venga attivato il criterio di avviso. Il valore deve essere un numero di minuti, espresso in secondi; ad esempio, 600s per una durata di 10 minuti. Per maggiori informazioni, consulta Comportamento dei criteri di avviso basati su metriche.
  • evaluationInterval: l'intervallo di tempo, in secondi, tra le valutazioni PromQL della query. Il valore predefinito è 30 secondi. Se PrometheusQueryLanguageCondition è stato creato eseguendo la migrazione di una regola di avviso di Prometheus, questo valore proviene dal gruppo di regole di Prometheus che conteneva la regola di avviso di Prometheus.
  • labels: un modo facoltativo per aggiungere o sovrascrivere le etichette nel risultato dell'espressione PromQL.
  • ruleGroup: se il criterio di avviso è stato migrato da un file di configurazione di Prometheus, questo campo contiene il valore del campo name del gruppo di regole nel file di configurazione di Prometheus. Questo campo non è obbligatorio quando crei un criterio di avviso PromQL nell'API Cloud Monitoring.
  • alertRule: se il criterio di avviso è stato migrato da un file di configurazione di Prometheus, questo campo contiene il valore del campo alert della regola di avviso nel file di configurazione di Prometheus. Questo campo non è obbligatorio quando crei un criterio di avviso PromQL nell'API Cloud Monitoring.

Ad esempio, la condizione seguente utilizza una query PromQL per trovare il numero di volte in cui un container è stato riavviato negli ultimi 30 minuti:

"conditionPrometheusQueryLanguage": {
  "query": "rate(kube_pod_container_status_restarts[30m]) * 1800 > 1",
  "duration": "10s",
  "alertRule": "ContainerRestartCount",
  "labels": {
    "action_required":"true",
    "severity":"critical/warning/info"}
}

Utilizza questa struttura come valore di un campo conditionPrometheusQueryLanguage in una condizione, che a sua volta è incorporata in una struttura dei criteri di avviso. Per maggiori informazioni su queste strutture, consulta AlertPolicy.

Di seguito è riportato un criterio completo con una condizione PrometheusQueryLanguageCondition in formato JSON:

{
  "displayName": "Container Restarts",
  "documentation": {
    "content": "Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes.",
    "mimeType": "text/markdown",
    "subject": "Container ${resource.label.container_name} in Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes."
  },
  "userLabels": {},
  "conditions": [
    {
      "displayName": "Container has restarted",
      "conditionPrometheusQueryLanguage": {
        "query": "rate(kubernetes_io:container_restart_count[30m]) * 1800",
        "duration": "10s",
        "alertRule": "ContainerRestart",
        "labels": {
          "action_required":"true",
          "severity":"critical/warning/info"}
      }
    }
  ],
  "alertStrategy": {
    "autoClose": "1800s"
  },
  "combiner": "OR",
  "enabled": true
}

crea un criterio di avviso

Per creare il criterio di avviso, inserisci il relativo JSON in un file denominato POLICY_NAME.json, quindi esegui questo comando:

curl -d @POLICY_NAME.json -H "Authorization: Bearer $TOKEN"
-H 'Content-Type: application/json'
-X POST https://monitoring.googleapis.com/v3/projects/${PROJECT}/alertPolicies

Per ulteriori informazioni sull'API Monitoring per i criteri di avviso, vedi Gestione dei criteri di avviso per API.

Per ulteriori informazioni sull'utilizzo di curl, vedi Richiamare curl.

Utilizzo di Terraform

Per istruzioni sulla configurazione dei criteri di avviso basati su PromQL utilizzando Terraform, consulta la sezione condition_prometheus_query_language del google_monitoring_alert_policy Registro Terraform.

Per informazioni generali sull'utilizzo di Google Cloud con Terraform, consulta Terraform con Google Cloud.

Richiamo di curl in corso...

Ogni chiamata curl include un insieme di argomenti, seguiti dall'URL di una risorsa API. Gli argomenti comuni includono un ID progetto Google Cloud e un token di autenticazione. Questi valori sono rappresentati qui dalle variabili di ambiente PROJECT_ID e TOKEN.

Potresti anche dover specificare altri argomenti, ad esempio per specificare il tipo di richiesta HTTP (ad esempio -X DELETE). La richiesta predefinita è GET, perciò gli esempi non la specificano.

Ogni chiamata di curl ha questa struttura generale:

curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

Per utilizzare curl, devi specificare il tuo ID progetto e un token di accesso. Per ridurre il numero di errori da digitare e gli errori, puoi inserirli nelle variabili di ambiente e trasferirli in questo modo a curl.

Per impostare queste variabili:

  1. Crea una variabile di ambiente che contenga l'ID del progetto di ambito delle metriche. Questi passaggi chiamano la variabile PROJECT_ID:

    PROJECT_ID=a-sample-project
    
  2. Esegui l'autenticazione in Google Cloud CLI:

    gcloud auth login
    
  3. Facoltativo. Per evitare di dover specificare il tuo ID progetto con ogni comando gcloud, imposta l'ID progetto come predefinito utilizzando gcloud CLI:

    gcloud config set project ${PROJECT_ID}
    
  4. Crea un token di autorizzazione e acquisiscilo in una variabile di ambiente. Questi passaggi chiamano la variabile TOKEN:

    TOKEN=`gcloud auth print-access-token`
    

    Devi aggiornare periodicamente il token di accesso. Se i comandi che hanno funzionato all'improvviso segnalano che il tuo account non è stato autenticato, invia di nuovo il comando.

  5. Per verificare di aver ricevuto un token di accesso, esegui l'echo della variabile TOKEN:

    echo ${TOKEN}
    ya29.GluiBj8o....