Informações de referência sobre a observabilidade dos microsserviços

Dados de configuração

Os dados de configuração encontrados nas variáveis de ambiente estão definidos na tabela seguinte.

Campos Spec
project_id String

O identificador do projeto para o qual os dados de observabilidade são enviados. Se estiver vazio, o plug-in de observabilidade gRPC tenta obter o ID do projeto das variáveis de ambiente ou das credenciais predefinidas.

Se não for encontrado, as funções de inicialização da observabilidade devolvem um erro.
cloud_logging Objeto

As opções de registo estão categorizadas nesta tabela.
Quando está ausente, o registo está desativado.
cloud_logging.client_rpc_events[] List

Uma lista de configurações client_rpc_events, que representa a configuração para RPCs de saída do ficheiro binário.

As configurações de client_rpc_events são avaliadas pela ordem do texto. É usada a primeira correspondência. Se um RPC não corresponder a uma entrada, continua para a entrada seguinte na lista.
cloud_logging.client_rpc_events[].methods[] List [String]

Uma lista de identificadores de métodos.

Por predefinição, a lista está vazia e não corresponde a nenhum método.

O valor do método está no formato [service]/[method].

* é aceite como caráter universal para:
  • O nome do método. Se o valor for [service]/*, corresponde a todos os métodos no serviço especificado.
  • O valor total do campo que corresponde a qualquer [service]/[method]. Não é suportado quando client_rpc_events[].exclude é verdadeiro.
  • Não é possível usar o caráter universal * no nome do serviço de forma independente. */[method] não é suportado.

O nome do serviço, quando especificado, tem de ser o nome do serviço totalmente qualificado, incluindo o nome do pacote.

Exemplos:
  • goo.Foo/Bar seleciona apenas o método Bar do serviço goo.Foo. Aqui, goo é o nome do pacote.
  • goo.Foo/* seleciona todos os métodos do serviço goo.Foo
  • * seleciona todos os métodos de todos os serviços.
cloud_logging.client_rpc_events[].exclude Bool

Indica se os métodos indicados por client_rpc_events[].methods[] devem ser excluídos do registo.

O valor predefinido é false, o que significa que os métodos indicados por client_rpc_events[].methods[] estão incluídos no registo.

Se o valor for verdadeiro, não é possível usar o caráter universal (*) como o valor completo no elemento client_rpc_events[].methods[].
cloud_logging.client_rpc_events[].max_metadata_bytes Int

Número máximo de bytes de metadados a registar. Se o tamanho dos metadados for superior ao limite definido, os pares de chave-valor que excedam o limite não são registados.

O valor predefinido é 0, o que significa que não são registados metadados.
cloud_logging.client_rpc_events[].max_message_bytes Int

Número máximo de bytes de cada mensagem a registar. Se o tamanho da mensagem for superior ao limite definido, o conteúdo que exceder o limite é truncado.

O valor predefinido é 0, o que significa que não é registado nenhum payload de mensagem.
cloud_logging.server_rpc_events[] Lista

Uma lista de configurações server_rpc_events, representa a configuração para RPCs recebidos no ficheiro binário.

As configurações server_rpc_events são avaliadas pela ordem do texto. É usada a primeira correspondência. Se um RPC não corresponder a uma entrada, continua para a entrada seguinte na lista.
cloud_logging.server_rpc_events[].methods[] List [String]

Uma lista de strings que pode selecionar um grupo de métodos.

Por predefinição, a lista está vazia e não corresponde a nenhum método.

O valor do método está no formato [service]/[method].

* é aceite como caráter universal para:
  • O nome do método. Se o valor for [service]/*, corresponde a todos os métodos no serviço especificado.
  • O valor total do método que corresponde a qualquer [service]/[method]. Não é suportado quando server_rpc_events[].exclude é verdadeiro.
  • Não é possível usar o caráter universal * no nome do serviço de forma independente. */[method] não é suportado.

O nome do serviço, quando especificado, tem de ser o nome do serviço totalmente qualificado, incluindo o nome do pacote.

