Configure uma aplicação gRPC em Google Cloud com observabilidade de microsserviços

---

As ferramentas de observabilidade de microsserviços permitem-lhe instrumentar as suas aplicações para recolher e apresentar dados de telemetria no Cloud Monitoring, Cloud Logging e Cloud Trace a partir de cargas de trabalho gRPC implementadas no Google Cloud e noutros locais. A observabilidade dos microsserviços funciona com qualquer implementação à qual tenha sido concedida autorização para aceder ao Monitoring, ao Logging e ao Trace ativando a API Microservices.

Neste tutorial, vai aprender a usar as funcionalidades de observabilidade de microsserviços criando uma aplicação gRPC simples no Google Cloud usando o Compute Engine e a instrumentar a sua aplicação com a observabilidade de microsserviços, e a vê-los aparecer em direto no Monitoring e Logging.

Objetivos

A um nível elevado, faz o seguinte.

• Enquanto programador de serviços, pode:

  • Crie uma aplicação gRPC com o idioma à sua escolha (C++, Go ou Java).
  • Ative a sua aplicação e controle o plug-in de observabilidade de microsserviços.
  • Implemente a aplicação numa VM do Compute Engine.

• Enquanto operador de serviços, consome os dados recolhidos de várias formas:

  • Veja rastreios no Rastreio.
  • Veja métricas no painel de controlo de monitorização denominado Monitorização de microsserviços (gRPC).
  • Veja métricas no Explorador de métricas.
  • Inspecione as entradas do registo no Explorador de registos.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• Compute Engine

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

Consola

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.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, and Microservices API APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Create a service account:

1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator). Learn how to grant roles.

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

   Go to Create service account
3. Select your project.

4. 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.

5. Click Create and continue.

6. 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.
7. Click Continue.

8. 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.

9. Click Done to finish creating the service account.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, and Microservices API APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Create a service account:

1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator). Learn how to grant roles.

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

   Go to Create service account
3. Select your project.

4. 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.

5. Click Create and continue.

6. 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.
7. Click Continue.

8. 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.

9. Click Done to finish creating the service account.

1. Leia a vista geral da observabilidade dos microsserviços.
2. Leia acerca das duas variáveis de ambiente suportadas, decida qual usar e determine os valores exigidos pela variável de ambiente.

cli

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.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, and Microservices API APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Create a service account:

1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator). Learn how to grant roles.

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

   Go to Create service account
3. Select your project.

4. 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.

5. Click Create and continue.

6. Grant the following roles to the service account: roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.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.
7. Click Continue.

8. 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.

9. Click Done to finish creating the service account.

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Compute Engine, and Microservices API APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Create a service account:

1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator). Learn how to grant roles.

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

   Go to Create service account
3. Select your project.

4. 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.

5. Click Create and continue.

6. Grant the following roles to the service account: roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.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.
7. Click Continue.

8. 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.

9. Click Done to finish creating the service account.

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

1. Leia a vista geral da observabilidade dos microsserviços.
2. Leia acerca das duas variáveis de ambiente suportadas, decida qual usar e determine os valores exigidos pela variável de ambiente.

Crie e ligue-se a uma VM do Compute Engine

Use estas instruções para criar e estabelecer ligação a uma instância de VM do Compute Engine. Na VM, implementa a sua aplicação e, em seguida, instrumenta a aplicação com a observabilidade dos microsserviços.

1. Crie uma instância de 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. Estabeleça ligação à instância de VM:

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

Implemente a sua aplicação na VM do Compute Engine

Pode implementar uma aplicação à sua escolha na VM do Compute Engine que criou no passo anterior e, em seguida, ignorar este passo, ou pode usar um exemplo para continuar com as instruções no seu idioma preferencial.

C++

1. Depois de se ligar à instância de VM, execute o seguinte 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
   

Ir

1. Certifique-se de que tem o Go instalado.

   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. Clone os exemplos gRPC-Go.

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

