Configurar um aplicativo gRPC em Google Cloud com a observabilidade de microsserviços

---

As ferramentas de observabilidade de microsserviços permitem instrumentar seus aplicativos para coletar e apresentar dados de telemetria no Cloud Monitoring, Cloud Logging e Cloud Trace de cargas de trabalho gRPC implantadas no Google Cloud e em outros lugares. A observabilidade de microsserviços funciona com qualquer implantação que tenha permissão para acessar o Monitoring, o Logging e o Trace ao ativar a API Microservices.

Neste tutorial, você aprenderá a usar os recursos de observabilidade de microsserviços criando um aplicativo gRPC simples no Google Cloud usando o Compute Engine, instrumentando seu aplicativo com a observabilidade de microsserviços e visualizando-os como ativos Monitoring e Logging.

Objetivos

Em geral, você faz o seguinte.

• Como desenvolvedor de serviços, você pode fazer o seguinte:

  • Crie um aplicativo gRPC na linguagem de sua escolha (C++, Go ou Java).
  • Ative seu aplicativo e controle o plug-in de observabilidade de microsserviços.
  • Implante o aplicativo em uma VM do Compute Engine.

• Como operador de serviços, você consome os dados coletados de várias maneiras.

  • Visualize traces no Trace.
  • Confira as métricas no painel de monitoramento chamado de monitoramento de microsserviços (gRPC).
  • Veja métricas no Metrics Explorer.
  • Inspecione entradas de registro na Análise de registros.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

• Compute Engine

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Antes de começar

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. Leia a Visão geral da observabilidade de microsserviços.
11. Leia sobre as duas variáveis de ambiente compatíveis, decida qual delas usar e determine os valores exigidos pela variável de ambiente.

cli

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. Leia a Visão geral da observabilidade de microsserviços.
15. Leia sobre as duas variáveis de ambiente compatíveis, decida qual delas usar e determine os valores exigidos pela variável de ambiente.

Criar e se conectar a uma VM do Compute Engine

Use estas instruções para criar e se conectar a uma instância de VM do Compute Engine. Na VM, você implanta seu aplicativo e o instrumenta com a observabilidade de 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. Conectar-se à instância de VM

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

Implantar o aplicativo na VM do Compute Engine

É possível implantar um aplicativo de sua escolha na VM do Compute Engine criada na etapa anterior e pular esta etapa ou usar um exemplo para continuar com as instruções na linguagem de sua preferência.

C++

1. Depois de se conectar à instância de VM, execute o comando a seguir.

   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
   

Go

1. Verifique se o Go está 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 de 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 se conectar à instância de VM, verifique se o Java 8 ou posterior está 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
   

Criar o arquivo de configuração de observabilidade do gRPC Google Cloud

É necessário um arquivo de configuração de observabilidade do gRPC Google Cloud separado para ativar a observabilidade de microsserviços para o servidor e o cliente. O local desse arquivo será exportado como GRPC_GCP_OBSERVABILITY_CONFIG_FILE nas etapas futuras. Use as instruções a seguir sobre como configurar os diferentes parâmetros no arquivo de configuração.

Exemplo de 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 seções abaixo contêm instruções para ativar a coleta de dados na sua configuração para os componentes individuais. Se você usou o exemplo do gRPC neste tutorial, pode usar essa configuração no estado em que se encontra (após atualizar your-project-here) ou usá-la como um modelo para seu aplicativo e um exemplo mostrando as informações de configuração em uma variável de ambiente.

Ativar métricas

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

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

Ativar rastreamento

Para ativar o rastreamento, 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% das RPCs.

Se você planeja ativar o rastreamento em vários serviços, verifique se eles são compatíveis com a propagação do contexto de rastreamento recebido do upstream (ou iniciado por si só) para o downstream.

Para mais informações sobre rastreamento, consulte Definições de trace.

Ativar a geração de registros

Para ativar a geração de registros, 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 e especifique o conjunto de serviços ou métodos para os quais você quer gerar a geração de registros de eventos no nível de transporte e o número de bytes a serem registrados para cabeçalhos e mensagens.

Para mais informações sobre a geração de registros, consulte Definições de registros.

Instrumentar os aplicativos para o plug-in de observabilidade

Se quiser instrumentar seus aplicativos para que eles possam usar o plug-in de observabilidade de microsserviços, siga as instruções abaixo no seu idioma preferido.

C++

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

