Informações de referência de observabilidade de microsserviços

Dados de configuração

Os dados de configuração encontrados nas variáveis de ambiente são definidos na tabela a seguir.

Campos Especificações
project_id String

É o identificador do projeto para onde os dados de observabilidade são enviados. Se vazio, o plug-in de observabilidade do gRPC tentará buscar o ID do projeto das variáveis de ambiente ou das credenciais padrão.

Se não for encontrado, as funções init de observabilidade retornarão um erro.
cloud_logging Objeto

As opções de geração de registros são categorizadas nesta tabela.
Quando ausente, a geração de registros é desativada.
cloud_logging.client_rpc_events[] Lista

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

As configurações do client_rpc_events são avaliadas em ordem de texto. A primeira correspondência é usada. Se uma RPC não corresponder a uma entrada, ela continuará para a próxima entrada na lista.
cloud_logging.client_rpc_events[].methods[] Lista [String]

Uma lista de identificadores de método.

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

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

O caractere * é aceito como caractere curinga para:
  • O nome do método. Se o valor for [service]/*, ele corresponderá a todos os métodos no serviço especificado.
  • Todo o valor do campo que corresponde a qualquer [service]/[method]. Não é compatível quando client_rpc_events[].exclude é verdadeiro.
  • Não é possível usar o caractere curinga * no nome do serviço de maneira independente. */[method] não é suportado.

Quando especificado, precisa ser o nome totalmente qualificado do serviço, incluindo o nome do pacote.

Exemplos:
  • goo.Foo/Bar seleciona apenas o método Bar do serviço goo.Foo, em que 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

Se os métodos indicados pelo client_rpc_events[].methods[] precisam ser excluídos da geração de registros.

O valor padrão é falso, o que significa que os métodos indicados pelo client_rpc_events[].methods[] estão incluídos no registro.

Se o valor for verdadeiro, o caractere curinga (*) não poderá ser usado como todo o valor no client_rpc_events[].methods[]..
cloud_logging.client_rpc_events[].max_metadata_bytes Int

Número máximo de bytes de metadados a serem registrados. Se o tamanho dos metadados for maior que o limite definido, os pares de chave-valor além do limite não serão registrados.

O valor padrão é 0, o que significa que nenhum metadado é registrado.
cloud_logging.client_rpc_events[].max_message_bytes Int

Número máximo de bytes de cada mensagem a ser registrada. Se o tamanho da mensagem for maior que o limite definido, o conteúdo que exceder o limite será truncado.

O valor padrão é 0, o que significa que nenhum payload de mensagem é registrado.
cloud_logging.server_rpc_events[] Lista

Uma lista de configurações server_rpc_events, que representa a configuração das RPCs de entrada para o binário.

As configurações do server_rpc_events são avaliadas em ordem de texto. A primeira correspondência é usada. Se uma RPC não corresponder a uma entrada, ela continuará para a próxima

entrada na lista.
cloud_logging.server_rpc_events[].methods[] Lista [String]

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

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

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

O caractere * é aceito como caractere curinga para:
  • O nome do método. Se o valor for [service]/*, ele corresponderá a todos os métodos no serviço especificado.
  • Todo o valor do método que corresponde a qualquer [service]/[method]. Não é compatível quando server_rpc_events[].exclude é verdadeiro.
  • Não é possível usar o caractere curinga * no nome do serviço de maneira independente. */[method] não é suportado.

Quando especificado, precisa ser o nome totalmente qualificado do serviço, incluindo o nome do pacote.

Exemplos:
  • goo.Foo/Bar seleciona apenas o método Bar do serviço goo.Foo, em que 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

Se os métodos indicados pelo server_rpc_events[].methods[] precisam ser excluídos da geração de registros.

O valor padrão é "false", o que significa que os métodos indicados pelo server_rpc_events[].methods[] são registrados.

Se o valor for verdadeiro, o caractere curinga (*) não poderá ser usado como todo o valor em nenhuma entrada de server_rpc_events[].methods[].
cloud_logging.server_rpc_events[].max_metadata_bytes Int

Número máximo de bytes de metadados a serem registrados. Se o tamanho dos metadados for maior que o limite definido, os pares de chave-valor além do limite não serão registrados.

O valor padrão é 0, o que significa que nenhum metadado é registrado.
cloud_logging.server_rpc_events[].max_message_bytes Int

Número máximo de bytes de cada mensagem a ser registrada. Se o tamanho da mensagem for maior que o limite definido, o conteúdo que ultrapassar o limite será truncado.

