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

As ferramentas de observabilidade de microsserviços oferecem a capacidade de instrumentar seus aplicativos para coletar e apresentar dados de telemetria no Cloud Monitoring, Cloud Logging e Cloud Trace de cargas de trabalho gRPC implantadas em 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ê vai aprender a usar os recursos de observabilidade de microsserviços criando um aplicativo gRPC simples no Google Cloud com o Compute Engine, instrumentando seu aplicativo com a observabilidade de microsserviços e visualizando-os como ativos no Monitoring e no Logging.

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