O rastreio do OpenTelemetry permite-lhe identificar e rastrear a latência de várias operações da biblioteca de cliente do Pub/Sub, como o processamento em lote, a gestão de concessões e o controlo de fluxo. A recolha destas informações pode ajudar a depurar problemas da biblioteca de cliente.
Seguem-se alguns exemplos de utilização potenciais da monitorização de rastreios do OpenTelemetry:
- O seu serviço está a registar uma latência de publicação superior ao normal.
- Está a receber um número elevado de reenvios de mensagens.
- Uma alteração à função de chamada de retorno do cliente subscritor faz com que o processamento demore mais tempo do que o habitual.
Antes de começar
Antes de configurar o OpenTelemetry, conclua as seguintes tarefas:
- Configure o Pub/Sub através de uma das bibliotecas de cliente.
- Instale o SDK OpenTelemetry e configure um exportador de rastreio e um fornecedor de rastreador.
- Ative a API Cloud Trace.
- Compreenda como ler rastreios do Cloud Observability.
Funções necessárias
Para garantir que a conta de serviço tem as autorizações necessárias para exportar rastreios para o Cloud Trace, peça ao seu administrador para conceder à conta de serviço as seguintes funções do IAM no seu projeto:
-
Tudo:
Agente do Cloud Trace (
roles/cloudtrace.agent)
Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.
Estas funções predefinidas contêm as autorizações necessárias para exportar rastreios para o Cloud Trace. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:
Autorizações necessárias
São necessárias as seguintes autorizações para exportar rastreios para o Cloud Trace:
-
Tudo:
cloudtrace.traces.patch
O administrador também pode atribuir estas autorizações à conta de serviço com funções personalizadas ou outras funções predefinidas.
Fluxo de trabalho de rastreio do OpenTelemetry
Para configurar a monitorização de rastreios do OpenTelemetry, usa as bibliotecas de cliente do Pub/Sub e o SDK do OpenTelemetry. Com o SDK, tem de configurar um exportador de rastreio e um fornecedor de rastreador antes de estabelecer ligação às bibliotecas do Pub/Sub. Em algumas bibliotecas, a configuração de um fornecedor de rastreio é opcional.
Rastreie o exportador. O SDK OpenTelemetry usa o exportador de rastreios para determinar para onde enviar os rastreios.
Fornecedor de rastreio. As bibliotecas cliente do Pub/Sub usam o fornecedor de rastreios para criar rastreios.
Os passos seguintes descrevem como configurar o rastreio:
- Instancie um exportador do OpenTelemetry do Cloud Trace.
- Se necessário, instancie e registe um Tracer Provider através do SDK OpenTelemetry.
- Configure o cliente com a opção de ativação da monitorização OpenTelemetry.
- Use as bibliotecas cliente do Pub/Sub para publicar uma mensagem.
Como funciona o rastreio
Para cada mensagem publicada, a biblioteca de cliente cria um novo rastreio. Este rastreio representa todo o ciclo de vida da mensagem, desde o momento em que publica uma mensagem até ao momento em que a mensagem é reconhecida. Um rastreio encapsula informações, como a duração das operações, os intervalos principais e os intervalos secundários, bem como os intervalos associados.
Um rastreio é composto por um intervalo de raiz e os respetivos intervalos secundários. Estes intervalos representam o trabalho que a biblioteca de cliente faz ao processar uma mensagem. Cada rastreio de mensagens contém o seguinte:
- Para publicação. Controlo de fluxo, agendamento de chaves de ordenação, processamento em lote e a duração da RPC de publicação.
- Para subscrições. Controlo de simultaneidade, agendamento de chaves de ordenação e gestão de concessões.
Para propagar informações do lado da publicação para o lado da subscrição, as bibliotecas de cliente injetam um atributo específico de rastreio no lado da publicação. O mecanismo de propagação de contexto só é ativado quando o rastreio está ativado e tem o prefixo googclient_.
Publique mensagens com rastreio
O exemplo de código seguinte mostra como ativar o rastreio através da biblioteca cliente do Pub/Sub e do SDK OpenTelemetry. Neste exemplo, os resultados da monitorização são exportados para o Cloud Trace.
Considerações
Quando instancia o fornecedor de rastreadores, configura uma taxa de amostragem com o SDK do OpenTelemetry. Esta proporção determina quantas rastreios o SDK deve amostrar. Uma taxa de amostragem mais baixa pode ajudar a reduzir os custos de faturação e impedir que o seu serviço exceda a quota de intervalos do Cloud Trace.
Ir
C++
Python
Antes de experimentar este exemplo, siga as instruções de configuração do Python em Início rápido: usar bibliotecas cliente. Para mais informações, consulte a documentação de referência da API Python Pub/Sub.
TypeScript
Node.js
Java
Receba mensagens com rastreio
Ir
C++
Python
TypeScript
Node.js
Java
Analise um rastreio
As secções seguintes contêm informações detalhadas sobre como acompanhar e analisar um rastreio na Cloud de Confiance consola.
Considerações
- Quando publica um lote de mensagens, o intervalo de RPC de publicação é capturado num rastreio separado.
- Um RPC de publicação tem vários intervalos de origem, uma vez que várias chamadas de criação podem resultar num RPC de publicação quando são processadas em lote.
Os intervalos no OpenTelemetry podem ter zero ou um intervalo principal.
Os 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 com zero ou um intervalo principal.
Monitorize os intervalos criados durante o ciclo de vida da mensagem
A imagem seguinte mostra um exemplo de intervalos criados numa única rastreabilidade para uma única mensagem.

Cada intervalo pode ter atributos adicionais. Os atributos de intervalo transmitem metadados adicionais, como a chave de ordenação da mensagem, o ID da mensagem e o tamanho da mensagem.

Os intervalos principais de publicação e subscrição são aumentados com eventos de intervalo que correspondem ao momento em que é emitida uma chamada de rede e quando é concluída.

Resolva problemas comuns
Os seguintes problemas podem causar problemas com o rastreio:
- A conta de serviço que usa para exportar rastreios não tem a função
roles/cloudtrace.agentnecessária. - A quota do número máximo de intervalos carregados no Cloud Trace foi atingida.
- A sua aplicação é terminada sem chamar a função de descarga adequada.