Java

1. Depois de estabelecer ligação à instância de VM, certifique-se de que tem o Java 8 ou posterior instalado.

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

2. Clone o repositório grpc-java.

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

Crie um ficheiro de configuração de observabilidade gRPC Google Cloud

Precisa de um ficheiro de configuração de observabilidade gRPC separado para ativar a observabilidade de microsserviços para o servidor e o cliente. Google Cloud A localização deste ficheiro é exportada como GRPC_GCP_OBSERVABILITY_CONFIG_FILE nos passos futuros. Use a seguinte instrução sobre como configurar os diferentes parâmetros no ficheiro de configuração.

Exemplo 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"
  }
}

As secções seguintes contêm instruções para ativar a recolha de dados na sua configuração para os componentes individuais. Se usou o exemplo de gRPC neste tutorial, pode usar esta configuração tal como está (depois de atualizar your-project-here) ou usá-la como um modelo para a sua aplicação.

Ative as métricas

Para ativar as métricas, adicione o objeto cloud_monitoring à configuração e defina o respetivo valor como {}.

Para mais informações sobre métricas, consulte o artigo Definições de métricas.

Ative o rastreio

Para ativar o rastreio, faça o seguinte:

1. Adicione o objeto cloud_trace à configuração.
2. Defina cloud_trace.sampling_rate como 0.5, que rastreia aleatoriamente 50% dos RPCs.

Se planeia ativar o rastreio entre serviços, certifique-se de que os serviços suportam a propagação do contexto de rastreio recebido a montante (ou iniciado por si próprios) para a jusante.

Para mais informações sobre o rastreio, consulte o artigo Definições de rastreio.

Ative o registo

Para ativar o registo, faça o seguinte:

1. Adicione o objeto cloud_logging à configuração.
2. Adicione um padrão a client_rpc_events ou server_rpc_events, ou a ambos, especificando o conjunto de serviços ou métodos para os quais quer gerar o registo de eventos ao nível do transporte e o número de bytes a registar para cabeçalhos e mensagens.

Para mais informações sobre o registo, consulte o artigo Definições de registos.

Capacite as suas aplicações com instrumentos para o plug-in de observabilidade

Para instrumentar as suas aplicações de modo a que possam usar o plug-in de observabilidade de microsserviços, use as seguintes instruções para o seu idioma preferido.

C++

Pode usar C++ com a observabilidade de microsserviços a partir do gRPC C++ v1.54. O repositório de exemplo está no GitHub.

1. O apoio técnico de observabilidade só está disponível através do sistema de compilação do Bazel. Adicione o alvo grpcpp_gcp_observability como uma dependência.

2. A ativação da observabilidade dos microsserviços requer uma dependência adicional (um módulo de observabilidade) e as seguintes alterações de código aos clientes, servidores ou ambos os gRPC existentes:

   #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
   }
   

   Antes de quaisquer operações gRPC, incluindo a criação de um canal, um servidor ou credenciais, invoque o seguinte:

   grpc::GcpObservability::Init();
   

   Isto devolve absl::StatusOr<GcpObservability>, que deve ser guardado. O estado ajuda a determinar se a observabilidade foi inicializada com êxito. O objeto GcpObservability associado controla a duração total da observabilidade e fecha e limpa automaticamente os dados de observabilidade quando sai do âmbito.

Ir

1. Os plug-ins de observabilidade de microsserviços são suportados para versões do gRPC Go v1.54.0 e posteriores. O repositório de exemplo está no GitHub.

Com o módulo Go, a aceitação da observabilidade dos microsserviços requer um módulo de observabilidade e o seguinte código:

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()
  …
}

A chamada observability.Start analisa a configuração das variáveis de ambiente, cria exportadores em conformidade e injeta lógica de recolha nas ligações de clientes e nos servidores criados após a chamada. A chamada adiadaobservability.End limpa os recursos e garante que os dados em buffer são descarregados antes de a aplicação ser fechada.

