Query con Grafana

Dopo aver eseguito il deployment di Google Cloud Managed Service per Prometheus, puoi eseguire query sui dati inviati al servizio gestito e visualizzare i risultati in grafici e dashboard.

Questo documento descrive gli ambiti delle metriche, che determinano i dati su cui puoi eseguire query, e come utilizzare Grafana per recuperare e utilizzare i dati che hai raccolto.

Tutte le interfacce di query per Managed Service per Prometheus sono configurate per recuperare i dati da Monarch utilizzando l'API Cloud Monitoring. Eseguendo query su Monarch anziché sui server Prometheus locali, ottieni il monitoraggio globale su larga scala.

Prima di iniziare

Se non hai ancora eseguito il deployment del servizio gestito, configura la raccolta gestita o la raccolta con deployment autonomo. Puoi saltare questa procedura se ti interessa solo eseguire query sulle metriche di Cloud Monitoring utilizzando PromQL.

Configura il tuo ambiente

Per evitare di inserire ripetutamente l'ID progetto o il nome del cluster, esegui la seguente configurazione:

  • Configura gli strumenti a riga di comando come segue:

    • Configura gcloud CLI per fare riferimento all'ID del tuo progetto Google Cloud:

      gcloud config set project PROJECT_ID

    • Configura l'interfaccia a riga di comando kubectl per utilizzare il cluster:

      kubectl config set-cluster CLUSTER_NAME

    Per ulteriori informazioni su questi strumenti, consulta le seguenti risorse:

Configura uno spazio dei nomi

Crea lo spazio dei nomi Kubernetes NAMESPACE_NAME per le risorse che crei nell'ambito dell'applicazione di esempio:

kubectl create ns NAMESPACE_NAME

Verifica le credenziali dell'account di servizio

Puoi saltare questa sezione se per il tuo cluster Kubernetes è abilitata Workload Identity.

Durante l'esecuzione su GKE, Managed Service per Prometheus recupera automaticamente le credenziali dall'ambiente in base all'account di servizio predefinito di Compute Engine. L'account di servizio predefinito ha le autorizzazioni necessarie, monitoring.metricWriter e monitoring.viewer, per impostazione predefinita. Se non utilizzi Workload Identity e in precedenza hai rimosso uno di questi ruoli dall'account di servizio del nodo predefinito, dovrai riaggiungere le autorizzazioni mancanti prima di continuare.

Se non stai eseguendo su GKE, consulta Fornire le credenziali in modo esplicito.

Configura un account di servizio per Workload Identity

Puoi saltare questa sezione se per il tuo cluster Kubernetes non è abilitata Workload Identity.

Managed Service per Prometheus acquisisce i dati delle metriche utilizzando l'API Cloud Monitoring. Se il cluster utilizza Workload Identity, devi concedere al tuo account di servizio Kubernetes l'autorizzazione all'API Monitoring. Questa sezione descrive quanto segue:

Crea e associa l'account di servizio

Questo passaggio viene visualizzato in diverse sezioni della documentazione di Managed Service per Prometheus. Se hai già eseguito questo passaggio come parte di un'attività precedente, non è necessario ripeterlo. Vai avanti per autorizzare l'account di servizio.

La seguente sequenza di comandi crea l'account di servizio gmp-test-sa e lo associa all'account di servizio Kubernetes predefinito nello spazio dei nomi NAMESPACE_NAME:

gcloud config set project PROJECT_ID \
&&
gcloud iam service-accounts create gmp-test-sa \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

Se utilizzi uno spazio dei nomi GKE o un account di servizio diverso, modifica i comandi di conseguenza.

Autorizza l'account di servizio

I gruppi di autorizzazioni correlate vengono raccolti in ruoli e concedi i ruoli a un'entità, in questo esempio l'account di servizio Google Cloud. Per ulteriori informazioni sui ruoli di Monitoring, consulta Controllo dell'accesso.

Il comando seguente concede all'account di servizio Google Cloud gmp-test-sa i ruoli dell'API Monitoring necessari per leggere i dati delle metriche.

Se hai già concesso all'account di servizio Google Cloud un ruolo specifico nell'ambito dell'attività precedente, non è necessario ripeterlo.

