Utilizzare il file collaterale Prometheus per Cloud Run

Il sidecar Managed Service per Prometheus per Cloud Run è il metodo consigliato da Google per ottenere il monitoraggio in stile Prometheus per i servizi Cloud Run. Se il tuo servizio Cloud Run scrive metriche OTLP, puoi utilizzare il sidecar OpenTelemetry. Tuttavia, per i servizi che scrivono metriche Prometheus, utilizza il sidecar di Managed Service per Prometheus descritto in questo documento.

Questo documento descrive come:

• Aggiungi il sidecar di Managed Service per Prometheus a un servizio Cloud Run esistente.
• Crea un'app di esempio con il sidecar. Puoi utilizzare l'app di esempio per scoprire come funziona il sidecar se non hai già un servizio Cloud Run.

Il sidecar utilizza Google Cloud Managed Service per Prometheus lato server e una distribuzione del raccoglitore OpenTelemetry, personalizzata per i carichi di lavoro serverless, lato client. Questa distribuzione personalizzata include alcune modifiche per supportare Cloud Run. Il collector esegue uno scan all'avvio dopo 10 secondi e uno scan al termine, indipendentemente dalla durata dell'istanza. Per la massima affidabilità, consigliamo ai servizi Cloud Run che eseguono il sidecar di utilizzare anche una CPU sempre allocata. Per ulteriori informazioni, consulta Allocazione della CPU (servizi). Alcuni tentativi di scraping potrebbero non andare a buon fine se l'allocazione della CPU è limitata a causa di un numero ridotto di query al secondo (QPS). Una CPU sempre allocata rimane disponibile.

Il sidecar si basa sulla funzionalità multicontainer (sidecar) di Cloud Run per eseguire il collector come container sidecar insieme al container del carico di lavoro. Per ulteriori informazioni sui sidecar in Cloud Run, consulta Eseguire il deployment di più container in un servizio (sidecar).

Il file collaterale Managed Service per Prometheus per Cloud Run introduce una nuova configurazione,RunMonitoring, un sottoinsieme della risorsa personalizzata PodMonitoring di Kubernetes. La maggior parte degli utenti può utilizzare la configurazione predefinita RunMonitoring, ma puoi anche creare configurazioni personalizzate. Per ulteriori informazioni sulle configurazioni RunMonitoring predefinite e personalizzate, consulta Aggiungere il sidecar a un servizio Cloud Run.

Prima di iniziare

Questa sezione descrive la configurazione necessaria per utilizzare questo documento.

Installa e configura la gcloud CLI

Molti dei passaggi descritti in questo documento utilizzano Google Cloud CLI. Per informazioni sull'installazione dell'interfaccia alla gcloud CLI, consulta Gestire i componenti dell'interfaccia a riga di comando Google Cloud.

Quando richiami i comandi gcloud, devi specificare l'identificatore per il tuo progetto Google Cloud. Puoi impostare un progetto predefinito per Google Cloud CLI ed eliminare la necessità di inserirlo con ogni comando. Per impostare il progetto come predefinito, inserisci il seguente comando:

gcloud config set project PROJECT_ID

Puoi anche impostare una regione predefinita per il servizio Cloud Run. Per impostare una regione predefinita, inserisci il seguente comando:

gcloud config set run/region REGION

Abilita API

Devi abilitare le seguenti API nel tuo progetto Google Cloud:

• API Cloud Run Admin: run.googleapis.com
• API Artifact Registry: artifactregistry.googleapis.com
• API Cloud Monitoring: monitoring.googleapis.com
• API Cloud Logging: logging.googleapis.com
• (Facoltativo) Se crei una RunMonitoring configurazione personalizzata, devi attivare l'API Secret Manager: secretmanager.googleapis.com
• (Facoltativo) Se scegli di eseguire l'app di esempio utilizzando Cloud Build, devi anche attivare le seguenti API:
  • API Cloud Build: cloudbuild.googleapis.com.
  • API Identity and Access Management: iam.googleapis.com. Per maggiori informazioni, vedi Creare ed eseguire l'app di esempio.

