Python e OpenTelemetry

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:

    Acessar as configurações da 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:

  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:

O exemplo a seguir ilustra essas instruçõ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 para o Cloud Trace, modifique o aplicativo para ele 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 do período. Por exemplo, o código a seguir adiciona um evento ao período denominado 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, 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:


# 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 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:


import time

from flask import Flask
from opentelemetry import metrics, trace
from opentelemetry.exporter.cloud_monitoring import (
    CloudMonitoringMetricsExporter,
)
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.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import Resource
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 o Flask

Configure o FlaskInstrumentor para instrumentar seu aplicativo. O exemplo 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 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:

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 Trace trace.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