1. O suporte à observabilidade só está disponível no sistema de compilação do Bazel. Adicione o destino grpcpp_gcp_observability como uma dependência.

2. Para ativar a observabilidade de microsserviços, é necessária uma dependência adicional (um módulo de observabilidade) e o seguinte código será alterado para os clientes, servidores ou ambos do gRPC:

   #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 qualquer operação gRPC, incluindo a criação de um canal, servidor ou credenciais, invoque o seguinte:

   grpc::GcpObservability::Init();
   

   Isso retorna absl::StatusOr<GcpObservability>, que precisa ser salvo. O status ajuda a determinar se a observabilidade foi inicializada. O objeto GcpObservability que o acompanha controla a vida útil dele. Ele fecha e limpa automaticamente os dados de observabilidade quando eles estão fora do escopo.

Go

1. Os plug-ins de observabilidade de microsserviços são compatíveis com as versões gRPC v1.54.0 e posteriores. O repositório de exemplo está no GitHub.

Com o módulo Go, para ativar a observabilidade de microsserviços, é necessário ter 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 a partir de variáveis de ambiente, cria exportadores adequadamente e injeta lógica de coleta para conexões do cliente e servidores criados após a chamada. A chamada deferida observability.End limpa os recursos e garante que os dados armazenados em buffer sejam transferidos antes do fechamento do aplicativo.

Depois que o código do aplicativo for atualizado, execute o comando abaixo para atualizar o arquivo go.mod.

go mod tidy

Java

Para usar a observabilidade de microsserviços com aplicativos Java, modifique seu build para incluir o artefato grpc-gcp-observability. Use o gRPC versão 1.54.1 ou mais recente.

Nos snippets de build nas seções das ferramentas de build do Gradle e do Maven, grpcVersion é definido como o valor 1.54.1.

O repositório de exemplo está no GitHub.

1. Para instrumentar seus aplicativos Java para a 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();
...
}

Lembre-se de chamar GcpObservability.grpcInit() antes de criar canais ou servidores gRPC. A função GcpObservability.grpcInit() lê a configuração de observabilidade de microsserviços e a usa para definir os interceptadores e rastreadores globais necessários para os recursos de de geração de registros, métricas e traces em cada canal e servidor criado. GcpObservability.grpcInit() é seguro para linhas de execução e precisa ser chamado exatamente uma vez. Ela retorna uma instância de GcpObservability que precisa ser salva para chamar close() mais tarde.

GcpObservability.close() desaloca recursos. Os canais ou servidores criados depois não realizam a geração de registros.

GcpObservability implementa java.lang.AutoCloseable, que é fechado automaticamente se você usa try-with-resources da seguinte maneira:

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

Usar a ferramenta de build do Gradle

Se você estiver usando a ferramenta de build do Gradle, inclua o seguinte:

def grpcVersion = '1.54.1'

...

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

Usar a ferramenta de build do Maven (pom.xml)

Se você estiver usando a ferramenta de build do 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 o aplicativo

Siga as instruções desta seção apenas se tiver usado o exemplo gRPC no tutorial. Modifique o comando run para direcionar ao binário do aplicativo.

Executar servidor

C++

1. Criar uma sessão SSH na VM.

2. Exporte variáveis de ambiente. Use as etapas definidas 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 o aplicativo servidor shell cd grpc tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_server

Go

1. Criar uma sessão SSH na VM.

2. Exporte variáveis de ambiente. Use as etapas definidas acima para criar server_config.json.

   export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./server/serverConfig.json
   

3. Execute o aplicativo servidor shell go run ./server/main.go

Java

1. No diretório de exemplos, abra o arquivo README e siga as instruções.
2. Quando as instruções solicitarem que você 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 as etapas definidas acima para criar o arquivo 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. Executar o aplicativo cliente

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

Go

1. Crie outra sessão SSH na VM.
2. Exporte variáveis de ambiente. Use as etapas definidas acima para criar o arquivo client_config.json. shell export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./client/clientConfig.json

3. Executar o aplicativo cliente

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

Java

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

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Excluir o projeto

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja passar por várias arquiteturas, tutoriais ou guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Excluir recursos individuais

1. Exclua a instância:

   gcloud compute instances delete INSTANCE_NAME

A seguir

• Para saber mais sobre dados de configuração, definições de trace, definições de métricas e definições de registros, consulte a referência de observabilidade de microsserviços.
• Para informações sobre como visualizar registros, traces e métricas, consulte Visualizar traces, métricas e entradas de registro