Configurar a observabilidade de microsserviços

Este documento contém as informações necessárias para configurar o plug-in de observabilidade de microsserviços, instrumentar os aplicativos gRPC e receber informações do Cloud Monitoring, Cloud Logging e Cloud Trace.

Antes de começar

A observabilidade de microsserviços funciona com qualquer implantação que tenha permissão para acessar o Cloud Monitoring, o Cloud Logging e o Cloud Trace ativando a API Microservices. Neste guia, fornecemos um exemplo de configuração da observabilidade de microsserviços usando um exemplo do Compute Engine.

Em geral, você faz o seguinte:

1. Como desenvolvedor de serviços, você ativa e controla o plug-in de observabilidade de microsserviços.
2. Como operador de serviços, você consome os dados coletados de várias maneiras.

Os repositórios gRPC (C++, Go e Java) incluem exemplos para demonstrar a observabilidade de microsserviços.

Antes de configurar a observabilidade, conclua as seguintes tarefas:

1. Leia a Visão geral da observabilidade de microsserviços.
2. Verifique se você tem um projeto existente ou crie um novo.
3. Verifique se você tem uma conta de serviço atual ou crie uma.
4. Leia sobre as duas variáveis de ambiente compatíveis, decida qual delas usar e determine os valores exigidos pela variável de ambiente.
5. Ativar a API Microservices.

Escolher uma variável de ambiente de configuração

Ao ativar o plug-in de observabilidade de microsserviços, descrito em Instrumentar os aplicativos para o plug-in de observabilidade, você precisa fornecer a configuração usando uma variável de ambiente. Por padrão, nenhum recurso de observabilidade está ativado. Defina a variável de ambiente na VM ou no contêiner em que o aplicativo gRPC ou a carga de trabalho está em execução:

Veja a seguir as variáveis de ambiente:

• GRPC_GCP_OBSERVABILITY_CONFIG_FILE: o valor é um caminho que aponta para um arquivo de configuração codificado em JSON.
• GRPC_GCP_OBSERVABILITY_CONFIG: o valor é o corpo da configuração codificada em JSON.

Se ambas as variáveis de ambiente forem definidas, GRPC_GCP_OBSERVABILITY_CONFIG_FILE terá prioridade sobre GRPC_GCP_OBSERVABILITY_CONFIG.

Para aplicar a configuração, reinicie o aplicativo gRPC. Não é possível definir ou visualizar os valores das variáveis de ambiente no Console do Google Cloud.

Na configuração, é possível definir um projeto de destino para o upload de dados de geração de registros, rastreamento e métricas. Defina o ID do projeto no campo project_id.

• Se esse campo for deixado em branco, o plug-in de observabilidade preencherá automaticamente o valor do ID do projeto com base nas credenciais padrão do aplicativo.

• Se as credenciais padrão do aplicativo não puderem ser identificadas e o campo project_id estiver vazio, o método INIT/START exibirá ou retornará um erro ao aplicativo. O aplicativo precisa processar o erro.

Use as informações em Dados de configuração para definir os valores na variável de ambiente escolhida.

Ativar a API Microservices

É possível usar a Google Cloud CLI ou o console para ativar a API Microservices nos seus projetos. A ativação da API Microservice ativa automaticamente as APIs Cloud Logging, Cloud Monitoring e Cloud Trace.

Para ativar a API:

gcloud services enable microservices.googleapis.com

Definir permissões da conta de serviço

Se você estiver usando uma conta de serviço não padrão, conceda as permissões necessárias para a conta de serviço. Defina os seguintes valores:

• PROJECT_ID: Substitua seu código do projeto:
• SERVICE_ACCOUNT_NAME: substitua o nome da conta de serviço do seu projeto.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/logging.logWriter

gcloud projects add-iam-policy-binding PROJECT_ID> \
  --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.metricWriter

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/cloudtrace.agent

Instrumentar os aplicativos para o plug-in de observabilidade