Per autorizzare il tuo account di servizio a leggere da un ambito delle metriche multiprogetto, segui queste istruzioni e poi consulta Modificare il progetto sottoposto a query. 

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer \
&& \
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator

Esegui il debug della configurazione di Workload Identity

Se hai difficoltà a utilizzare Workload Identity, consulta la documentazione per la verifica della configurazione di Workload Identity e la guida alla risoluzione dei problemi di Workload Identity.

Poiché gli errori di battitura e gli errori di copia-incolla parziali sono le fonti di errore più comuni durante la configurazione di Workload Identity, ti consigliamo vivamente di utilizzare le variabili modificabili e le icone di copia e incolla cliccabili incorporate negli esempi di codice di queste istruzioni.

Workload Identity negli ambienti di produzione

L'esempio descritto in questo documento associa l'account di servizio Google Cloud all'account di servizio Kubernetes predefinito e concede all'account di servizio Google Cloud tutte le autorizzazioni necessarie per utilizzare l'API Monitoring.

In un ambiente di produzione, è consigliabile utilizzare un approccio più granulare, con un account di servizio per ogni componente, ciascuno con autorizzazioni minime. Per maggiori informazioni sulla configurazione degli account di servizio per la gestione delle identità dei carichi di lavoro, consulta Utilizzo di Workload Identity.

Ambiti di query e metriche

I dati su cui è possibile eseguire query sono determinati dall'ambito delle metriche del costrutto di Cloud Monitoring, indipendentemente dal metodo utilizzato per eseguire le query sui dati. Ad esempio, se utilizzi Grafana per eseguire query su Managed Service per i dati di Prometheus, ogni ambito delle metriche deve essere configurato come origine dati separata.

Un ambito delle metriche di Monitoring è un costrutto di sola lettura che consente di eseguire query su dati delle metriche appartenenti a più progetti Google Cloud. Ogni ambito delle metriche è ospitato da un progetto Google Cloud designato, chiamato progetto di ambito.

Per impostazione predefinita, un progetto è il progetto di definizione dell'ambito per il proprio ambito delle metriche, che contiene le metriche e la configurazione per quel progetto. Un progetto di definizione dell'ambito può includere più di un progetto monitorato nell'ambito delle metriche e le metriche e le configurazioni di tutti i progetti monitorati nell'ambito delle metriche sono visibili al progetto di definizione dell'ambito. Un progetto monitorato può anche appartenere a più di un ambito delle metriche.

Quando esegui query sulle metriche in un progetto di definizione dell'ambito e se il progetto di definizione dell'ambito ospita un ambito delle metriche multiprogetto, puoi recuperare i dati da più progetti. Se l'ambito delle metriche contiene tutti i progetti, le query e le regole vengono valutate a livello globale.

Per ulteriori informazioni sulla definizione dell'ambito dei progetti e delle metriche, consulta Ambiti delle metriche. Per informazioni sulla configurazione dell'ambito delle metriche multiprogetto, consulta Visualizzare metriche per più progetti.

Managed Service per dati di Prometheus in Cloud Monitoring

Il modo più semplice per verificare che i dati di Prometheus vengano esportati è utilizzare la pagina Explorer metriche di Cloud Monitoring nella console Google Cloud, che supporta PromQL. Per le istruzioni, consulta Esecuzione di query con PromQL in Cloud Monitoring.

Puoi anche importare le tue dashboard Grafana in Cloud Monitoring. In questo modo puoi continuare a utilizzare le dashboard Grafana personali o create dalla community senza dover configurare o eseguire il deployment di un'istanza Grafana.

Grafana

Managed Service per Prometheus utilizza l'origine dati Prometheus integrata per Kubernetes, il che significa che puoi continuare a utilizzare le dashboard di Kubernetes personali o create dalla community senza alcuna modifica.

Deployment di Grafana

Se non hai un deployment Grafana in esecuzione nel tuo cluster, puoi creare un deployment di test temporaneo con cui sperimentare.

