Gerar traces e métricas com o Python

Neste documento, descrevemos como modificar um aplicativo Python para coletar dados de trace e métrica usando o framework de código aberto OpenTelemetry e como gravar registros JSON estruturados para saída padrão. Este documento também fornece informações sobre um app Python de amostra que pode ser instalado e executado. O app usa o framework da Web Flask e está configurado para gerar métricas, traces e registros.

Sobre a instrumentação manual e automática

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

Este documento não descreve as informações automáticas. Para mais informações sobre esse tópico, consulte Instrumentação automática para Python.

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

Antes de começar

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

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

Para instrumentar o app para coletar dados de rastreamento e métrica e gravar um JSON estruturado para saída padrão, siga as etapas a seguir, conforme descrito nas próximas seções deste documento:

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 modelo do SDK do Python da OpenTelemetry usa o formato Contexto de Rastreamento do W3C para propagar o contexto do 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, clique em Mais e selecione Ver no GitHub.

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()}",
})

traceProvider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(OTLPSpanExporter())
traceProvider.add_span_processor(processor)
trace.set_tracer_provider(traceProvider)

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

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 o ambiente 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.

LoggingInstrumentor().instrument()

logHandler = logging.StreamHandler()
formatter = jsonlogger.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",
        },
    datefmt="%Y-%m-%dT%H:%M:%SZ",
)
logHandler.setFormatter(formatter)
logging.basicConfig(
    level=logging.INFO,
    handlers=[logHandler],
)

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 com o 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

O aplicativo de exemplo usa formatos neutros em relação a fornecedores, incluindo JSON para registros e OTLP para métricas e traces. A telemetria do app é roteada para o Google Cloud usando o Collector do OpenTelemetry configurado com os exportadores do Google. Ela usa o Flask para atender a solicitações HTTP, e a biblioteca de solicitações para fazer solicitações HTTP. 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__)

app = Flask(__name__)
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."""
      subRequests = randint(3, 7)
      logger.info("handle /multi request", extra={'subRequests': subRequests})
      for _ in range(subRequests):
          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)
      time.sleep(duration)
      return f'slept {duration} seconds'

Fazer o download e implantar o app

Observação :recomendamos usar o Cloud Shell para executar o app de exemplo. No entanto, se você quiser executar o app de exemplo localmente no Linux ou Mac, pule a primeira etapa das instruções a seguir.

Para executar a amostra:

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Clone o repositório:

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python
   

3. Acesse o diretório da amostra:

   cd opentelemetry-operations-python/samples/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 do 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 Monitoramento.

2. 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.
3. 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

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

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

2. No gráfico de dispersão, selecione um rastro com o URI de /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 o explorador do Cloud Trace, consulte Encontrar e explorar traces.

Acessar 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 do 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 do registro, expanda a entrada.

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.

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

A seguir

• OpenTelemetry
• Visão geral do OTLP
• Geração de registros estruturados
• Solução de problemas do Managed Service para Prometheus
• Resolver problemas do Cloud Trace