Para instrumentar seus aplicativos para que eles possam usar o plug-in de observabilidade de microsserviços, use as seguintes instruções para C++, Java e Go.

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.

Mudanças no build

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

Alterações de código necessárias

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

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.

Mudanças necessárias no código Java

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

Ativar a coleta de dados de geração de registros, tracing e métricas

As seções a seguir contêm instruções para ativar a coleta de dados na configuração e um exemplo que mostra 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

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 ativar o rastreamento, faça o seguinte:

1. Adicione o objeto cloud_trace à configuração.
2. Defina a cloud_trace.sampling_rate como a probabilidade que você quer que seu aplicativo observe para iniciar novos traces.
   • Por exemplo, 1.0 significa rastrear cada RPC.
   • 0.0 significa que novos traces não serão iniciados.
   • 0.5 significa que 50% das RPCs são rastreadas aleatoriamente.

Se uma decisão positiva de amostragem for tomada de forma upstream, os períodos de upload dos serviços serão realizados independentemente da configuração da taxa de amostragem.

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.

Exemplo de variável de ambiente

O exemplo a seguir define as variáveis de observabilidade na variável de ambiente GRPC_GCP_OBSERVABILITY_CONFIG:

export GRPC_GCP_OBSERVABILITY_CONFIG='{
     "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": 1.00
     },
     "labels": {
         "SOURCE_VERSION": "J2e1Cf",
         "SERVICE_NAME": "payment-service-1Cf",
         "DATA_CENTER": "us-west1-a"
     }
}'

Criar o exemplo de observabilidade

Use estas instruções para criar e se conectar a uma instância de VM do Compute Engine e configure o exemplo de observabilidade.

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
   

Continue com as instruções para Java, C++ ou Go, dependendo da linguagem dos aplicativos gRPC.

Visualizar traces, métricas e entradas de registro

Use as instruções desta seção para visualizar traces, métricas e entradas de registro.

Ver traces no Cloud Trace

Depois de configurar os exemplos ou instrumentar suas cargas de trabalho, você verá os traces gerados pelos clientes e servidores gRPC no console do Google Cloud listados como recentes.

Ver registros de traces

Se você ativar a geração de registros e o rastreamento, poderá visualizar as entradas de registro dos traces junto ao gráfico de cascata do Cloud Trace ou no Explorador de registros.

Ver métricas no painel

A observabilidade de microsserviços fornece um painel de monitoramento chamado Monitoramento de microsserviços (gRPC) para as métricas definidas em Definições de métricas. O painel é exibido no Console do Google Cloud somente quando a API Microservices está ativada. O console do Google Cloud chama a API Service Usage para verificar se a API Microservices está ativada em um projeto. O usuário precisa ter a permissão serviceusage.services.list para visualizar o painel.

O painel Monitoramento de microsserviços (gRPC) é um painel do Google Cloud, e não é possível modificá-lo diretamente. Para personalizar o painel, copie-o para um painel personalizado. Em seguida, é possível atualizar o painel personalizado, por exemplo, adicionando, excluindo ou reorganizando os gráficos.

Ver métricas no Metrics Explorer

Depois de configurar o exemplo do gRPC ou instrumentar sua carga de trabalho, você verá as métricas geradas pelos clientes e servidores gRPC no console do Google Cloud.

Para visualizar e gerar gráficos de métricas, siga as instruções em Selecionar métricas ao usar o Metrics Explorer

Inspecionar entradas de registro no Explorador de registros

A consulta sugerida é um recurso do Cloud Logging em que o Google Cloud sugere um conjunto de consultas com base nos registros ingeridos. É possível clicar e usar os filtros preparados:

Depois que as entradas de registro correspondentes às consultas sugeridas aparecerem no Cloud Logging, você verá novas consultas sugeridas em aproximadamente 6 minutos. Na maioria dos casos, você vê novas consultas sugeridas mais cedo. Se há entradas de registro que correspondem a uma sugestão nos 15 minutos anteriores, todas as consultas sugeridas continuam sendo exibidas. Elas continuam aparecendo como uma sugestão até que não haja nenhuma entrada de registro correspondente nos 15 minutos anteriores.