Per creare un deployment di Grafana temporaneo, applica il manifest grafana.yaml di Managed Service per Prometheus al cluster e esegui il port forwarding del servizio grafana alla tua macchina locale. L'esempio seguente inoltra il servizio alla porta 3000.

  1. Applica il manifest grafana.yaml:

    kubectl -n NAMESPACE_NAME apply -f  https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/6ebc1afa8e609febe8d687bb7fa6bd2375e46db1/examples/grafana.yaml

  2. Esegui il port forwarding del servizio grafana alla tua macchina locale. Questo esempio inoltra il servizio alla porta 3000:

    kubectl -n NAMESPACE_NAME port-forward svc/grafana 3000

    Questo comando non restituisce e, mentre è in esecuzione, segnala gli accessi all'URL.

    Puoi accedere a Grafana nel browser all'URL http://localhost:3000 con il nome utente:password admin:admin.

Quindi, aggiungi una nuova origine dati Prometheus a Grafana procedendo nel seguente modo:

  1. Vai al deployment di Grafana, ad esempio visitando l'URL http://localhost:3000 per accedere alla pagina di benvenuto di Grafana.

  2. Seleziona Connessioni dal menu principale di Grafana e poi seleziona Origini dati.

    Aggiunta di un'origine dati in Grafana.

  3. Seleziona Aggiungi origine dati e poi Prometheus come database della serie temporale.

    Aggiunta di un'origine dati Prometheus.

  4. Assegna un nome all'origine dati, imposta il campo URL su http://localhost:9090 e seleziona Salva e testa. Puoi ignorare gli eventuali errori che indicano che l'origine dati non è configurata correttamente.

  5. Copia l'URL del servizio locale per il tuo deployment, che sarà simile al seguente:

    http://grafana.NAMESPACE_NAME.svc:3000

Configurare e autenticare l'origine dati Grafana

Tutte le API Google Cloud richiedono l'autenticazione tramite OAuth2. Tuttavia, Grafana non supporta l'autenticazione OAuth2 per le origini dati Prometheus. Per utilizzare Grafana con Managed Service per Prometheus, devi utilizzare il sincronizzatore dell'origine dati per generare le credenziali OAuth2 e sincronizzarle con Grafana tramite l'API per origine dati Grafana.

Devi utilizzare il sincronizzatore delle origini dati per configurare e autorizzare Grafana a eseguire query sui dati a livello globale. Se non segui questi passaggi, Grafana esegue solo query sui dati nel server Prometheus locale.

Il sincronizzatore dell'origine dati è uno strumento di interfaccia a riga di comando che utilizza un Kubernetes CronJob per sincronizzare in remoto i valori di configurazione con una determinata origine dati Grafana Prometheus. Ciò garantisce che nell'origine dati Grafana sia configurato correttamente quanto segue:

  • Autenticazione mediante l'aggiornamento periodico di un token di accesso OAuth2
  • L'API Cloud Monitoring impostata come URL del server Prometheus
  • Il metodo HTTP impostato su GET
  • Il tipo e la versione di Prometheus sono impostati su un valore minimo di 2.40.x
  • I valori per HTTP e Timeout query sono impostati su 2 minuti

Il sincronizzatore dell'origine dati utilizza l'account di servizio locale del cluster per generare periodicamente un token di accesso all'API Google Cloud con le autorizzazioni IAM necessarie per eseguire query sui dati di Cloud Monitoring. Poiché i token di accesso all'API Google Cloud hanno una durata di un'ora, il sincronizzatore delle origini dati viene eseguito ogni 30 minuti per garantire una connessione autenticata ininterrotta tra Grafana e l'API Cloud Monitoring.

