Exemplo de instrumentação em Python

É possível instrumentar um aplicativo Python para coletar dados de trace e métrica com o SDK do OpenTelemetry e um coletor do OpenTelemetry e gravar registros JSON correlacionados e estruturados na saída padrão. Para testar essa instrumentação, faça o download e execute o aplicativo de amostra do Flask, que gera dados de registro, métrica e trace e os exporta para o projeto do Google Cloud .

Sobre a abordagem de instrumentação

Ao usar um coletor do OpenTelemetry, você instrumenta seu aplicativo com o SDK e o exportador em processo OTLP do SDK. Essa instrumentação é independente de fornecedor. Você também implanta um coletor do OpenTelemetry que recebe telemetria do exportador em processo e, em seguida, exporta essa telemetria para o projeto do Google Cloud . Para saber mais sobre coletores, consulte Coletor do OpenTelemetry criado pelo Google.

Recomendamos que você use um coletor do OpenTelemetry para exportar seus dados de telemetria quando o ambiente for compatível com o uso de um coletor. Em alguns ambientes, é necessário usar um exportador em processo que envie dados diretamente para o projeto doGoogle Cloud . Para saber mais sobre a instrumentação em processo, consulte Migrar do exportador do Trace para o endpoint do OTLP.

Para saber mais sobre instrumentação, consulte os seguintes documentos:

Sobre a instrumentação manual e sem código

Para essa linguagem, o OpenTelemetry define a instrumentação sem código como a prática de coletar telemetria de bibliotecas e frameworks sem fazer alterações no código. No entanto, você precisa instalar módulos e definir variáveis de ambiente.

Este documento não descreve a instrumentação sem código. Para mais informações sobre esse tópico, consulte Instrumentação sem código do Python.

Para informações gerais, consulte Instrumentação do OpenTelemetry para Python.

Antes de começar

  1. Instale a CLI do Google Cloud.

  2. Configure a CLI gcloud para usar sua identidade federada.

    Para mais informações, consulte Fazer login na CLI gcloud com sua identidade federada.

  3. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  4. Crie ou selecione um projeto do Google Cloud .

    Papéis necessários para selecionar ou criar um projeto

    • Selecionar um projeto: para selecionar um projeto, não é necessário ter um papel do IAM específico. É possível selecionar qualquer projeto em que você tenha um papel.
    • Criar um projeto: para criar um projeto, é preciso ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

    • Crie um projeto do Google Cloud :

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por um nome para o projeto do Google Cloud que você está criando.

    • Selecione o projeto do Google Cloud que você criou:

      gcloud config set project PROJECT_ID

      Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

  5. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  6. Ative as APIs Cloud Logging, Cloud Monitoring, Cloud Trace e Telemetry, se ainda não estiverem ativadas:

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis. 

    gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

  7. Para receber as permissões necessárias para que o aplicativo de amostra grave dados de registro, métrica e trace, peça ao administrador para conceder a você os seguintes papéis do IAM:

    Essas permissões são suficientes se você executar o exemplo no Cloud Shell, em recursos do Google Cloud ou em um ambiente de desenvolvimento local. Para saber como configurar um projeto de cota, consulte Definir o projeto de cota.

    Para ter as permissões necessárias para visualizar os dados de registro, métrica e trace, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

    Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

    Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Instrumentar o app para coletar traces, métricas e registros

Para instrumentar o app para coletar dados de trace e métrica e gravar registros JSON estruturados na saída padrão, siga estas etapas:

  1. Configurar o OpenTelemetry
  2. Configurar a geração de registros estruturados

Configurar o OpenTelemetry

Este app de exemplo está configurado para usar o SDK do Python do OpenTelemetry para exportar rastros e métricas usando o protocolo OTLP. Por padrão, o SDK do Python do OpenTelemetry usa o formato Contexto de Trace do W3C para propagar o contexto de trace, garantindo que os períodos tenham a relação pai-filho correta em um trace.

O exemplo de código a seguir ilustra um módulo Python para configurar o OpenTelemetry. Para ver o exemplo completo, selecione o logotipo do GitHub na barra de ferramentas do exemplo.

def setup_opentelemetry() -> None:
    resource = Resource.create(
        attributes={
            # Use the PID as the service.instance.id to avoid duplicate timeseries
            # from different Gunicorn worker processes.
            SERVICE_INSTANCE_ID: f"worker-{os.getpid()}",
        }
    )
    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))
    logs.set_logger_provider(logger_provider)

    reader = PeriodicExportingMetricReader(OTLPMetricExporter())
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