Per visualizzare le API abilitate nel tuo progetto, esegui il seguente comando:

gcloud services list

Per abilitare un'API non abilitata, esegui uno dei seguenti comandi:

gcloud services enable run.googleapis.com
gcloud services enable artifactregistry.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable monitoring.googleapis.com
gcloud services enable logging.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable iam.googleapis.com

Account di servizio per Cloud Run

Per impostazione predefinita, i job e i servizi Cloud Run utilizzano l'account di servizio predefinito di Compute Engine,PROJECT_NUMBER-compute@developer.gserviceaccount.com. In genere, questo account di servizio dispone dei ruoli IAM (Identity and Access Management) necessari per scrivere le metriche e i log descritti in questo documento:

• roles/monitoring.metricWriter
• roles/logging.logWriter

Se crei una configurazione RunMonitoring personalizzata, l'account di servizio deve disporre anche dei seguenti ruoli:

• roles/secretmanager.admin
• roles/secretmanager.secretAccessor

Puoi anche configurare un account di servizio gestito dall'utente per Cloud Run. Un account di servizio gestito dall'utente deve avere anche questi ruoli. Per ulteriori informazioni sugli account di servizio per Cloud Run, consulta Configurazione dell'identità di servizio.

Configurare e aggiungere il sidecar a un servizio Cloud Run

Il file collaterale Managed Service per Prometheus per Cloud Run introduce una nuova configurazione,RunMonitoring, che è un sottoinsieme della risorsa personalizzata PodMonitoring di Kubernetes. La configurazione RunMonitoring utilizza le opzioni PodMonitoring esistenti per supportare Cloud Run, eliminando al contempo alcune opzioni specifiche di Kubernetes.

Puoi utilizzare la configurazione predefinita RunMonitoring o creare una configurazione personalizzata. Le sezioni seguenti descrivono entrambi gli approcci. Non è necessario farlo da entrambe le piattaforme. Per ulteriori informazioni sull'utilizzo delle configurazioni predefinite o personalizzate, seleziona la scheda corrispondente.

apiVersion: monitoring.googleapis.com/v1beta
kind: RunMonitoring
metadata:
  name: run-gmp-sidecar
spec:
  endpoints:
  - port: 8080
    path: /metrics
    interval: 30s

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    run.googleapis.com/launch-stage: ALPHA
    run.googleapis.com/cpu-throttling: 'false'
  name: my-cloud-run-service
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
+       run.googleapis.com/container-dependencies: '{"collector":["app"]}'
    spec:
      containers:
      - image: "REGION-docker.pkg.dev/PROJECT_ID/run-gmp/sample-app"
        name: app
        startupProbe:
          httpGet:
            path: /startup
            port: 8000
        livenessProbe:
          httpGet:
            path: /liveness
            port: 8000
        ports:
        - containerPort: 8000
+     - image: "us-docker.pkg.dev/cloud-ops-agents-artifacts/cloud-run-gmp-sidecar/cloud-run-gmp-sidecar:1.2.0"
+       name: collector

gcloud run services replace run-service.yaml --region=REGION

apiVersion: monitoring.googleapis.com/v1beta
kind: RunMonitoring
metadata:
  name: my-custom-cloud-run-job
spec:
  endpoints:
  - port: 8080
    path: /metrics
    interval: 10s
    metricRelabeling:
    - action: replace
      sourceLabels:
      - __address__
      targetLabel: label_key
      replacement: label_value
  targetLabels:
    metadata:
    - service
    - revision

gcloud secrets create mysecret --data-file=custom-config.yaml

gcloud secrets versions add mysecret --data-file=custom-config-updated.yaml

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    run.googleapis.com/launch-stage: ALPHA
    run.googleapis.com/cpu-throttling: 'false'
  name: my-cloud-run-service
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
+       run.googleapis.com/container-dependencies: '{"collector":["app"]}'
+       run.googleapis.com/secrets: 'mysecret:projects/PROJECT_ID/secrets/mysecret'
    spec:
      containers:
      - image: "REGION-docker.pkg.dev/PROJECT_ID/run-gmp/sample-app"
        name: app
        startupProbe:
          httpGet:
            path: /startup
            port: 8000
        livenessProbe:
          httpGet:
            path: /liveness
            port: 8000
        ports:
        - containerPort: 8000