Per eseguire il deployment e l'esecuzione del sincronizzazione dell'origine dati:

  1. Scegli un progetto, un cluster e uno spazio dei nomi in cui eseguire il deployment del sincronizzatore dell'origine dati. Ti consigliamo di eseguire il deployment del sincronizzatore delle origini dati in un cluster appartenente al progetto di ambito di un ambito delle metriche multiprogetto. Il sincronizzazione dell'origine dati utilizza il progetto Google Cloud configurato come progetto di ambito.

    Dopodiché, assicurati di configurare e autorizzare correttamente il sincronizzazione delle origini dati:

    Poi, determina se devi autorizzare ulteriormente il sincronizzatore delle origini dati per le query multiprogetto:

  2. Calcola l'URL dell'istanza di Grafana, ad esempio https://yourcompanyname.grafana.net per un deployment di Grafana Cloud o http://grafana.NAMESPACE_NAME.svc:3000 per un'istanza locale configurata utilizzando il deployment di test YAML.

    Se esegui il deployment di Grafana in locale e il tuo cluster è configurato per proteggere tutto il traffico nel cluster tramite TLS, devi utilizzare https:// nell'URL ed eseguire l'autenticazione utilizzando una delle opzioni di autenticazione TLS supportate.

  3. Scegli l'origine dati Grafana Prometheus che vuoi utilizzare per Managed Service per Prometheus, che può essere un'origine dati nuova o preesistente, poi trova e annota l'UID dell'origine dati. L'UID dell'origine dati si trova nell'ultima parte dell'URL quando esplori o configuri un'origine dati, ad esempio https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID.

  4. Configura un account di servizio Grafana, concedigli il ruolo "Amministratore" e genera un token dell'account di servizio. Assicurati che la scadenza del token sia impostata su "Nessuna scadenza".

  5. Configura le seguenti variabili di ambiente utilizzando i risultati dei passaggi precedenti:

    # These values are required.
PROJECT_ID=SCOPING_PROJECT_ID
GRAFANA_API_ENDPOINT=GRAFANA_INSTANCE_URL
DATASOURCE_UIDS=GRAFANA_DATASOURCE_UID
GRAFANA_API_TOKEN=GRAFANA_SERVICE_ACCOUNT_TOKEN

  6. Esegui questo comando per creare un CronJob che aggiorni l'origine dati al momento dell'inizializzazione e poi ogni 30 minuti. Se utilizzi Workload Identity, il valore di NAMESPACE_NAME deve corrispondere allo spazio dei nomi precedentemente associato all'account di servizio.

    curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/main/cmd/datasource-syncer/datasource-syncer.yaml \
| sed 's|$DATASOURCE_UIDS|'"$DATASOURCE_UIDS"'|; s|$GRAFANA_API_ENDPOINT|'"$GRAFANA_API_ENDPOINT"'|; s|$GRAFANA_API_TOKEN|'"$GRAFANA_API_TOKEN"'|; s|$PROJECT_ID|'"$PROJECT_ID"'|;' \
| kubectl -n NAMESPACE_NAME apply -f -

  7. Vai all'origine dati Grafana appena configurata e verifica che il valore dell'URL del server Prometheus inizi con https://monitoring.googleapis.com. Potresti dover aggiornare la pagina. Dopo la verifica, vai in fondo alla pagina e seleziona Salva e testa. Devi selezionare questo pulsante almeno una volta per assicurarti che il completamento automatico delle etichette in Grafana funzioni.

Eseguire query utilizzando Grafana

Ora puoi creare dashboard Grafana ed eseguire query utilizzando l'origine dati configurata. Il seguente screenshot mostra un grafico di Grafana che mostra la metrica up:

Grafico di Grafana per la metrica Managed Service per Prometheus up.

Per informazioni sull'esecuzione di query sulle metriche di sistema di Google Cloud utilizzando PromQL, consulta Metriche di PromQL per Cloud Monitoring.

Esecuzione del sincronizzazione dell'origine dati al di fuori di GKE

Puoi saltare questa sezione se esegui il sincronizzatore delle origini dati in un cluster Google Kubernetes Engine. Se riscontri problemi di autenticazione su GKE, consulta Verificare le credenziali dell'account di servizio.

Durante l'esecuzione su GKE, il sincronizzatore dell'origine dati recupera automaticamente le credenziali dall'ambiente in base all'account di servizio del nodo o alla configurazione di Workload Identity. Nei cluster Kubernetes non GKE, le credenziali devono essere fornite esplicitamente al sincronizzatore delle origini dati utilizzando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

  1. Imposta il contesto per il progetto di destinazione:

    gcloud config set project PROJECT_ID

  2. Crea un account di servizio:

    gcloud iam service-accounts create gmp-test-sa

    Questo passaggio crea l'account di servizio che potresti aver già creato nelle istruzioni di Workload Identity.

  3. Concedi le autorizzazioni richieste all'account di servizio:

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer \
&& \
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator

  4. Crea e scarica una chiave per l'account di servizio:

    gcloud iam service-accounts keys create gmp-test-sa-key.json \
  --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

  5. Imposta il percorso del file della chiave utilizzando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