O app Flask depende do Gunicorn para exibir solicitações HTTP seguindo as recomendações no guia Como implantar na produção do Flask. O Gunicorn inicia várias cópias do app em execução em processos de worker independentes. para aumentar a capacidade de processamento. Para garantir que as métricas dos processos do worker não entrem em conflito entre si, recomendamos que cada processo de worker defina um valor único do atributo de recurso service.instance.id. Uma maneira de fazer isso é incluir o ID de processo no service.instance.id. Para mais informações, consulte Colisões de séries temporais.

Para mais informações e opções de configuração, consulte Instrumentação de Python. da OpenTelemetry.

Configurar a geração de registros estruturados

Para gravar registros estruturados vinculados a traces, configure o app para a saída de registros formatados em JSON para saída padrão com chaves que contêm informações de trace. O exemplo de código a seguir ilustra como configurar a biblioteca padrão logging para gerar registros estruturados JSON usando a biblioteca python-json-logger e como usar o pacote opentelemetry-instrumentation-logging para incluir informações de trace.

class JsonFormatter(jsonlogger.JsonFormatter):
    def formatTime(self, record: logging.LogRecord, datefmt: Optional[str] = None):
        # Format the timestamp as RFC 3339 with microsecond precision
        isoformat = datetime.fromtimestamp(record.created).isoformat()
        return f"{isoformat}Z"


def setup_structured_logging() -> None:
    LoggingInstrumentor().instrument()

    log_handler = logging.StreamHandler()
    formatter = JsonFormatter(
        "%(asctime)s %(levelname)s %(message)s %(otelTraceID)s %(otelSpanID)s %(otelTraceSampled)s",
        rename_fields={
            "levelname": "severity",
            "asctime": "timestamp",
            "otelTraceID": "logging.googleapis.com/trace",
            "otelSpanID": "logging.googleapis.com/spanId",
            "otelTraceSampled": "logging.googleapis.com/trace_sampled",
        },
    )
    log_handler.setFormatter(formatter)
    logging.basicConfig(
        level=logging.INFO,
        handlers=[log_handler],
    )

A configuração anterior extrai informações sobre o período ativo da mensagem de registro e, em seguida, adiciona essas informações como atributos ao registro estruturado JSON. Esses atributos podem ser usados para correlacionar um registro com um trace:

  • logging.googleapis.com/trace: nome do recurso do trace associado à entrada de registro.
  • logging.googleapis.com/spanId: o ID do período dentro do trace associado à entrada de registro.
  • logging.googleapis.com/trace_sampled: o valor desse campo precisa ser true ou false.

Para mais informações sobre esses campos, consulte a estrutura LogEntry.

Executar um app de exemplo configurado para coletar telemetria

A instrumentação no app de exemplo usa formatos neutros em relação a fornecedores, como JSON para dados de registro e OTLP para dados de métricas e traces. O app de exemplo também usa o Flask para atender a solicitações HTTP e a biblioteca de solicitações para fazer solicitações HTTP. O Collector do OpenTelemetry envia dados de registro e métricas para seu projeto usando exportadores do Google. Ele envia os dados de trace para o projeto usando a API Telemetry, que usa o OTLP.

Para gerar métricas e traces para o cliente HTTP e servidor, o app de amostra instala as bibliotecas de instrumentação opentelemetry-instrumentation-flask e opentelemetry-instrumentation-requests:

logger = logging.getLogger(__name__)

# Initialize OpenTelemetry Python SDK and structured logging
setup_opentelemetry()
setup_structured_logging()

app = Flask(__name__)

# Add instrumentation
FlaskInstrumentor().instrument_app(app)
RequestsInstrumentor().instrument()

O app tem dois endpoints:

  • O endpoint /multi é processado pela função multi. O gerador de carga no app emite solicitações para o endpoint /multi. Quando esse endpoint recebe uma solicitação, ele envia de três a sete solicitações para o endpoint /single no servidor local.

    @app.route("/multi")
def multi():
    """Handle an http request by making 3-7 http requests to the /single endpoint."""
    sub_requests = randint(3, 7)
    logger.info("handle /multi request", extra={"subRequests": sub_requests})
    for _ in range(sub_requests):
        requests.get(url_for("single", _external=True))
    return "ok"

  • O endpoint /single é processado pela função single. Quando esse endpoint recebe uma solicitação, ele fica suspenso por um pequeno atraso e depois responde com uma string.

    @app.route("/single")
def single():
    """Handle an http request by sleeping for 100-200 ms, and write the number of seconds slept as the response."""
    duration = uniform(0.1, 0.2)
    logger.info("handle /single request", extra={"duration": duration})
    time.sleep(duration)
    return f"slept {duration} seconds"

