O rastreamento do OpenTelemetry permite identificar e rastrear a latência de várias operações da biblioteca de cliente do Pub/Sub, como agrupamento em lote, gerenciamento de concessão e controle de fluxo. A coleta dessas informações pode ajudar a depurar problemas da biblioteca de cliente.
Alguns casos de uso possíveis para o rastreamento do OpenTelemetry incluem:
- Seu serviço está com uma latência de publicação maior do que o normal.
- Você está enfrentando um grande número de reenvios de mensagens.
- Uma mudança na função de callback do cliente inscrito faz com que o processamento demore mais do que o normal.
Antes de começar
Antes de configurar o OpenTelemetry, conclua as seguintes tarefas:
- Configure o Pub/Sub usando uma das bibliotecas de cliente.
- Instale o SDK do OpenTelemetry e configure um exportador de rastreamento e um provedor de rastreador.
- Ative a API Cloud Trace.
- Saiba como ler rastreamentos do Cloud Observability.
Funções exigidas
Para garantir que a conta de serviço tenha as permissões necessárias para exportar rastreamentos para o Cloud Trace, peça ao administrador para conceder à conta de serviço os seguintes papéis do IAM no seu projeto:
-
Todos:
Agente do Cloud Trace (
roles/cloudtrace.agent
)
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Esses papéis predefinidos contêm as permissões necessárias para exportar rastreamentos para o Cloud Trace. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As seguintes permissões são necessárias para exportar traces para o Cloud Trace:
-
Todos:
cloudtrace.traces.patch
O administrador também pode conceder essas permissões à conta de serviço com papéis personalizados ou outros papéis predefinidos.
Fluxo de trabalho de rastreamento do OpenTelemetry
Para configurar o rastreamento do OpenTelemetry, use as bibliotecas de cliente do Pub/Sub e o SDK do OpenTelemetry. Com o SDK, é necessário configurar um exportador de rastreamento e um provedor de rastreador antes de se conectar às bibliotecas do Pub/Sub. Em algumas bibliotecas, configurar um provedor de rastreador é opcional.
Exportador de rastreamento. O SDK do OpenTelemetry usa o exportador de rastreamento para determinar para onde enviar os rastreamentos.
Provedor de rastreador. As bibliotecas de cliente do Pub/Sub usam o provedor de rastreador para criar rastreamentos.
Confira nas etapas a seguir como configurar o rastreamento:
- Instancie um exportador do OpenTelemetry do Cloud Trace.
- Se necessário, crie uma instância e registre um provedor de rastreador usando o SDK do OpenTelemetery.
- Configure seu cliente com a opção "Ativar rastreamento do OpenTelemetry".
- Use as bibliotecas de cliente do Pub/Sub para publicar uma mensagem.
Como o rastreamento funciona
Para cada mensagem publicada, a biblioteca de cliente cria um novo rastreamento. Esse rastreamento representa todo o ciclo de vida da mensagem, desde o momento em que você publica uma mensagem até o momento em que ela é confirmada. Um trace encapsula informações como a duração das operações, períodos pai e filho e períodos vinculados.
Um rastreamento é composto por um período raiz e os períodos filhos correspondentes. Esses intervalos representam o trabalho que a biblioteca de cliente faz ao processar uma mensagem. Cada rastreamento de mensagem contém o seguinte:
- Para publicação. Controle de fluxo, programação de chaves de ordenação, agrupamento em lotes e o comprimento da RPC de publicação.
- Para assinaturas. Controle de simultaneidade, programação de chaves de ordenação e gerenciamento de concessões.
Para propagar informações do lado de publicação para o de inscrição, as
bibliotecas de cliente injetam um atributo específico de rastreamento no lado de
publicação. O mecanismo de propagação de contexto só é ativado quando o rastreamento está ativado e tem o prefixo googclient_
.
Publicar mensagens com rastreamento
O exemplo de código a seguir mostra como ativar o rastreamento usando a biblioteca de cliente do Pub/Sub e o SDK do OpenTelemetry. Neste exemplo, os resultados do rastreamento são exportados para o Cloud Trace.
Considerações
Ao instanciar o provedor de rastreador, você configura uma proporção de amostragem com o SDK do OpenTelemetry. Essa proporção determina quantas rastreamentos o SDK deve coletar. Uma taxa de amostragem menor pode ajudar a reduzir os custos de faturamento e evitar que seu serviço exceda a cota de intervalos do Cloud Trace.
Go
C++
Python
Antes de tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.
TypeScript
Node.js
Java
Receber mensagens com rastreamento
Go
C++
Python
TypeScript
Node.js
Java
Analisar um rastreamento
As seções a seguir contêm informações detalhadas sobre como rastrear e analisar um rastreamento no console do Google Cloud .
Considerações
- Ao publicar um lote de mensagens, o intervalo de RPC de publicação é capturado em um rastreamento separado.
- Uma RPC de publicação tem vários intervalos de origem, já que várias chamadas de criação podem resultar em uma RPC de publicação quando são agrupadas.
Os períodos no OpenTelemetry podem ter zero ou um período pai.
Intervalos que representam operações em lote, como um lote de publicação (que logicamente deve ter vários principais), não podem ser representados usando zero ou um intervalo principal.
Rastrear intervalos criados durante o ciclo de vida da mensagem
A imagem a seguir mostra um exemplo de intervalos criados em um único rastreamento para uma única mensagem.
Cada período pode ter atributos extras que fornecem mais informações, como tamanho do byte da mensagem e informações da chave de ordenação.
Os atributos de extensão transmitem outros metadados, como a chave de ordenação, o ID e o tamanho da mensagem.
Os principais intervalos de publicação e inscrição são aumentados com eventos de intervalo que correspondem ao momento em que uma chamada de rede é emitida e quando ela é concluída.
Resolver problemas comuns
Os problemas a seguir podem causar problemas com o rastreamento:
- A conta de serviço usada para exportar rastreamentos não tem
o papel
roles/cloudtrace.agent
necessário. - A cota do número máximo de períodos ingeridos no Cloud Trace foi atingida.
- O aplicativo é encerrado sem chamar a função de limpeza adequada.