Autorizza il sincronizzatore dell'origine dati a ottenere il monitoraggio multiprogetto

Managed Service per Prometheus supporta il monitoraggio multiprogetto utilizzando gli ambiti delle metriche. Se il progetto locale è il progetto di definizione dell'ambito e hai seguito le istruzioni per verificare o configurare un account di servizio per il progetto locale, le query multiprogetto dovrebbero funzionare senza ulteriori configurazioni.

Se il progetto locale non è il progetto di definizione dell'ambito, devi autorizzare l'account di servizio Compute predefinito del progetto locale o l'account di servizio Workload Identity ad avere accesso monitoring.viewer al progetto di definizione dell'ambito. Quindi passa l'ID del progetto di definizione dell'ambito come valore della variabile di ambiente PROJECT_ID.

Se utilizzi l'account di servizio default di Compute Engine, puoi effettuare una delle seguenti operazioni:

Per concedere a un account di servizio le autorizzazioni necessarie per accedere a un altro progetto Google Cloud:

  1. Concedi all'account di servizio l'autorizzazione a leggere dal progetto di destinazione su cui vuoi eseguire la query:

    gcloud projects add-iam-policy-binding SCOPING_PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer

  2. Quando configuri il sincronizzatore dell'origine dati, passa l'ID del progetto di definizione dell'ambito come valore della variabile di ambiente PROJECT_ID.

Ispeziona il CronJob

Per esaminare il CronJob e assicurarti che tutte le variabili siano impostate correttamente, esegui questo comando:

kubectl describe cronjob datasource-syncer

Per visualizzare i log del job che configura inizialmente Grafana, esegui questo comando subito dopo aver applicato il file datasource-syncer.yaml:

kubectl logs job.batch/datasource-syncer-init

Smaltimento

Per disabilitare il Cronjob per il sincronizzatore dell'origine dati, esegui questo comando:

kubectl delete -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/main/cmd/datasource-syncer/datasource-syncer.yaml

La disattivazione del sincronizzatore dell'origine dati interrompe l'aggiornamento della risorsa Grafana collegata con credenziali di autenticazione aggiornate e, di conseguenza, l'esecuzione di query su Managed Service per Prometheus non funziona più.

Compatibilità delle API

I seguenti endpoint dell'API Prometheus HTTP sono supportati da Managed Service per Prometheus nell'URL con prefisso https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/.

Per la documentazione completa, consulta la documentazione di riferimento dell'API Cloud Monitoring.

Per informazioni sulla compatibilità con PromQL, consulta il supporto per PromQL.

  • I seguenti endpoint sono completamente supportati:

    • /api/v1/query
    • /api/v1/query_range
    • /api/v1/metadata
    • /api/v1/labels
    • /api/v1/query_exemplars

  • L'endpoint /api/v1/label/<label_name>/values funziona solo se l'etichetta __name__ viene fornita utilizzandola come valore <label_name> o corrispondendo esattamente all'etichetta tramite un selettore di serie. Ad esempio, le seguenti chiamate sono pienamente supportate:

    • /api/v1/label/__name__/values
    • /api/v1/label/__name__/values?match[]={__name__=~".*metricname.*"}
    • /api/v1/label/labelname/values?match[]={__name__="metricname"}

    Questa limitazione determina l'esito negativo delle query con variabile label_values($label) in Grafana. Puoi invece utilizzare label_values($metric, $label). Questo tipo di query è consigliato perché evita di recuperare i valori per le etichette su metriche che non sono pertinenti per la dashboard specifica.

  • L'endpoint /api/v1/series è supportato per le richieste GET ma non per POST. Quando utilizzi il sincronizzatore dell'origine dati o il proxy frontend, questa limitazione viene gestita automaticamente. Puoi anche configurare le origini dati Prometheus in Grafana per inviare solo le richieste GET.

Passaggi successivi