Configura un'applicazione gRPC su Google Cloud con l'osservabilità dei microservizi

---

Gli strumenti di osservabilità dei microservizi ti consentono di instrumentare le tue applicazioni per raccogliere e presentare i dati di telemetria in Cloud Monitoring, Cloud Logging e Cloud Trace dai carichi di lavoro gRPC di cui è stato eseguito il deployment su Google Cloud e altrove. L'osservabilità dei microservizi funziona con qualsiasi implementazione a cui è stata concessa l'autorizzazione per accedere a Monitoraggio, Logging e Trace attivando l'API Microservices.

In questo tutorial imparerai a utilizzare le funzionalità di monitoraggio dei microservizi creando una semplice applicazione gRPC su Google Cloud utilizzando Compute Engine e strumentando l'applicazione con la funzionalità di monitoraggio dei microservizi, nonché visualizzarle in tempo reale in Monitoraggio e Logging.

Obiettivi

A livello generale, svolgi i seguenti passaggi.

• In qualità di sviluppatore di servizi, puoi:

  • Crea un'applicazione gRPC con il linguaggio che preferisci (C++, Go o Java).
  • Attiva l'applicazione e controlla il plug-in di osservabilità dei microservizi.
  • Esegui il deployment dell'applicazione su una VM Compute Engine.

• In qualità di operatore di servizi, utilizzi i dati raccolti in vari modi:

  • Visualizza le tracce in Trace.
  • Visualizza le metriche nella dashboard di monitoraggio Monitoraggio dei microservizi (gRPC).
  • Visualizza le metriche in Metrics Explorer.
  • Esamina le voci di log in Esplora log.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

• Compute Engine

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi Google Cloud utenti potrebbero avere diritto a una prova gratuita.

Al termine delle attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la sezione Pulizia.

Prima di iniziare

Console

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Compute Engine, and Microservices API APIs.

   Enable the APIs

5. Create a service account:

   1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
   2. Select your project.

   3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

      In the Service account description field, enter a description. For example, Service account for quickstart.

   4. Click Create and continue.

   5. Grant the following roles to the service account: Logging > Logs Viewer > Logs Writer, Monitoring > Monitoring Editor > Metrics Writer, Trace > Trace Admin > Trace Agent.

      To grant a role, find the Select a role list, then select the role.

      To grant additional roles, click Add another role and add each additional role.

      Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
   6. Click Continue.

   7. In the Service account users role field, enter the identifier for the principal that will attach the service account to other resources, such as Compute Engine instances.

      This is typically the email address for a Google Account.

   8. Click Done to finish creating the service account.

6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

7. Make sure that billing is enabled for your Google Cloud project.

8. Enable the Compute Engine, and Microservices API APIs.

   Enable the APIs

9. Create a service account:

   1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
   2. Select your project.

   3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

      In the Service account description field, enter a description. For example, Service account for quickstart.

   4. Click Create and continue.

   5. Grant the following roles to the service account: Logging > Logs Viewer > Logs Writer, Monitoring > Monitoring Editor > Metrics Writer, Trace > Trace Admin > Trace Agent.

      To grant a role, find the Select a role list, then select the role.

      To grant additional roles, click Add another role and add each additional role.

      Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
   6. Click Continue.

   7. In the Service account users role field, enter the identifier for the principal that will attach the service account to other resources, such as Compute Engine instances.

      This is typically the email address for a Google Account.

   8. Click Done to finish creating the service account.

10. Leggi la panoramica dell'osservabilità dei microservizi.
11. Leggi le informazioni sulle due variabili di ambiente supportate, decidi quale utilizzare e determina i valori richiesti dalla variabile di ambiente.

interfaccia a riga di comando

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Compute Engine, and Microservices API APIs:

   gcloud services enable compute.googleapis.com microservices.googleapis.com

7. Set up authentication:

   1. Create the service account:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Replace SERVICE_ACCOUNT_NAME with a name for the service account.

   2. Grant roles to the service account. Run the following command once for each of the following IAM roles: roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.agent:

      gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

      Replace the following:

      • SERVICE_ACCOUNT_NAME: the name of the service account
      • PROJECT_ID: the project ID where you created the service account
      • ROLE: the role to grant
      Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.

   3. Grant the required role to the principal that will attach the service account to other resources.

      gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

      Replace the following:

      • SERVICE_ACCOUNT_NAME: the name of the service account
      • PROJECT_ID: the project ID where you created the service account
      • USER_EMAIL: the email address for a Google Account
8. Install the Google Cloud CLI.

9. To initialize the gcloud CLI, run the following command:

   gcloud init

10. Create or select a Google Cloud project.

    Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

11. Make sure that billing is enabled for your Google Cloud project.