O valor padrão é 0, o que significa que nenhum payload de mensagem é registrado.
cloud_monitoring Objeto

Ativa o Cloud Monitoring. Não há opções de configuração. Se você fornecer uma objeção de configuração vazia, o monitoramento será ativado. Se você não fornecer um objeto de configuração, o monitoramento será desativado.

Por exemplo, quando nenhuma outra opção é especificada, uma seção de configuração vazia ativa o monitoramento.

export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_monitoring": {
    }
}'
cloud_trace Objeto

Uma seção de configuração vazia ativa o rastreamento com as opções de configuração padrão. Se você não fornecer um objeto de configuração, o rastreamento será desativado.

Por exemplo, uma seção de configuração vazia ativa o rastreamento com opções de configuração padrão.

export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_trace": {
    }
}'


Quando o rastreamento é ativado, mesmo com uma taxa de amostragem `0`, a decisão de usar um trace específico é propagada.
cloud_trace.sampling_rate Número

A configuração global que controla a probabilidade de uma RPC ser rastreada. Por exemplo:
  • O valor 0.05 significa que há 5% de chance de uma RPC ser rastreada.
  • O valor 1.0 significa que todas as chamadas são rastreadas.
  • O valor 0 significa que não são iniciados novos traces.

Por padrão, o sample_rate é 0.

O plug-in respeita a decisão de amostragem upstream. Se uma RPC for escolhida para amostragem upstream, o plug-in coletará períodos e fará o upload dos dados para o back-end, independentemente da configuração da taxa de amostragem do plug-in.
labels Objeto

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

Os rótulos são aplicados juntos no Logging, no Cloud Monitoring e no Cloud Trace.

Definições de traces

Esta seção fornece informações sobre rastreamento.

Propagação do contexto de trace

Para que o rastreamento entre serviços funcione, o proprietário do serviço precisa ser compatível com a propagação do contexto de trace recebido de upstream (ou iniciado sozinho) para o downstream. O contexto de trace é propagado entre os serviços pelos metadados gRPC. Verifique se você ativou as APIs Cloud Monitoring, Cloud Logging, Cloud Trace e Microservices, que permitem que os serviços nessa configuração informem os dados de telemetria ao serviço apropriado.

Sem compatibilidade com a propagação, os serviços downstream não podem gerar períodos para um trace. Os períodos existentes não são afetados. Os plug-ins de observabilidade de microsserviços são compatíveis com o formato binário do OpenCensus para codificação e codificação do contexto de trace.

Períodos

O nome de um período é formatado da seguinte maneira:

Tipo Valor de exemplo Uso
Período da RPC [Sent|Recv].helloworld.Greeter.SayHello O nome do período é o nome completo do método, conectado por pontos, sem barras de prefixo.
Os nomes dos períodos são prefixados com Sent. para o período da RPC do CLIENTE e Recv. para o período da RPC do SERVIDOR na frente do nome completo do método.
Período da tentativa Attempt.helloworld.Greeter.SayHello Anexar um prefixo Attempt. na frente do nome completo do método.

Identificadores de período

As integrações fornecem diferentes identificadores de período.

Para períodos de tentativas, dois atributos adicionais relacionados a novas tentativas (identificadores de período) são anexados:

Rótulo Valor de exemplo Uso
previous-rpc-attempts 0 As novas tentativas são contabilizadas antes desta RPC.
transparent-retry True/False Se esta RPC é iniciada por uma nova tentativa transparente.

Definições de métricas

As métricas a seguir estão disponíveis e são exibidas em um painel chamado Monitoramento de Microsserviços (gRPC) para jornadas comuns do usuário:

Veja a seguir as métricas das métricas do cliente gRPC:

Nome da métrica Descrição Classe, Tipo, Unidade Marcadores
custom.googleapis.com/opencensus/grpc.io/client/started_rpcs A contagem de tentativas de RPCs do cliente iniciadas, incluindo aquelas 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 completo para concluir uma tentativa de RPC, incluindo o tempo necessário para escolher 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 levou para concluir uma RPC do ponto de vista do aplicativo. 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 (compactados, não criptografados) enviados em todas as mensagens de solicitação 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 (compactados, não criptografados) recebidos em todas as mensagens de resposta por tentativa de RPC. Cumulativo, Distribuição, por grpc_client_method, grpc_client_status

As seguintes métricas do servidor gRPC estão disponíveis:

Nome da métrica Descrição Classe, Tipo, Unidade Marcadores
custom.googleapis.com/opencensus/grpc.io/server/started_rpcs
A contagem de RPCs já recebidas no servidor, incluindo RPCs que não foram concluídas.		 Cumulativo, Int64, 1 grpc_server_method
custom.googleapis.com/opencensus/grpc.io/server/completed_rpcs
A contagem total de RPCs concluídas, por exemplo, quando uma resposta é enviada pelo servidor.		 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 (compactados e não criptografados) 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 (compactados e não criptografados) recebidos em todas as mensagens de solicitação por RPC.		 Cumulativo, Distribuição, por grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/server_latency
O tempo total gasto por um RPC na perspectiva do transporte de servidor (HTTP2/inproc/cronet).		 Cumulativo, Distribuição, ms grpc_server_method

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

  • 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, 10000, 20000, 50000, 100000

Descrição da tag

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

Definições de registro

Os registros de observabilidade de microsserviços são enviados ao Cloud Logging usando o nome do registro (PROJECT_ID é o marcador para a string que representa seu projeto):

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

Veja a seguir a representação JSON do registro de log 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 a seguir descreve os campos na entrada de registro:

Campos Especificações
autoridade String

Um único processo pode ser usado para executar vários servidores virtuais com identidades diferentes.

A autoridade é o nome dessa identidade do servidor. Normalmente, ela é uma parte do URI na forma de host ou host:port
callId String

Identifica exclusivamente uma chamada de [client/server] que é um UUID. Cada chamada pode ter várias entradas de registro. Todos têm o mesmo callId.
tipo String

O tipo do evento de registro.

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

O tipo do registrador de eventos.

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

O nome do serviço.
methodName String

O nome do método de RPC.
peering Objeto

Informações de endereço de peering. No lado do cliente, o peering é registrado em eventos de cabeçalho do servidor e eventos de trailer. No lado do servidor, o peering é sempre registrado no evento de cabeçalho do cliente.
peer.type String

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

O conteúdo do endereço.
peer.ip_port Int

O número da porta do endereço. Disponível apenas para endereços IPv4 e IPv6.
payload Objeto

O payload pode incluir uma combinação de metadados, tempo limite, mensagem e status, dependendo do evento.

  • Para eventos de mensagens, o payload são os dados reais transmitidos como mensagens do cliente/servidor e a duração da mensagem.
  • Para eventos de cabeçalho, o payload inclui o nome e o valor do cabeçalho.
  • Para eventos de trailer, o payload inclui detalhes de status junto com os metadados do trailer (se presentes).
  • Para eventos de cabeçalho do cliente, se o tempo limite for definido, o payload também incluirá o tempo limite.
payload.timeout String

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

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

Usado por evento de cabeçalho ou trailer.
payload.message String (bytes)

O payload da mensagem.
payload.messageLength Int

Tamanho da mensagem, não importa se a mensagem completa está sendo registrada (por exemplo, pode estar truncada ou omitida).
payload.statusCode String

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

A mensagem de status do gRPC.
payload.statusDetails String

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

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

O ID da sequência de mensagens desta chamada. A primeira mensagem tem o valor de 1 para diferenciar de um valor não definido. A finalidade desse campo é detectar entradas ausentes em ambientes em que a durabilidade ou a ordem não são garantidas.

Rótulos de recursos

Os rótulos de recurso identificam a fonte que gera dados de observabilidade. Cada tag de local é um par de chave-valor, em que as chaves são valores predefinidos específicos do ambiente de origem (por exemplo, GKE ou Compute Engine).

Para métricas e rastreamento em implantações do GKE, as tags de local são preenchidas por padrão, exceto os nomes do contêiner e do namespace. Preencha os valores ausentes usando a Downward API.

Veja a seguir as chaves de variáveis de ambiente:

  • CONTAINER_NAME
  • NAMESPACE

Por exemplo, a seção env a seguir inclui dois rótulos 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

Rótulos personalizados

Os rótulos personalizados representam outras informações fornecidas pelo usuário nos dados de observabilidade. Os identificadores são compostos por uma chave e um valor. O par de chave-valor é anexado a dados de rastreamento como identificadores de período, a dados de métricas como identificadores de métricas e a dados de registro como identificadores de entrada de registro. Todos os rótulos personalizados são do tipo STRING.

É possível fornecer rótulos personalizados na configuração especificando uma lista de pares de chave-valor para labels. A implementação lê a configuração e cria um identificadores separado para cada par de chave-valor e, em seguida, anexa o rótulo aos dados de observabilidade: Exemplo:

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

Cada entrada de registro tem os seguintes identificadores extras:

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

A seguir