Exemplos:
  • goo.Foo/Bar seleciona apenas o método Bar do serviço goo.Foo. Aqui, goo é o nome do pacote.
  • goo.Foo/* seleciona todos os métodos do serviço goo.Foo
  • * seleciona todos os métodos de todos os serviços.
cloud_logging.server_rpc_events[].exclude Bool

Indica se os métodos indicados por server_rpc_events[].methods[] devem ser excluídos do registo.

O valor predefinido é false, o que significa que os métodos indicados por server_rpc_events[].methods[] são registados.

Se o valor for verdadeiro, não é possível usar o caráter universal (*) como o valor completo em qualquer entrada de server_rpc_events[].methods[].
cloud_logging.server_rpc_events[].max_metadata_bytes Int

Número máximo de bytes de metadados a registar. Se o tamanho dos metadados for superior ao limite definido, os pares de chave-valor que excedam o limite não são registados.

O valor predefinido é 0, o que significa que não são registados metadados.
cloud_logging.server_rpc_events[].max_message_bytes Int

Número máximo de bytes de cada mensagem a registar. Se o tamanho da mensagem for superior ao limite definido, o conteúdo que passa o limite é truncado.

O valor predefinido é 0, o que significa que não é registado nenhum payload de mensagem.
cloud_monitoring Object

Ativa o Cloud Monitoring. Não existem opções de configuração. Se fornecer uma objeção de configuração vazia, a monitorização é ativada. Se não fornecer um objeto de configuração, a monitorização é desativada.

Por exemplo, quando não são especificadas outras opções, uma secção de configuração vazia ativa a monitorização.
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_monitoring": {
    }
}'
cloud_trace Objeto

Uma secção de configuração vazia permite a monitorização com as opções de configuração predefinidas. Se não fornecer um objeto de configuração, a monitorização é desativada.

Por exemplo, uma secção de configuração vazia permite a monitorização com opções de configuração predefinidas.
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_trace": {
    }
}'


Quando a monitorização está ativada, mesmo com uma taxa de amostragem de "0", a decisão de amostrar um rastreio específico é propagada.
cloud_trace.sampling_rate Número

A definição global que controla a probabilidade de um RPC ser rastreado. Por exemplo:
  • O valor 0.05 significa que existe uma probabilidade de 5% de um RPC ser rastreado.
  • O valor 1.0 significa que todas as chamadas são rastreadas.
  • O valor 0 significa não iniciar novos rastreios.

Por predefinição, a sampling_rate é 0.

O plugin respeita a decisão de amostragem a montante. Se for escolhido um RPC para a amostragem a montante, o plug-in recolhe intervalos e carrega os dados para o back-end, independentemente da definição da taxa de amostragem para o plug-in.
labels Objeto

Um objeto JSON que contém um conjunto de pares de chave-valor. Tanto a chave como o valor são strings.

As etiquetas são aplicadas no Cloud Logging, no Cloud Monitoring e no Cloud Trace em conjunto.

Definições de rastreio

Esta secção fornece informações sobre o rastreio.

Propagação do contexto de rastreio

Para que a monitorização entre serviços funcione, o proprietário do serviço tem de suportar a propagação do contexto de rastreio recebido a montante (ou iniciado por si próprio) a jusante. O contexto de rastreio é propagado entre serviços através de metadados gRPC. Certifique-se de que ativa as APIs Cloud Monitoring, Cloud Logging, Cloud Trace e Microservices, que permitem que os serviços nesta configuração comuniquem os respetivos dados de telemetria ao serviço adequado.

Sem suporte de propagação, os serviços a jusante não podem gerar intervalos para um rastreio. Os intervalos existentes não são afetados. Os plug-ins de observabilidade de microsserviços suportam o formato binário do OpenCensus para codificar e codificar o contexto de rastreio.

Abrangências

O nome de um intervalo está formatado da seguinte forma:

Tipo Valor de exemplo Utilização
Intervalo RPC [Sent|Recv].helloworld.Greeter.SayHello O nome do intervalo é o nome completo do método, ligado por pontos, sem uma barra inicial.
Os nomes dos intervalos têm o prefixo Sent. para o intervalo de RPC do CLIENTE e Recv. para o intervalo de RPC do SERVIDOR antes do nome completo do método.
Intervalo de tentativas Attempt.helloworld.Greeter.SayHello Anexar um prefixo Attempt. antes do nome completo do método.

Etiquetas de intervalo

As integrações fornecem etiquetas de intervalo diferentes.

Para os intervalos de tentativas, são anexados dois atributos adicionais relacionados com novas tentativas (etiquetas de intervalo):

Etiqueta Exemplo de valor Utilização
previous-rpc-attempts 0 O número de tentativas antes deste RPC.
transparent-retry True/False Se este RPC é iniciado por uma nova tentativa transparente.

Definições das métricas

As seguintes métricas estão disponíveis e são apresentadas num painel de controlo denominado Monitorização de microsserviços (gRPC) para percursos comuns do utilizador.

Seguem-se as métricas das métricas do lado do cliente gRPC:

Nome da métrica Descrição Tipo, tipo de elemento, unidade Marcadores
custom.googleapis.com/opencensus/grpc.io/client/started_rpcs A contagem de tentativas de RPCs de clientes iniciadas, incluindo as que não foram concluídas. Cumulativo, Int64, 1 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/completed_rpcs A contagem de RPCs do cliente concluídas, por exemplo, quando uma resposta é recebida ou enviada pelo servidor. Cumulativo, Int64, 1 grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/roundtrip_latency Tempo total necessário para concluir uma tentativa de RPC, incluindo o tempo necessário para selecionar um subcanal. Cumulativo, Distribuição, ms grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/api_latency O tempo total que a biblioteca gRPC demora a concluir um RPC do ponto de vista da aplicação. Cumulativo, Distribuição, ms grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/sent_compressed_message_bytes_per_rpc O total de bytes (comprimidos, não encriptados) enviados em todas as mensagens de pedido por tentativa de RPC. Cumulativo, Distribuição, Por grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/received_compressed_message_bytes_per_rpc O total de bytes (comprimidos, não encriptados) recebidos em todas as mensagens de resposta por tentativa de RPC. Cumulativo, Distribuição, Por grpc_client_method, grpc_client_status

Estão disponíveis as seguintes métricas do lado do servidor gRPC:

Nome da métrica Descrição Tipo, tipo de elemento, unidade Marcadores
custom.googleapis.com/opencensus/grpc.io/server/started_rpcs
A contagem de RPCs recebidos no servidor, incluindo RPCs que não foram concluídos.		 Cumulativo, Int64, 1 grpc_server_method
custom.googleapis.com/opencensus/grpc.io/server/completed_rpcs
A contagem total de RPCs concluídos, por exemplo, quando o servidor envia uma resposta.		 Cumulativo, Int64, 1 grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/sent_compressed_message_bytes_per_rpc
O total de bytes (comprimidos e não encriptados) enviados em todas as mensagens de resposta por RPC.		 Cumulativo, Distribuição, Por grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/received_compressed_message_bytes_per_rpc
O total de bytes (comprimidos e não encriptados) recebidos em todas as mensagens de pedido por RPC.		 Cumulativo, Distribuição, Por grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/server_latency
O tempo total que um RPC demora do ponto de vista do transporte do servidor (HTTP2 / inproc / cronet).		 Cumulativo, Distribuição, ms grpc_server_method

Cada distribuição na tabela acima contém um histograma com intervalos da seguinte forma:

  • Tamanho em bytes: 0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296

  • Latência em ms: 0, 0,01, 0,05, 0,1, 0,3, 0,6, 0,8, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10 000, 20 000, 50 000, 100 000

Descrição da etiqueta:

  • grpc_client_method: nome completo do método gRPC, incluindo o pacote, o serviço e o método. Por exemplo, google.bigtable.v2.Bigtable/CheckAndMutateRow
  • grpc_client_status: código de estado do servidor gRPC recebido, por exemplo, OK, CANCELLED, DEADLINE_EXCEEDED
  • grpc_server_method: nome completo do método gRPC, incluindo o pacote, o serviço e o método, por exemplo, com.exampleapi.v4.BookshelfService/Checkout
  • grpc_server_status: código de estado do servidor gRPC devolvido, por exemplo, OK, CANCELLED, DEADLINE_EXCEEDED

Definições de registos de registos

Os registos de observabilidade dos microsserviços são carregados para o Cloud Logging usando o nome do registo (PROJECT_ID é o marcador de posição para a string que representa o seu projeto):

logName=projects/[PROJECT_ID]/logs/microservices.googleapis.com%2Fobservability%2Fgrpc

Segue-se a representação JSON do registo gerado:

{
    "authority": string,
    "callId": string,
    "type": string,
    "logger": string,
    "serviceName": string,
    "methodName": string,
    "peer": {
        "type": string,
        "address": string,
        "ipPort": int
    },
    "payload": {
        "timeout": string,
        "metadata":
            {
                string: string,
                string: string
            },
        "statusCode": string,
        "statusMessage": string,
        "statusDetails": string,
        "message": string,
        "messageLength": int,
    },
    "sequenceId": int
}

A tabela seguinte descreve os campos na entrada do registo:

Campos Spec
autoridade String

É possível usar um único processo para executar vários servidores virtuais com identidades diferentes.

A autoridade é o nome dessa identidade do servidor. Normalmente, é uma parte do URI sob a forma de anfitrião ou anfitrião:porta.
callId String

Identifica de forma exclusiva uma chamada [cliente/servidor] que é um UUID. Cada chamada pode ter várias entradas de registo. Todos têm o mesmo callId.
escrever String

O tipo do evento de registo.

Os tipos de eventos são:
EVENT_TYPE_UNKNOWN
CLIENT_HEADER
SERVER_HEADER
CLIENT_MESSAGE
SERVER_MESSAGE
CLIENT_HALF_CLOSE
SERVER_TRAILER
CANCEL
registador String

O tipo do registador de eventos.

Os tipos de registador de eventos são:
LOGGER_UNKNOWN, CLIENT, SERVER
serviceName String

O nome do serviço.
methodName String

O nome do método RPC.
par Object

Informações da morada do par. Do lado do cliente, o par é registado em eventos de cabeçalho do servidor e eventos de trailer. Do lado do servidor, o par é sempre registado no evento de cabeçalho do cliente.
peer.type String

O tipo de endereço, quer seja IPv4, IPv6 ou UNIX.
peer.address String

O conteúdo da morada.
peer.ip_port Int

O número da porta para a morada. Apenas disponível para endereços IPv4 e IPv6.
payload Objeto

A carga útil pode incluir uma combinação de metadados, tempo limite, mensagem e estado, consoante o evento.

  • Para eventos de mensagens, o payload são os dados reais transmitidos como mensagens de cliente/servidor e o comprimento da mensagem.
  • Para eventos de cabeçalho, o payload inclui o nome e o valor do cabeçalho.
  • Para eventos de trailer, a carga útil inclui detalhes do estado juntamente com metadados do trailer (se presentes).
  • Para eventos de cabeçalho do cliente, se o limite de tempo estiver definido, a carga útil também inclui o limite de tempo.
payload.timeout String

Uma string que representa google.protobuf.Duration, como "1,2 s".

O valor de limite de tempo da RPC.
payload.metadata Mapping[String, String]

Usado pelo evento de cabeçalho ou pelo evento de trailer.
payload.message String (Bytes)

A carga útil da mensagem.
payload.messageLength Int

Tamanho da mensagem, independentemente de a mensagem completa estar a ser registada (por exemplo, pode ser truncada ou omitida).
payload.statusCode String

O código de estado do gRPC.
payload.statusMessage String

A mensagem de estado do gRPC.
payload.statusDetails String

O valor da chave de metadados grpc-status-details-bin, se existir. Esta é sempre uma mensagem google.rpc.Status codificada.
payloadTruncated Bool

Verdadeiro se o campo de mensagem ou metadados estiver truncado ou omitido devido às opções de configuração.
sequenceId Int

O ID da sequência de mensagens para esta chamada. A primeira mensagem tem um valor de 1 para desambiguar de um valor não definido. O objetivo deste campo é detetar entradas em falta em ambientes onde a durabilidade ou a ordenação não são garantidas.

Etiquetas de recursos

As etiquetas de recursos identificam a origem que gera dados de observabilidade. Cada etiqueta de recurso é um par de chave-valor, em que as chaves são valores predefinidos que são específicos do ambiente de origem (por exemplo, GKE ou Compute Engine).

Para métricas e rastreio em implementações do GKE, as etiquetas de recursos são preenchidas por predefinição, exceto para o nome do contentor e o nome do espaço de nomes. Os valores em falta podem ser preenchidos através da API Downward.

Seguem-se as chaves das variáveis de ambiente:

  • CONTAINER_NAME
  • NAMESPACE

Por exemplo, a secção env no exemplo seguinte inclui duas etiquetas de recursos:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    run: app1
  name: app1
spec:
  replicas: 2
  selector:
    matchLabels:
      run: app1
  template:
    metadata:
      labels:
        run: app1
    spec:
      containers:
        - image: 'o11y-examples:1.00'
          name: container1
          ports:
            - protocol: TCP
              containerPort: 50051
          env:
            - name: CONTAINER_NAME
              value: container1
            - name: NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace

Etiquetas personalizadas

As etiquetas personalizadas representam informações adicionais fornecidas pelos utilizadores nos dados de observabilidade. As etiquetas são constituídas por uma chave e um valor. O par de chave-valor é anexado aos dados de rastreio como etiquetas de intervalo, aos dados de métricas como etiquetas de métricas e aos dados de registo como etiquetas de entrada de registo. Todas as etiquetas personalizadas são do tipo STRING.

Pode fornecer etiquetas personalizadas na configuração especificando uma lista de pares de chave-valor para labels. A implementação lê a configuração e cria uma etiqueta separada para cada par chave-valor. Em seguida, anexa a etiqueta aos dados de observabilidade. Por exemplo:

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

Cada entrada de registo tem as seguintes etiquetas adicionais:

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

O que se segue?