Crea criteri di avviso basati su PromQL (API)

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

Per informazioni generali, consulta la panoramica degli avvisi basati su PromQL.

Se lavori in un ambiente Prometheus al di fuori di Cloud Monitoring e disponi di regole di avviso Prometheus, puoi utilizzare Google Cloud CLI per eseguirne la migrazione a criteri di avviso basati su PromQL in Monitoring. Per maggiori informazioni, consulta la pagina Eseguire la migrazione di regole di avviso e destinatari da Prometheus.

Creare criteri di avviso con query PromQL

Utilizzi il metodo alertPolicies.create per creare programmaticamente criteri di avviso.

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

Di seguito è riportata una query PromQL per una condizione di 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

Costruzione del criterio di avviso

Per creare una criterio di avviso basata su PromQL, utilizza il tipo di condizione AlertPolicyPrometheusQueryLanguageCondition. 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. Equivalente al campo expr di una regola di avviso Prometheus standard.
  • duration: specifica il periodo di tempo durante il quale ogni valutazione della query deve generare un valore true prima che venga soddisfatta la condizione del criterio di avviso. Il valore deve essere un numero di minuti, espresso in secondi; ad esempio, 600s per una durata di 10 minuti. Per ulteriori 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 Prometheus, questo valore proviene dal gruppo di regole Prometheus che conteneva la regola di avviso 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 Prometheus, questo campo contiene il valore del campo name del gruppo di regole nel file di configurazione Prometheus. Questo campo non è obbligatorio quando crei un criterio di avviso PromQL nell'API Cloud Monitoring.

  • alertRule: se la criterio di avviso è stata migrata da un file di configurazione Prometheus, questo campo contiene il valore del campo alert della regola di avviso nel file di configurazione Prometheus. Questo campo non è obbligatorio quando crei un criterio di avviso PromQL nell'API Cloud Monitoring.

Ad esempio, la seguente condizione utilizza una query PromQL per trovare il numero di riavvii di un container negli ultimi 30 minuti:

"conditionPrometheusQueryLanguage": {
  "query": "rate(kube_pod_container_status_restarts[30m]) * 1800 > 1",
  "duration": "600s",
  evaluationInterval: "60s",
  "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 di criteri di avviso. Per saperne di più su queste strutture, consulta la sezione AlertPolicy.

Di seguito è riportata una policy completa con una condizione PrometheusQueryLanguageCondition in 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": "600s",
        evaluationInterval: "60s",
        "alertRule": "ContainerRestart",
        "labels": {
          "action_required":"true",
          "severity":"critical/warning/info"}
      }
    }
  ],
  "combiner": "OR",
  "enabled": true
}

Crea un criterio di avviso

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

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 saperne di più sull'API Monitoring per le policy di avviso, consulta Gestione delle policy di avviso tramite API.

Per maggiori informazioni sull'utilizzo di curl, consulta Richiamare curl.

Disattiva il controllo dell'esistenza delle metriche

Quando crei una criterio di avviso basata su PromQL, Google Cloud esegue una convalida per assicurarsi che le metriche a cui viene fatto riferimento nella condizione esistano già in Monitoring. Tuttavia, puoi ignorare questa convalida se devi creare un criterio di avviso prima che esistano le metriche. Ad esempio, potresti volerlo fare quando utilizzi l'automazione per creare nuovi progetti con un insieme standard di criteri di avviso predefiniti. Se non disattivi la convalida, la creazione criterio di avviso non va a buon fine finché non vengono create le metriche sottostanti.

Per disattivare il controllo dell'esistenza della metrica, aggiungi il campo "disableMetricValidation": true al tuo PrometheusQueryLanguageCondition:

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

Se la condizione di un criterio di avviso fa riferimento a una metrica inesistente, la condizione viene comunque eseguita in base all'intervallo di valutazione. Tuttavia, il risultato della query è sempre vuoto. Una volta che la metrica sottostante esiste, la query restituisce i dati.