É possível criar consultas personalizadas. Consulte o Guia da linguagem de consulta do Logging para ver instruções. Por exemplo, no painel "Consulta" da Análise de registros, é possível tentar mostrar todos os registros de depuração do gRPC com o seguinte código:

log_id("microservices.googleapis.com/observability/grpc")

É possível usar todos os campos no registro de logs do gRPC para filtragem. Veja a seguir um exemplo de entrada de registro:

{
  "insertId": "17kh8vafzuruci",
  "jsonPayload": {
    "authority": "10.84.1.15:50051",
    "sequenceId": "6",
    "serviceName": "helloworld.Greeter",
    "peer": {
      "ipPort": 50051,
      "address": "10.84.1.10",
      "type": "IPV4"
    },
    "callId": "d9577780-c608-4bff-9e12-4d9cdea6b298",
    "type": "SERVER_TRAILER",
    "methodName": "SayHello",
    "payload": {},
    "logger": "CLIENT"
  },
  "resource": {
    "type": "k8s_container",
    "labels": {
      "pod_name": "grpc-client-deployment-155-6967959544-x8ndr",
      "container_name": "grpc-client-container-155",
      "cluster_name": "o11y-cluster",
      "namespace_name": "grpc-client-namespace-155",
      "location": "us-west1-b",
      "project_id": "grpc-greeter"
    }
  },
  "timestamp": "2023-04-05T23:33:41.718523Z",
  "severity": "DEBUG",
  "labels": {
    "environment": "example-client"
  },
  "logName": "projects/grpc-greeter/logs/microservices.googleapis.com%2Fobservability%2Fgrpc",
  "receiveTimestamp": "2023-04-05T23:33:42.712682457Z"
}

Consultas sugeridas

A observabilidade de microsserviços fornece as seguintes consultas sugeridas para o Cloud Logging:

Registros de cabeçalho ou trailer para gRPCs

Esta consulta fornece uma visão básica das RPCs, gerando informações de peering e resultados da RPC.

log_id("microservices.googleapis.com/observability/grpc") AND
jsonPayload.type=("CLIENT_HEADER" OR "SERVER_TRAILER")

Chamadas gRPC com falha

Esta consulta encontra as RPCs que terminam com status não OK.

log_id("microservices.googleapis.com/observability/grpc") AND
jsonPayload.type="SERVER_TRAILER" AND
jsonPayload.payload.statusCode!="OK"

Registros de registros para gRPCs cancelados ou excedidos

O excesso de cancelamento de gRPC ou excedentes de prazo podem fornecer informações úteis sobre a perda de desempenho ou o comportamento imprevisível do aplicativo.

log_id("microservices.googleapis.com/observability/grpc") AND
((jsonPayload.type="SERVER_TRAILER" AND jsonPayload.payload.statusCode=("CANCELLED" OR "DEADLINE_EXCEEDED")) OR (jsonPayload.type="CANCEL"))

Usar registros e rastreamento para solucionar problemas

Se você vir um evento de RPC que indica comportamento inadequado, poderá encontrar o callid no evento. Use a consulta a seguir para exibir todos os eventos que ocorreram em uma RPC, independentemente de ser uma RPC unária ou de streaming. A entrada de registro anterior é usada como exemplo:

log_id("microservices.googleapis.com/observability/grpc")
jsonPayload.callid="a358c7b80-3548-4bc8-a33f-b93ba1514904"

Para determinar o escopo do problema, encontre todos os eventos de RPC para o mesmo método ou local. A consulta a seguir mostra todos os registros de depuração relacionados a um método de RPC específico, usando o serviço Greeter como exemplo:

