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.

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 as métricas, consulte o artigo Definições das métricas.

Ative o rastreio

Para ativar o rastreio, faça o seguinte:

  1. Adicione o objeto cloud_trace à configuração.
  2. Defina o valor 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óprio) 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