12. Enable the Compute Engine, and Microservices API APIs:

    gcloud services enable compute.googleapis.com microservices.googleapis.com

13. Set up authentication:

    1. Create the service account:

       gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

       Replace SERVICE_ACCOUNT_NAME with a name for the service account.

    2. Grant roles to the service account. Run the following command once for each of the following IAM roles: roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.agent:

       gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

       Replace the following:

       • SERVICE_ACCOUNT_NAME: the name of the service account
       • PROJECT_ID: the project ID where you created the service account
       • ROLE: the role to grant
       Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.

    3. Grant the required role to the principal that will attach the service account to other resources.

       gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

       Replace the following:

       • SERVICE_ACCOUNT_NAME: the name of the service account
       • PROJECT_ID: the project ID where you created the service account
       • USER_EMAIL: the email address for a Google Account
14. Leggi la panoramica dell'osservabilità dei microservizi.
15. Leggi le informazioni sulle due variabili di ambiente supportate, decidi quale utilizzare e determina i valori richiesti dalla variabile di ambiente.

Creare e connettersi a una VM Compute Engine

Segui queste istruzioni per creare e connetterti a un'istanza VM di Compute Engine. Nella VM esegui il deployment dell'applicazione e poi la strumenti con l'osservabilità dei microservizi.

1. Crea un'istanza VM:

   gcloud compute instances create grpc-observability-vm \
     --image-family=debian-11 \
     --image-project=debian-cloud \
     --service-account=SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com
   

2. Connettiti all'istanza VM:

   gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm
   

Esegui il deployment dell'applicazione nella VM Compute Engine

Puoi eseguire il deployment di un'applicazione a tua scelta nella VM Compute Engine creata nel passaggio precedente, quindi saltare questo passaggio oppure utilizzare un esempio per continuare con le istruzioni nella lingua che preferisci.

C++

1. Dopo aver eseguito la connessione all'istanza VM, esegui il seguente comando.

   sudo apt-get update -y
   sudo apt-get install -y git build-essential clang
   git clone -b v1.54.0 https://github.com/grpc/grpc.git --depth=1
   

Vai

1. Assicurati di avere installato Go.

   sudo apt-get install -y git
   sudo apt install wget
   wget https://go.dev/dl/go1.20.2.linux-amd64.tar.gz
   sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf \
   go1.20.2.linux-amd64.tar.gz
   export PATH=$PATH:/usr/local/go/bin
   

2. Clona gli esempi gRPC-Go.

   git clone https://github.com/grpc/grpc-go.git
   cd grpc-go/
   git checkout -b run-observability-example
   875c97a94dca8093bf01ff2fef490fbdd576373d
   

Java

1. Dopo aver eseguito la connessione all'istanza VM, assicurati di aver installato Java 8 o versioni successive.

   sudo apt update
   sudo apt upgrade
   sudo apt install git
   sudo apt-get install -y openjdk-11-jdk-headless
   

2. Clona il repository grpc-java.

   export EXAMPLES_VERSION=v1.54.1
   git clone -b $EXAMPLES_VERSION --single-branch --depth=1 \
   https://github.com/grpc/grpc-java.git
   

Crea il file di configurazione dell' Google Cloud osservabilità gRPC

Per attivare l'osservabilità dei microservices sia per il server che per il client, devi avere un file di configurazione Google Cloud di osservabilità gRPC separato. La posizione di questo file viene esportata come GRPC_GCP_OBSERVABILITY_CONFIG_FILE nei passaggi futuri. Segui le istruzioni riportate di seguito per configurare i diversi parametri nel file di configurazione.

Esempio GRPC_GCP_OBSERVABILITY_CONFIG_FILE

{
  "project_id": "your-project-here",
  "cloud_logging": {
    "client_rpc_events": [
    {
      "methods": ["google.pubsub.v1.Subscriber/Acknowledge", "google.pubsub.v1.Publisher/CreateTopic"],
      "exclude": true,
    },
    {
      "methods": ["google.pubsub.v1.Subscriber/*", "google.pubsub.v1.Publisher/*"],
      "max_metadata_bytes": 4096,
      "max_message_bytes": 4096,
    }],
    "server_rpc_events": [{
      "methods": ["*"],
      "max_metadata_bytes": 4096,
      "max_message_bytes": 4096
    }],
  },
  "cloud_monitoring": {},
  "cloud_trace": {
    "sampling_rate": 0.5,
  }
  "labels": {
    "SOURCE_VERSION": "J2e1Cf",
    "SERVICE_NAME": "payment-service-1Cf",
    "DATA_CENTER": "us-west1-a"
  }
}