log_id("microservices.googleapis.com/observability/grpc")
jsonPayload.serviceName="helloworld.Greeter"
jsonPayload.methodName="SayHello"

Para verificar as RPCs com falha de um código de status específico, adicione o código de status como uma das condições de filtragem. A consulta a seguir mostra os eventos de trailer que terminam com um status não OK:

log_id("microservices.googleapis.com/observability/grpc")
jsonPayload.payload.statusCode!="OK"

Opções de observabilidade

A observabilidade de microsserviços inclui os recursos opcionais a seguir.

Definir rótulos personalizados

É possível definir rótulos personalizados, que adicionam informações fornecidas pelo usuário aos dados de observação. Os rótulos personalizados consistem em pares de chave-valor. Cada par de chave-valor é anexado aos dados de rastreamento como rótulos de período, aos dados de métricas como tags de métricas e aos dados de registro como rótulos de entrada de registro.

Os rótulos personalizados são definidos na configuração com uma lista de pares de chave-valor no campo labels. Todas as chaves e valores de rótulos personalizados são do tipo STRING. A implementação lê a configuração e cria um identificador separado para cada par de chave-valor e, em seguida, anexa os rótulos aos dados de observabilidade.

Por exemplo, esta é uma definição de rótulo:

"labels": {
    "DATACENTER": "SAN_JOSE_DC",
    "APP_ID": "24512"
  }

Cada entrada de registro tem os seguintes rótulos adicionais:

{
   "DATACENTER" : "SAN_JOSE_DC"
   "APP_ID" : "24512"
}

Ativar a geração de registros de payload

Ative a geração de registros de payload usando as variáveis de ambiente que você fornece para a carga de trabalho. Para ativar a geração de registros de payload para mensagens e cabeçalhos HelloWorld, atualize o valor dos arquivos de configuração gcp_observability_server_config.json, gcp_observability_client_config.json ou ambos nos exemplos gRPC da seguinte maneira:

{
   "cloud_monitoring":{
   },
   "cloud_trace":{
      "sampling_rate":1.0
   },
   "cloud_logging":{
      "client_rpc_events":[
         {
            "methods":[
               "helloworld.Greeter/*"
            ],
            "max_metadata_bytes":4096,
            "max_message_bytes":4096
         }
      ],
      "server_rpc_events":[
         {
            "methods":[
               "helloworld.Greeter/*"
            ],
            "max_metadata_bytes":4096,
            "max_message_bytes":4096
         }
      ]
   }
}

Configurar a observabilidade entre projetos

É possível definir o projeto de destino explicitamente usando a configuração definida na variável de ambiente GRPC_GCP_OBSERVABILITY_CONFIG. Para observabilidade entre projetos, você também precisa definir as permissões da conta de serviço apropriadas. Supondo que o ID do projeto de destino seja core-platform-stats, é possível configurar a observabilidade de projetos cruzados usando a seguinte configuração de exemplo:

{
   "project_id":"core-platform-stats",
   "cloud_monitoring":{
   },
   "cloud_trace":{
      "sampling_rate":1.0
   },
   "cloud_logging":{
      "client_rpc_events":[
         {
            "methods":[
               "helloworld.Greeter/*"
            ]
         }
      ],
      "server_rpc_events":[
         {
            "methods":[
               "helloworld.Greeter/*"
            ]
         }
      ]
   }
}

Volume de registros de estimativa

Nesta seção, apresentamos informações que podem ser usadas para estimar opcionalmente o volume de ingestão de registros. É possível fazer uma estimativa antes de se inscrever nos eventos de RPC dos serviços.

Tamanho total da fórmula de estimativa de ingestão de registros por mês:

Monthly Log Ingestion = QPS * 6 * (500B + Payload Logging Size + Custom Labels Size) * 2592000

Por exemplo, se o QPS de um método de chamada unária for 1 e nenhum recurso extra estiver ativado, o tamanho estimado da ingestão de registros será de aproximadamente 7,24 GiB.

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.