Python e OpenTelemetry

Esta página foi projetada para desenvolvedores de aplicativos que querem coletar dados do Cloud Trace para aplicativos Python usando o OpenTelemetry. O OpenTelemetry é um conjunto de bibliotecas de instrumentação para coletar dados de rastreamento e métrica. Essas bibliotecas funcionam com vários back-ends. Para coletar traces com o OpenTelemetry e o Python, faça o seguinte, conforme descrito nesta página:

  • Instale os pacotes do OpenTelemetry.
  • Configure o aplicativo para exportar períodos para o Cloud Trace.
  • Configure sua plataforma.

Para ver informações sobre a versão, consulte:

Para ver os detalhes mais recentes sobre o OpenTelemetry para Python, além de documentação e exemplos adicionais, consulte OpenTelemetry.

Antes de começar

  • Use o Python 3.6 ou posterior.
  • Verifique se a API Cloud Trace está ativada no seu projeto do Google Cloud:

    1. Clique no botão a seguir ou, no Console do Google Cloud, selecione APIs e serviços e, em seguida, selecione API Cloud Trace:

      Acessar a API do Trace

    2. Na página API Cloud Trace, se um botão Ativar for exibido, clique nele. Se esse botão não for exibido, significa que a API Cloud Trace está ativada para o projeto selecionado.

Instalar os pacotes do OpenTelemetry

Para instalar os pacotes OpenTelemetry necessários, faça o seguinte:

  1. (Opcional) Faça upgrade para a versão mais recente do pip:

    pip install --upgrade pip
    
  2. 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
  • Um processador de período de exportação:

    • Para enviar períodos com um processo em segundo plano, use o processador BatchSpanProcessor. Recomendamos que você use esse processador, a menos que esteja usando o Cloud Run. O Cloud Run não é compatível com processos em segundo plano.

    • Para enviar períodos com um processo em primeiro plano, use o processador SimpleSpanProcessor. Se você estiver usando o Cloud Run, use esse processador. Esse processador pode atrasar o aplicativo.

  • (Opcional) Se você quiser vincular períodos, importe a classe Link.

O exemplo a seguir ilustra essas declarações de importação:


from opentelemetry import trace
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.trace import Link

Configurar a exportação de períodos para o Cloud Trace

Para enviar períodos ao Cloud Trace, modifique o aplicativo para usar o exportador CloudTraceSpanExporter. O exemplo a seguir ilustra as etapas necessárias:


tracer_provider = TracerProvider()
cloud_trace_exporter = CloudTraceSpanExporter()
tracer_provider.add_span_processor(
    # BatchSpanProcessor buffers spans and sends them in batches in a
    # background thread. The default parameters are sensible, but can be
    # tweaked to optimize your performance
    BatchSpanProcessor(cloud_trace_exporter)
)
trace.set_tracer_provider(tracer_provider)

tracer = trace.get_tracer(__name__)

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:


with tracer.start_span("foo_with_attribute") as current_span:
    do_work()

    # Add attributes to the spans of various types
    current_span.set_attribute("string_attribute", "str")
    current_span.set_attribute("bool_attribute", False)
    current_span.set_attribute("int_attribute", 3)
    current_span.set_attribute("float_attribute", 3.14)

Adicionar eventos a um período

Para adicionar um evento a um período, chame o método add_event dele. Por exemplo, o código a seguir adiciona um evento ao período chamado foo_with_event:


# Adding events to spans
with tracer.start_as_current_span("foo_with_event") as current_span:
    do_work()
    current_span.add_event(name="event_name")

Para vincular dois períodos juntos, importe a classe Link e use o campo links no start_as_current_span{101 }. Ao vincular dois períodos, você pode incluir atributos no campo links.

O código a seguir ilustra duas maneiras diferentes de vincular um período ao intervalo chamado link_target:


# Adding links to spans
with tracer.start_as_current_span("link_target") as link_target:
    # Using start_as_current_span() instead of start_span() will make spans
    # created within this scope children of foo_with_attribute

    # Creates a span "span_with_link" and a link from
    # "span_with_link" -> "link_target"
    with tracer.start_as_current_span(
        "span_with_link", links=[Link(link_target.context)]
    ):
        do_work()

    # Creates a span "span_with_link" and a link from
    # "span_with_link" -> "link_target". This link also has the attribute
    # {"link_attr": "string"}
    with tracer.start_as_current_span(
        "span_with_link_and_link_attributes",
        links=[Link(link_target.context, attributes={"link_attr": "string"})],
    ):
        do_work()

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 não é preciso adicionar instrumentação específica às rotas para as solicitações:

  • O Flask usa o propagador configurado para extrair o contexto do período das solicitações HTTP recebidas.
  • O Flask cria automaticamente períodos com atributos que descrevem a solicitação e a resposta.

Para um exemplo completo usando 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 que estão 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 pela biblioteca requests.

Importação e configuração

Para usar a instrumentação Flask do OpenTelemetry, você precisa importar o FlaskInstrumentor.

Para garantir que os períodos criados por produtos diferentes do Google Cloud estejam associados ao mesmo trace, você precisa configurar 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.

A amostra a seguir ilustra as declarações necessárias de importação e configuração, bem como a configuração do propagador do Cloud Trace:


import time

from flask import Flask
from opentelemetry import trace
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.propagate import set_global_textmap
from opentelemetry.propagators.cloud_trace_propagator import (
    CloudTraceFormatPropagator,
)
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

set_global_textmap(CloudTraceFormatPropagator())

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 Flask

Configure o FlaskInstrumentor para instrumentar seu aplicativo. A amostra a seguir ilustra como realizar essa etapa:


app = Flask(__name__)
FlaskInstrumentor().instrument_app(app)

@app.route("/")
def hello_world():
    # You can still use the OpenTelemetry API as usual to create custom spans
    # within your trace
    with tracer.start_as_current_span("do_work"):
        time.sleep(0.1)

    return "Hello, World!"

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 compatíveis do Google Cloud, 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ê usa escopos de acesso personalizados, verifique se o escopo de acesso da API Cloud Trace está ativado:

  • Para mais informações sobre como configurar os escopos de acesso do ambiente usando o Console do Google Cloud, consulte Como configurar seu projeto do Google Cloud.

  • Para usuários gcloud, especifique os escopos de acesso usando a sinalização --scopes e inclua o escopo de acesso trace.append da API Cloud Trace. 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. Forneça essas credenciais definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS:

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"

Como visualizar os traces

Após a implantação, é possível ver os traces no Visualizador de traces do Console do Cloud.

Acesse a página do visualizador do Trace

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