Esta página é voltada a desenvolvedores de aplicativos que querem coletar dados do Cloud Trace para aplicativos Python usando o OpenTelemetry. O OpenTelemetry é um framework de instrumentação neutro em relação a fornecedores que pode ser usado para coletar dados de rastreamento e métricas. Para mais informações sobre como instrumentar seu código, consulte Instrumentação e observabilidade.
- Instale os pacotes do OpenTelemetry.
- Configure seu aplicativo para exportar períodos para o Cloud Trace.
- Configure sua plataforma.
Para ver informações sobre a versão, consulte:
Para conferir conteúdo de referência do OpenTelemetry, consulte:
Para ver os detalhes mais recentes sobre o OpenTelemetry para Python, além de documentação e exemplos extras, consulte OpenTelemetry.
Antes de começar
- Use o Python 3.6 ou mais recente.
-
No painel de navegação do console do Google Cloud, selecione APIs e serviços, clique em Ativar APIs e serviços e ative a API Cloud Trace:
Se a mensagem API ativada for exibida, quer dizer que a API já está ativada. Caso contrário, clique no botão Ativar.
Instalar os pacotes do OpenTelemetry
Para instalar os pacotes necessários do OpenTelemetry, faça o seguinte:
(Opcional) Faça upgrade para a versão mais recente do
pip
:pip install --upgrade pip
Instale os seguintes pacotes do OpenTelemetry usando
pip
:pip install opentelemetry-api \ opentelemetry-sdk \ opentelemetry-exporter-gcp-trace
Importar pacotes de trace
Atualize seu aplicativo para importar os seguintes pacotes e classes:
trace
CloudTraceSpanExporter
TracerProvider
BatchSpanProcessor
, que é um processador de período de exportação que envia períodos usando um processo em segundo plano.(Opcional) Se você quiser vincular períodos, importe a classe
Link
.
O exemplo a seguir ilustra essas instruções de importação:
Configurar a exportação de períodos para o Cloud Trace
Para enviar períodos para o Cloud Trace, modifique o aplicativo para ele usar
o exportador CloudTraceSpanExporter
. O exemplo a seguir ilustra as
etapas necessárias:
Adicionar atributos a um período
Para adicionar um atributo a um período, chame o método set_attribute
do período.
Por exemplo, o código a seguir adiciona vários atributos ao período
chamado foo_with_attribute
:
Adicionar eventos a um período
Para adicionar um evento a um período, chame o método add_event
do período.
Por exemplo, o código a seguir adiciona um evento ao
período denominado foo_with_event
:
Vincular períodos
Para vincular dois períodos, importe a classe Link
e use o campo links
no método
start_as_current_span
. Ao vincular dois períodos, é possível incluir atributos no campo
links
.
O código a seguir ilustra duas maneiras diferentes de
vincular um período ao período chamado link_target
:
Exemplo de aplicativo Flask
A instrumentação Flask do OpenTelemetry foi projetada para simplificar a captura de conteúdo de rastreamento relacionado a solicitações HTTP. Isso significa que você não precisa adicionar instrumentação específica às rotas para essas solicitações:
- O Flask usa o propagador configurado para extrair o contexto do período das solicitações HTTP recebidas.
- O Flask automaticamente cria períodos com atributos que descrevem a solicitação e a resposta.
Para ver um exemplo completo com Flask e OpenTelemetry, consulte flask_e2e. O README do Git inclui informações sobre como instalar, configurar e executar o exemplo.
Nesta seção, destacamos as etapas de configuração específicas do Flask incluídas
no arquivo server.py
do exemplo. O arquivo cliente, client.py
, usa
a instrumentação Requests
para ativar o rastreamento de solicitações HTTP feitas pelas
solicitações da biblioteca.
Importação e configuração
Para usar a instrumentação Flask do OpenTelemetry, importe o
FlaskInstrumentor
.
Quando você quiser garantir que os períodos criados por diferentes produtos do Google Cloud
estejam associados ao mesmo trace, configure o propagador com o
propagador do Cloud Trace. Esse propagador especifica o uso do
cabeçalho X-Cloud-Trace-Context
. Se você não configurar um propagador, o OpenTelemetry
usará o propagador padrão. Nesse caso, os períodos criados por
diferentes produtos do Google Cloud, como o
Cloud Run e o App Engine, estão em traces separados.
O exemplo a seguir ilustra as instruções de importação e configuração necessárias e a configuração do propagador do Cloud Trace:
Não é necessário adicionar instruções específicas do Flask ao configurar o
exportador CloudTraceSpanExporter
. A configuração mostrada em Configurar a exportação de períodos para o Cloud Trace é suficiente.
Inicializar o Flask
Configure o FlaskInstrumentor
para instrumentar seu aplicativo.
O exemplo a seguir ilustra como realizar essa etapa:
Configurar sua plataforma
Você pode usar o Cloud Trace no Google Cloud e em outras plataformas.
Como executar no Google Cloud
Quando seu aplicativo está em execução no Google Cloud, não é necessário fornecer credenciais de autenticação na forma de uma conta de serviço para a biblioteca de cliente. No entanto, verifique se o escopo de acesso da API Cloud Trace está ativado no Google Cloud Platform.
Para uma lista de ambientes do Google Cloud compatíveis, consulte Suporte ao ambiente.
Para as seguintes configurações, as definições de escopo de acesso padrão ativam a API Cloud Trace:
- Ambiente flexível do App Engine
Ambiente padrão do App Engine
Google Kubernetes Engine (GKE)
Compute Engine
Cloud Run
Se você usar escopos de acesso personalizados, verifique se o escopo de acesso da API Cloud Trace está ativado.
Para informações sobre como configurar os escopos de acesso do ambiente usando o console do Google Cloud, consulte Como configurar o projeto do Google Cloud.
Para usuários do
gcloud
, especifique os escopos de acesso usando a sinalização--scopes
e inclua o escopo de acesso da API Cloud Tracetrace.append
. Por exemplo, para criar um cluster do GKE com apenas a API Cloud Trace ativada, faça o seguinte:gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append
Execução local e em outro lugar
Se o aplicativo estiver em execução fora do Google Cloud, forneça as credenciais de autenticação na forma de uma conta de serviço para a biblioteca de cliente. A conta de serviço precisa conter o papel de agente do Cloud Trace. Para instruções, consulte Como criar uma conta de serviço.
As bibliotecas de cliente do Google Cloud usam o Application Default Credentials (ADC) para encontrar as credenciais do aplicativo.
É possível fornecer essas credenciais de três maneiras:
Executar
gcloud auth application-default login
Coloque a conta de serviço em um caminho padrão para seu sistema operacional. Veja a seguir os caminhos padrão para Windows e Linux:
Windows:
%APPDATA%/gcloud/application_default_credentials.json
Linux:
$HOME/.config/gcloud/application_default_credentials.json
Defina a variável de ambiente
GOOGLE_APPLICATION_CREDENTIALS
como o caminho para sua conta de serviço:
Linux/macOS
export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key
Windows
set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key
PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"
Ver traces
No painel de navegação do console do Google Cloud, selecione Trace e, em seguida, Trace Explorer:
Acessar o Explorador de traces
Solução de problemas
Para informações sobre como solucionar problemas com o Cloud Trace, acesse a página de solução de problemas.
Recursos
- https://opentelemetry.io/
- Repositório OpenTelemetry/opentelemetry-python do GitHub
- Repositório Google Cloud opentelemetry-operations-python do GitHub.