Esta página descreve como ativar os rastros do lado do cliente com o OpenTelemetry ao usar as bibliotecas de cliente do Cloud Storage para interagir com o Cloud Storage. É possível coletar e visualizar dados de rastreamento usando as seguintes bibliotecas de cliente do Cloud Storage com suporte:
Visão geral
Ativar os rastros nas bibliotecas de cliente do Cloud Storage permite monitorar o desempenho, identificar problemas de latência e realizar a depuração rapidamente para solicitações do Cloud Storage. Os rastros mostram a sequência de uma solicitação concluída, fornecendo uma visão detalhada de como a solicitação foi recebida, gerenciada e respondida pelo Cloud Storage. Um único rastro é composto por vários intervalos, que são registros detalhados e com carimbo de data/hora de cada função ou operação que o aplicativo realizou durante a solicitação do Cloud Storage.
Vantagens
A coleta e a propagação de dados de trace oferecem os seguintes benefícios ao aplicativo:
Visibilidade de desempenho aprimorada: como os dados de rastreamento são gerados quase em tempo real à medida que o Cloud Storage conclui cada solicitação, é possível identificar rapidamente gargalos no desempenho e detectar problemas de latência.
Gerenciamento de erros: é possível identificar onde os problemas surgem, agilizando a análise da causa raiz e reduzindo o tempo de inatividade usando as informações sobre cada solicitação do Cloud Storage fornecida em um rastreamento.
Como os rastros do cliente funcionam
As seções a seguir explicam em detalhes como a coleta de rastros funciona.
Como a coleta de rastros funciona com o OpenTelemetry
As bibliotecas de cliente do Cloud Storage oferecem suporte à coleta de dados de trace usando o SDK do OpenTelemetry para configurar os seguintes componentes necessários para coletar e propagar dados de trace:
Provedor de rastreamento: usado pelas bibliotecas de cliente do Cloud Storage, o provedor de rastreamento é responsável por criar e gerenciar o sistema de rastreamento, incluindo a geração e o gerenciamento de rastros e períodos no aplicativo.
Exportador de trace: usado pelo SDK do OpenTelemetry, o exportador de trace é responsável por enviar dados de trace para uma plataforma de observabilidade de back-end, como o Cloud Trace, em que é possível analisar e visualizar dados de trace. Para saber mais sobre o exportador de rastreamento, consulte Como os exportadores de rastreamento funcionam.
Como os exportadores de rastreamento funcionam
A configuração de rastros usando o SDK do OpenTelemetry inclui a seleção de um back-end de observabilidade para exportar seus dados para onde eles são analisados, armazenados e visualizados. Embora seja possível exportar os dados de rastreamento para qualquer back-end de observabilidade, recomendamos usar o Cloud Trace, que pode ser acessado pelo console do Google Cloud e oferece integração com outros Google Cloud serviços.
Depois que o provedor e o exportador de rastreamento forem configurados e ativados, você poderá conferir os dados de rastreamento quase em tempo real, já que os rastreamentos e os períodos são gerados para cada solicitação do Cloud Storage.
Usando o explorador do Cloud Trace no console do Google Cloud, é possível conferir cada rastro, que contém o seguinte:
Visualização de alto nível de uma solicitação do Cloud Storage
Vários intervalos, cada um capturando uma única operação com carimbo de data/hora na solicitação do Cloud Storage que foi realizada.
Para saber mais sobre rastros e intervalos, consulte a documentação do OpenTelemetry sobre rastros e intervalos.
Preços
Os dados de rastreamento são sujeitos a cobrança. As cobranças são baseadas no número de períodos de trace ingeridos e verificados pelo Cloud Trace. Para saber mais sobre os intervalos de rastreamento cobráveis e exemplos de preços, consulte Custos do Cloud Trace.
Antes de começar
Antes de coletar rastros para o uso da API Cloud Storage, você precisa concluir as etapas a seguir:
-
Enable the Cloud Trace API.
Ative a API Cloud Storage.
Funções exigidas
Para receber a permissão necessária para gravar rastros no Cloud Trace,
peça ao administrador para conceder a você o papel do IAM de
Agente do Cloud Trace (roles/coudtrace.agent
) no projeto usado pelo cliente.
Esse papel predefinido contém a
permissão cloudtrace.traces.patch
,
que é necessária para
gravar rastros no Cloud Trace.
Essas permissões também podem ser concedidas com papéis predefinidos ou papéis personalizados para conceder permissões específicas. Para instruções sobre como conceder papéis em projetos, consulte Conceder ou revogar um papel. Para mais informações sobre o papel do agente do Cloud Trace, consulte a documentação do Identity and Access Management (IAM).
Configurar o rastreamento para seu app
Use as instruções a seguir para configurar o rastreamento e começar a coletar dados de rastreamento usando a biblioteca de cliente do Cloud Storage:
Java
Instale as seguintes versões da biblioteca de cliente Java do Cloud Storage:
com.google.cloud:google-cloud-storage:2.47.0
ou posteriorcom.google.cloud:libraries-bom:26.53.0
ou posterior
Instale o exportador do Cloud Trace para o OpenTelemetry. Você também pode usar qualquer exportador de sua preferência.
Instale o propagador do Cloud Trace.
Crie uma instância do cliente do Cloud Storage com os rastros do OpenTelemetry ativados.
Python
Instale a biblioteca de cliente do Python do Cloud Storage:
pip install google-cloud-storage[tracing]>=2.18.0
Instale o exportador e o propagador do Cloud Trace. Você também pode usar qualquer exportador de sua preferência.
pip install opentelemetry-exporter-gcp-trace opentelemetry-propagator-gcp
Instale a instrumentação de solicitações do OpenTelemetry para rastrear as solicitações HTTP subjacentes.
pip install opentelemetry-instrumentation-requests
Defina a variável de ambiente para ativar seletivamente o rastreamento do cliente de armazenamento Python:
export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True
Configure o exportador e o provedor de trace.
Visualizar os rastros
Use o explorador do Cloud Trace para conferir os dados de rastreamento no console do Google Cloud:
-
No console do Google Cloud, acesse a página Explorador de traces:
Acessar o Explorador de traces
Também é possível encontrar essa página usando a barra de pesquisa.
Na página Trace Explorer, clique em um trace específico no gráfico de dispersão para conferir os detalhes dele.
O painel Detalhes do trace mostra uma tabela de períodos de trace.
Opcional: clique em uma linha de período para conferir informações detalhadas sobre um período específico, como as seguintes:
Atributos: pares de chave-valor que fornecem informações adicionais sobre a extensão.
Registros e eventos: entradas de registro associadas ao período.
Stack traces: stack traces associados ao período.
Metadados e links: links para outros Google Cloud serviços associados à extensão.
Para mais informações sobre como usar o explorador do Cloud Trace, consulte Encontrar e explorar traces.