+     - image: "us-docker.pkg.dev/cloud-ops-agents-artifacts/cloud-run-gmp-sidecar/cloud-run-gmp-sidecar:1.2.0"
+       name: collector
+       volumeMounts:
+       - mountPath: /etc/rungmp/
+         name: config
+     volumes:
+     - name: config
+       secret:
+         items:
+         - key: latest
+           path: config.yaml
+         secretName: 'mysecret'

gcloud run services replace run-service.yaml --region=REGION

apiVersion: monitoring.googleapis.com/v1beta
kind: RunMonitoring
metadata:
  name: my-custom-cloud-run-job
spec:
  endpoints:
  - port: 8080
    path: /metrics
    interval: 10s
    metricRelabeling:
    - action: replace
      sourceLabels:
      - __address__
      targetLabel: label_key
      replacement: label_value
  targetLabels:
    metadata:
    - service
    - revision

Crea ed esegui un'app di esempio

Questa sezione descrive come eseguire il sidecar di Managed Service per Prometheus con un'app di esempio. Questa sezione è facoltativa. Se hai già un servizio Cloud Run e vuoi eseguire il deployment del sidecar al suo interno, consulta Aggiungere il sidecar di Managed Service per Prometheus a un servizio Cloud Run.

Clona il repository run-gmp-sidecar

Per ottenere l'app di esempio e i relativi file di configurazione, clona il repository run-gmp-sidecar eseguendo il seguente comando:

git clone https://github.com/GoogleCloudPlatform/run-gmp-sidecar/

Dopo aver clonato il repository, passa alla directory run-gmp-sidecar:

cd run-gmp-sidecar

Crea ed esegui l'app di esempio

L'app di esempio richiede Docker o un sistema di compilazione di container simile per Linux. Puoi compilare ed eseguire l'app di esempio in uno dei seguenti modi:

• Utilizza Cloud Build per eseguire l'applicazione senza il supporto di Docker locale. Se utilizzi Cloud Build, devi anche attivare l'API Cloud Build.
• Crea ed esegui manualmente l'app di esempio.

Le sezioni seguenti descrivono entrambi gli approcci. Non è necessario farlo da entrambe le piattaforme. Per ulteriori informazioni, seleziona la scheda di uno degli approcci.

./create-sa-and-ar.sh

gcloud builds submit . --config=cloudbuild-simple.yaml --region=REGION