Le sezioni seguenti contengono istruzioni per attivare la raccolta dei dati nella configurazione per i singoli componenti. Se hai utilizzato l'esempio gRPC in questo tutorial, puoi utilizzare questa configurazione così com'è (dopo l'aggiornamentoyour-project-here) o come modello per la tua applicazione.ed un esempio che mostra le informazioni di configurazione in una variabile di ambiente.

Attiva le metriche

Per attivare le metriche, aggiungi l'oggetto cloud_monitoring alla configurazione e impostane il valore su {}.

Per ulteriori informazioni sulle metriche, consulta Definizioni delle metriche.

Attiva il monitoraggio

Per attivare il monitoraggio, segui questi passaggi:

1. Aggiungi l'oggetto cloud_trace alla configurazione.
2. Imposta cloud_trace.sampling_rate su 0.5 per monitorare in modo casuale il 50% delle RPC.

Se prevedi di attivare il monitoraggio in più servizi, assicurati che i servizi supportino la propagazione del contesto della traccia ricevuto dall'upstream (o avviato autonomamente) al downstream.

Per ulteriori informazioni sul monitoraggio, consulta Definizioni dei traccianti.

Abilita il logging

Per attivare il logging:

1. Aggiungi l'oggetto cloud_logging alla configurazione.
2. Aggiungi un pattern a client_rpc_events e/o server_rpc_events specificando l'insieme di servizi o metodi per i quali vuoi generare il logging degli eventi a livello di trasporto e il numero di byte da registrare per intestazioni e messaggi.

Per ulteriori informazioni sul logging, consulta Definizioni dei record dei log.

Fornisci strumenti alle tue applicazioni per il plug-in di osservabilità

Per instrumentare le applicazioni in modo che possano utilizzare il plug-in di osservabilità dei microservizi, segui le istruzioni riportate di seguito per la lingua che preferisci.

C++

Puoi utilizzare C++ con l'osservabilità dei microservizi a partire dalla versione 1.54 di gRPC C++. Il repository di esempio si trova su GitHub.

1. Il supporto dell'osservabilità è disponibile solo tramite il sistema di compilazione Bazel. Aggiungi grpcpp_gcp_observability di destinazione come dipendenza.

2. L'attivazione dell'osservabilità dei microservizi richiede un'ulteriore dipendenza (un modulo di osservabilità) e le seguenti modifiche al codice di client, server o entrambi gRPC esistenti:

   #include <grpcpp/ext/gcp_observability.h>
   
   int main(int argc, char** argv) {
     auto observability = grpc::GcpObservability::Init();
     assert(observability.ok());
     …
     // Observability data flushed when object goes out of scope
   }
   

   Prima di qualsiasi operazione gRPC, inclusa la creazione di un canale, un server o delle credenziali, richiama quanto segue:

   grpc::GcpObservability::Init();
   

   Viene restituito absl::StatusOr<GcpObservability>, che deve essere salvato. Lo stato aiuta a determinare se l'osservabilità è stata inizializzata correttamente. L'oggetto GcpObservability associato controlla la durata dell'osservabilità e chiude e svuota automaticamente i dati di osservabilità quando esce dall'ambito.

Vai

1. I plug-in di osservabilità dei microservizi sono supportati per le versioni di gRPC Gov1.54.0 e successive. Il repository di esempio si trova su GitHub.

Con il modulo Go, l'attivazione dell'osservabilità dei microservizi richiede un modulo di osservabilità e il seguente codice:

import "google.golang.org/grpc/gcp/observability"

func main() {
  ctx, cancel := context.WithTimeout(context.Background(), time.Second)
  defer cancel()
  if err := observability.Start(ctx); err != nil {
    log.Warning("Unable to start gRPC observability:", err)
  }
  defer observability.End()
  …
}

La chiamata observability.Start analizza la configurazione dalle variabili di ambiente, crea gli esportatori di conseguenza e inserisce la logica di raccolta nelle connessioni dei client e nei server creati dopo la chiamata. La chiamataobservability.End differita libera le risorse e garantisce che i dati in buffer vengano svuotati prima della chiusura dell'applicazione.

Dopo aver aggiornato il codice dell'applicazione, esegui il comando seguente per aggiornare il filego.mod.

go mod tidy

Java

Per utilizzare l'osservabilità dei microservizi con le applicazioni Java, modifica la build in modo da includere l'elemento grpc-gcp-observability. Utilizza la versione gRPC 1.54.1 o successiva.

Negli snippet di build nelle sezioni degli strumenti di build Gradle e Maven, grpcVersion è impostato sul valore 1.54.1.

Il repository di esempio si trova su GitHub.

1. Per eseguire correttamente l'instrumentazione delle applicazioni Java per l'osservabilità dei microservizi, aggiungi il seguente codice a main().

...
import io.grpc.gcp.observability.GcpObservability;
...

// Main application class
...

public static void main(String[] args) {
...
  // call GcpObservability.grpcInit() to initialize & get observability
  GcpObservability observability = GcpObservability.grpcInit();

...
  // call close() on the observability instance to shutdown observability
  observability.close();
...
}

Tieni presente che devi chiamare GcpObservability.grpcInit() prima che vengano creati canali o server gRPC. La funzione GcpObservability.grpcInit() legge la configurazione dell'osservabilità dei microservizi e la utilizza per configurare gli intercettatori e i tracer globali necessari per le funzionalità di logging, metriche e traccia in ogni canale e server creato. GcpObservability.grpcInit() è thread-safe e deve essere chiamato esattamente una volta. Restituisce un'istanza di GcpObservability che devi salvare per chiamare close() in un secondo momento.

GcpObservability.close() disalloca le risorse. Tutti i canali o i server creati successivamente non eseguono alcun logging.

GcpObservability implementa java.lang.AutoCloseable, che viene chiuso automaticamente se utilizzi try-with-resource come segue:

...
import io.grpc.gcp.observability.GcpObservability;
...

// Main application class
...

public static void main(String[] args) {
...
  // call GcpObservability.grpcInit() to initialize & get observability
  try (GcpObservability observability = GcpObservability.grpcInit()) {

...
  } // observability.close() called implicitly
...
}

Utilizzare lo strumento di compilazione Gradle

Se utilizzi lo strumento di compilazione Gradle, includi quanto segue:

def grpcVersion = '1.54.1'

...

dependencies {
...
implementation "io.grpc:grpc-gcp-observability:${grpcVersion}"
...
}

Utilizzare lo strumento di compilazione Maven (pom.xml)

Se utilizzi lo strumento di compilazione Maven, includi quanto segue:

<properties>
...
<grpc.version>1.54.1</grpc.version>
...
</properties>

...

<dependencies>
...
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-gcp-observability</artifactId>
<version>${grpc.version}</version>
</dependency>
...
</dependencies>

Esegui l'applicazione

Segui le istruzioni in questa sezione solo se hai utilizzato l'esempio gRPC per il tutorial. Puoi modificare il comando run per scegliere come target il file binario dell'applicazione.

Esegui server

C++

1. Crea una sessione SSH nella VM.

2. Esporta le variabili di ambiente. Utilizza i passaggi definiti sopra per creare server_config.json.

     export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
     export GRPC_GCP_OBSERVABILITY_CONFIG_FILE="$(pwd)/examples/cpp/gcp_observability/helloworld/server_config.json"
   

3. Esegui l'applicazione server shell cd grpc tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_server

Vai

1. Crea una sessione SSH nella VM.

2. Esporta le variabili di ambiente. Utilizza i passaggi definiti sopra per creare server_config.json.

   export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./server/serverConfig.json
   

3. Esegui l'applicazione server shell go run ./server/main.go

Java

1. Nella directory degli esempi, apri il file README e segui le istruzioni al suo interno.
2. Quando le istruzioni ti chiedono di aprire un'altra finestra del terminale, emetti questo comando: shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

Esegui client

C++

1. Crea un'altra sessione SSH nella VM.

2. Esporta le variabili di ambiente. Utilizza i passaggi definiti sopra per creare il file client_config.json.

     export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
     export GRPC_GCP_OBSERVABILITY_CONFIG_FILE="$(pwd)/examples/cpp/gcp_observability/helloworld/client_config.json"
   

3. Esegui l'applicazione client

   cd grpc
   tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_client
   

Vai

1. Crea un'altra sessione SSH nella VM.
2. Esporta le variabili di ambiente. Utilizza i passaggi definiti sopra per creare il file client_config.json. shell export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./client/clientConfig.json

3. Esegui l'applicazione client

   cd grpc-go/examples/features/observability
   go run ./client/main.go
   

Java

1. Nella directory examples, apri il file README e segui le istruzioni al suo interno.
2. Quando le istruzioni ti chiedono di aprire un'altra finestra del terminale, emetti questo comando: shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, quando lo elimini elimini anche tutto il lavoro svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, il riuso dei progetti può aiutarti a non superare i limiti di quota.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Elimina singole risorse

1. Elimina l'istanza:

   gcloud compute instances delete INSTANCE_NAME

Passaggi successivi

• Per informazioni dettagliate sui dati di configurazione, sulle definizioni delle tracce, sulle definizioni delle metriche e sulle definizioni dei log, consulta Documentazione di riferimento sull'osservabilità dei microservizi.
• Per informazioni su come visualizzare log, tracce e metriche, consulta Visualizzare tracce, metriche e voci di log.