Fazer o download e implantar o app

Para executar a amostra:

  1. No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  2. Clone o repositório:

    git clone https://github.com/GoogleCloudPlatform/opentelemetry-samples

  3. Acesse o diretório da amostra:

    cd opentelemetry-samples/python/instrumentation-quickstart

  4. Crie e execute a amostra:

    docker compose up --abort-on-container-exit

    Se você não estiver usando o Cloud Shell, execute o aplicativo com a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS apontando para um arquivo de credenciais. O Application Default Credentials fornece um arquivo de credenciais em $HOME/.config/gcloud/application_default_credentials.json.

    # Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"

# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit

Ver suas métricas

A instrumentação do OpenTelemetry no app de amostra gera métricas do Prometheus, que podem ser visualizadas usando o Metrics Explorer:

  • Prometheus/http_server_duration_milliseconds/histogram registra a duração das solicitações do servidor e armazena os resultados em um histograma.

  • Prometheus/http_client_duration_milliseconds/histogram registra a duração das solicitações do cliente e armazena os resultados em um histograma.

Para visualizar as métricas geradas pelo app de exemplo, faça o seguinte:

  1. No console Google Cloud , acesse a página do  Metrics explorer:

    Acesse o Metrics Explorer

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

  2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta habilitada para apps.
  3. No elemento Metric, expanda o menu Selecionar uma métrica, digite http_server na barra de filtro e use os submenus para selecionar um tipo de recurso e métrica específicos:
    1. No menu Active resources, selecione Prometheus Target.
    2. No menu Categorias de métrica ativas, selecione Instância.
    3. No menu Métricas ativas, selecione uma métrica de faturamento†.
    4. Clique em Aplicar.

  4. Para adicionar filtros que removem séries temporais dos resultados da consulta, use o elemento Filtro.

  5. Configure a visualização dos dados.

    Quando as medições de uma métrica são cumulativas, o Metrics Explorer normaliza automaticamente os dados medidos pelo período de alinhamento, o que resulta na exibição de uma taxa no gráfico. Para mais informações, consulte Tipos, tipos e conversões.

    Quando valores inteiros ou duplos são medidos, como acontece com as duas métricas counter, o Metrics Explorer soma automaticamente todas as séries temporais. Para visualizar os dados das rotas HTTP /multi e /single, defina o primeiro menu da entrada Agregação como Nenhum.

    Para mais informações sobre como configurar um gráfico, consulte Selecionar métricas ao usar o Metrics Explorer.

Visualizar os rastros

Pode levar vários minutos até que os dados de trace estejam disponíveis. Por exemplo, quando os dados de trace são recebidos pelo projeto, o Google Cloud Observability pode precisar criar um banco de dados para armazenar esses dados. A criação do banco de dados pode levar alguns minutos e, durante esse período, nenhum dado de trace fica disponível para visualização.

Para visualizar os dados de trace, faça o seguinte:

  1. No console 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.

  2. Na seção de tabela da página, selecione uma linha com o nome de período /multi.

  3. No diagrama de Gantt no painel Detalhes do trace, selecione o período rotulado como /multi.

    Um painel é aberto com informações sobre a solicitação HTTP. Esses detalhes incluem o método, o código de status, o número de bytes e o user agent do autor da chamada.

  4. Para visualizar os registros associados a esse trace, selecione a guia Registros e eventos.

    A guia mostra registros individuais. Para exibir os detalhes da entrada de registro, expanda a entrada de registro. Também é possível clicar em Ver registros e ver o registro usando a Análise de registros.

Para mais informações sobre como usar a página do Trace Explorer, consulte Encontrar e analisar traces.

Veja os registros

Na Análise de registros, é possível inspecionar os registros e visualizar os traces associados, quando eles existirem.

  1. No console do Google Cloud , acesse a página Análise de registros:

    Acessar a Análise de registros

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

  2. Localize um registro com a descrição de handle /multi request.

    Para ver os detalhes da entrada de registro, expanda a entrada de registro.

  3. Clique em Traces em uma entrada de registro com a mensagem "handle /multi request" e selecione View trace details.

    O painel Detalhes do trace é aberto e mostra o trace selecionado.

    Os dados de registro podem estar disponíveis vários minutos antes dos dados de trace. Se você encontrar um erro ao visualizar dados de trace, seja pesquisando um trace por ID ou seguindo as etapas desta tarefa, aguarde um ou dois minutos e tente novamente.

Para mais informações sobre como usar a Análise de registros, consulte Ver registros usando a Análise de registros.

A seguir