Logs are available at [
https://console.cloud.google.com/cloud-build/builds/637860fb-7a14-46f2-861e-09c1dc4cea6b?project=PROJECT_NUMBER].

gcloud run services describe my-cloud-run-service --region=REGION --format="value(status.url)"

https://my-cloud-run-service-abcdefghij-ue.a.run.app

export GCP_PROJECT=PROJECT_ID
export REGION=REGION

gcloud artifacts repositories create run-gmp \
    --repository-format=docker \
    --location=${REGION}

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    run.googleapis.com/launch-stage: ALPHA
    run.googleapis.com/cpu-throttling: 'false'
  name: my-cloud-run-service
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
        run.googleapis.com/container-dependencies: '{"collector":["app"]}'
    spec:
      containers:
      - image: "%SAMPLE_APP_IMAGE%"
        name: app
        startupProbe:
          httpGet:
            path: /startup
            port: 8000
        livenessProbe:
          httpGet:
            path: /liveness
            port: 8000
        ports:
        - containerPort: 8000
      - image: "us-docker.pkg.dev/cloud-ops-agents-artifacts/cloud-run-gmp-sidecar/cloud-run-gmp-sidecar:1.2.0"
        name: collector

sed -i s@%SAMPLE_APP_IMAGE%@REGION-docker.pkg.dev/${GCP_PROJECT}/run-gmp/sample-app@g run-service-simple.yaml

gcloud run services replace run-service-simple.yaml --region=REGION
   

https://my-cloud-run-service-abcdefghij-ue.a.run.app

gcloud run services set-iam-policy my-cloud-run-service policy.yaml --region=REGION

Verifica che l'app sia in esecuzione

Per verificare che il servizio Cloud Run abbia eseguito correttamente l'app di esempio, utilizza l'utilità curl per accedere all'endpoint metrics del servizio.

1. Imposta la variabile di ambiente SERVICE_URL sull'URL del servizio Cloud Run del passaggio precedente:

   export SERVICE_URL=SERVICE_URL
   

2. Invia una richiesta all'URL del servizio eseguendo il seguente comando:

   curl $SERVICE_URL
   

Se l'app è stata avviata correttamente, viene visualizzata la seguente risposta:

User request received!

Visualizzare le metriche delle app in Metrics Explorer

Il contenitore app di esempio scrive le seguenti metriche:

• foo_metric: l'ora corrente come valore in virgola mobile (indicatore).
• bar_metric: l'ora corrente come valore in virgola mobile (contatore).

Per visualizzare queste metriche in Metrics Explorer, segui questi passaggi:

1. Nella console Google Cloud, vai alla pagina leaderboard Esplora metriche:

   Vai a Esplora metriche

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

2. Nella barra degli strumenti del riquadro Query Builder, seleziona il pulsante code MQL o code PromQL.

3. Verifica che PromQL sia selezionato nel pulsante di attivazione/disattivazione Lingua. Il pulsante di attivazione/disattivazione della lingua si trova nella stessa barra degli strumenti che consente di formattare la query.

4. Inserisci la seguente query nel riquadro dell'editor:

   foo_metric
   

5. Fai clic su Aggiungi query.

6. Nella barra degli strumenti del riquadro Query Builder, seleziona il pulsante code MQL o code PromQL.

7. Verifica che PromQL sia selezionato nel pulsante di attivazione/disattivazione Lingua. Il pulsante di attivazione/disattivazione della lingua si trova nella stessa barra degli strumenti che consente di formattare la query.

8. Inserisci la seguente query nel secondo riquadro dell'editor:

   bar_metric
   

9. Fai clic su Esegui query.

10. Per visualizzare i dettagli sulle metriche, seleziona Entrambe nell'opzione di attivazione/disattivazione Tabella del grafico Entrambe.

Esegui la pulizia

Al termine dell'esperimento con l'app di esempio, puoi utilizzare lo script clean-up-cloud-run.sh nel repository run-gmp-sidecar per eliminare le seguenti risorse che potresti aver creato per l'esempio:

• Il servizio Cloud Run.
• Il repository Artifact Registry.
• L'account di servizio creato per Cloud Build.

L'eliminazione di queste risorse ti garantisce di non sostenere costi dopo l'esecuzione del sample.

Per ripulire l'app di esempio, esegui lo script clean-up-cloud-run.sh:

./clean-up-cloud-run.sh

Visualizzare le metriche relative all'utente in Metrics Explorer

Il sidecar di Managed Service per Prometheus registra le seguenti metriche su se stesso in Cloud Monitoring:

• agent_uptime: il tempo di attività del collector sidecar (contatore).
• agent_memory_usage: la memoria utilizzata dal collector sidecar (indicatore).
• agent_api_request_count: il numero di richieste API dal collector sidecar (contatore).
• agent_monitoring_point_count: il numero di punti metrici scritti in Cloud Monitoring dal collector sidecar (contatore).

Per visualizzare le metriche del sidecar in Metrics Explorer, segui questi passaggi:

1. Nella console Google Cloud, vai alla pagina leaderboard Esplora metriche:

   Vai a Esplora metriche

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

2. Nella barra degli strumenti del riquadro Query Builder, seleziona il pulsante code MQL o code PromQL.

3. Verifica che PromQL sia selezionato nel pulsante di attivazione/disattivazione Lingua. Il pulsante di attivazione/disattivazione della lingua si trova nella stessa barra degli strumenti che consente di formattare la query.

4. Inserisci il nome della metrica per cui vuoi eseguire una query nel riquadro dell'editor, ad esempio:

   agent_api_request_count
   

5. Fai clic su Esegui query.

6. Per visualizzare i dettagli sulle metriche, seleziona Entrambe nell'opzione di attivazione/disattivazione Tabella del grafico Entrambe.

Visualizzare i log personali in Esplora log

Il sidecar di Managed Service per Prometheus scrive i log in Cloud Logging. Il sidecar scrive log in base al tipo di risorsa monitorata di Logging cloud_run_revision.

Per visualizzare i log del sidecar in Esplora log:

1. Nella console Google Cloud, vai alla pagina Esplora log:

   Vai a Esplora log

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

2. Seleziona il tipo di risorsa Revisione Cloud Run oppure inserisci la seguente query e fai clic su Esegui query:

   resource.type="cloud_run_revision"
   

Informazioni sulle metriche raccolte

Quando le metriche emesse dal sidecar vengono importate in Cloud Monitoring, vengono scritte in base al tipo di risorsa monitorata prometheus_target di Cloud Monitoring. Questo tipo di risorsa viene utilizzato sia per le metriche dell'applicazione sia per le metriche del sidecar.

Quando scrive le metriche, il sidecar imposta le etichette delle risorse come segue:

• project_id: l'ID del progetto Google Cloud in cui è in esecuzione il contenitore.
• location: la regione Google Cloud in cui è in esecuzione il contenitore.
• cluster: il valore __run__.
• namespace: il nome del servizio Cloud Run in esecuzione; proviene dalla variabile di ambiente K_SERVICE.
• job: nome della configurazione RunMonitoring; il valore predefinito è run-gmp-sidecar.
• instance: il valore faas.ID:PORT del carico di lavoro locale da cui il contenitore è configurato per estrarre le metriche. Il valore faas.ID è l'ID istanza dell'istanza Cloud Run.

Il sidecar aggiunge anche le seguenti etichette delle metriche:

• instanceId: l'ID dell'istanza Cloud Run.
• service_name: il nome del servizio Cloud Run in esecuzione.
• revision_name: il nome della revisione Cloud Run in esecuzione.
• configuration_name: il nome della configurazione Cloud Run in esecuzione.

Queste etichette delle metriche vengono aggiunte per impostazione predefinita. Se utilizzi una configurazione RunMonitoring personalizzata, puoi omettere le etichette service_name, revision_name e configuration_name utilizzando l'opzione targetLabels nella specifica RunMonitoring. Puoi anche utilizzare una configurazione personalizzata per rinominare i valori delle etichette service_name, revision_name e configuration_name.

Tutte le altre etichette visualizzate con le metriche importate provengono dalla metrica. Se un'etichetta definita dall'utente è in conflitto con una delle etichette fornite dal sistema, all'etichetta definita dall'utente viene anteposto il prefisso exported_. Ad esempio, un'etichetta specificata dall'utente namespace="playground" è in conflitto con l'etichetta namespace definita dal sistema, pertanto l'etichetta utente viene visualizzata come exported_namespace="playground".

Tipo di metrica

Quando le metriche emesse dal sidecar vengono importate in Cloud Monitoring, vengono scritte come metriche prometheus.googleapis.com e il tipo della metrica Prometheus viene aggiunto alla fine del nome. Ad esempio, l'app di esempio emette una metrica di indicatore Prometheus denominata foo_metric. In Cloud Monitoring, la metrica viene archiviata come tipo di metrica prometheus.googleapis.com/foo_metric/gauge.

Quando esegui una query sulla metrica con PromQL, puoi utilizzare il nome di Prometheus, come illustrato in Visualizzare le metriche dell'app in Metrics Explorer e Visualizzare le metriche relative all'entità in Metrics Explorer. Quando utilizzi strumenti come Query Builder o Monitoring Query Language (MQL) in Metrics Explorer, il tipo di metrica di Cloud Monitoring è pertinente.

Fatturazione

Le metriche emesse dal sidecar vengono importate in Cloud Monitoring con il prefisso prometheus.googleapis.com. Per le metriche con questo prefisso viene addebitato il costo in base al numero di campioni importati. Per ulteriori informazioni sulla fatturazione e su Managed Service per Prometheus, consulta Fatturazione.