Depois de atualizar o código da aplicação, execute o seguinte comando para atualizar o ficheiro go.mod.

go mod tidy

Java

Para usar a observabilidade de microsserviços com aplicações Java, modifique a compilação para incluir o artefacto grpc-gcp-observability. Use a versão 1.54.1 ou posterior do gRPC.

Nas secções de criação de fragmentos nas ferramentas de criação do Gradle e Maven, o valor de grpcVersion é 1.54.1.

O repositório de exemplo está no GitHub.

1. Para instrumentar com êxito as suas aplicações Java para observabilidade de microsserviços, adicione o seguinte código 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();
...
}

Tenha em atenção que tem de chamar GcpObservability.grpcInit() antes de serem criados canais gRPC ou servidores. A função GcpObservability.grpcInit() lê a configuração de observabilidade dos microsserviços e usa-a para configurar os interceptores e os rastreadores globais necessários para as funcionalidades de registo, métricas e rastreio em cada canal e servidor criado. GcpObservability.grpcInit() é thread-safe e tem de ser chamado exatamente uma vez. Devolve uma instância de GcpObservability que tem de guardar para chamar close() mais tarde.

GcpObservability.close() anula a atribuição de recursos. Os canais ou os servidores criados posteriormente não registam nada.

GcpObservability implementa java.lang.AutoCloseable, que é fechado automaticamente se usar try-with-resources da seguinte forma:

...
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
...
}

Use a ferramenta de compilação do Gradle

Se estiver a usar a ferramenta de compilação Gradle, inclua o seguinte:

def grpcVersion = '1.54.1'

...

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

Use a ferramenta de compilação Maven (pom.xml)

Se estiver a usar a ferramenta de compilação Maven, inclua o seguinte:

<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>

Execute a sua aplicação

Siga as instruções nesta secção apenas se tiver usado o exemplo gRPC para o tutorial. Pode modificar o comando run para segmentar o ficheiro binário da sua aplicação.

Executar servidor

C++

1. Crie uma sessão de SSH na VM.

2. Exporte variáveis de ambiente. Use os passos definidos acima para criar 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. Execute a aplicação de servidor shell cd grpc tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_server

Ir

1. Crie uma sessão de SSH na VM.

2. Exporte variáveis de ambiente. Use os passos definidos acima para criar server_config.json.

   export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./server/serverConfig.json
   

3. Execute a aplicação de servidor shell go run ./server/main.go

Java

1. No diretório de exemplos, abra o ficheiro README e siga as instruções no ficheiro.
2. Quando as instruções lhe indicarem que abra outra janela de terminal, emita este comando: shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

Executar cliente

C++

1. Crie outra sessão SSH na VM.

2. Exporte variáveis de ambiente. Use os passos definidos acima para criar o ficheiro 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. Execute a aplicação cliente

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

Ir

1. Crie outra sessão SSH na VM.
2. Exporte variáveis de ambiente. Use os passos definidos acima para criar o ficheiro client_config.json. shell export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./client/clientConfig.json

3. Execute a aplicação cliente

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

Java

1. No diretório de exemplos, abra o ficheiro README e siga as instruções no ficheiro.
2. Quando as instruções indicarem que deve abrir outra janela de terminal, emita este comando: shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

Elimine o projeto

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Elimine recursos individuais

1. In the Google Cloud console, go to the VM instances page.

   Go to VM instances

2. Select the checkbox for the instance that you want to delete.
3. To delete the instance, click More actions, click Delete, and then follow the instructions.

O que se segue?

• Para obter informações detalhadas sobre dados de configuração, definições de rastreio, definições de métricas e definições de registos, consulte a Referência de observabilidade de microsserviços.
• Para ver informações sobre como ver registos, rastreios e métricas, consulte o artigo Veja rastreios, métricas e entradas de registo