Exemplo de instrumentação Python

Este documento descreve como modificar uma app Python para recolher dados de rastreio e métricas através da framework OpenTelemetry de código aberto e como escrever registos JSON estruturados para saída padrão. Este documento também fornece informações sobre uma app Python de exemplo que pode instalar e executar. A app usa a estrutura Web Flask e está configurada para gerar métricas, rastreios e registos.

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

• Instrumentação e observabilidade.
• Escolha uma abordagem de instrumentação.

Nota: este documento apresenta apenas partes selecionadas de uma aplicação funcional. Por exemplo, o exemplo não apresenta a lista de pacotes importados. No entanto, a aplicação completa está disponível no GitHub. Para ver o exemplo completo, clique em Mais e, de seguida, selecione Ver no GitHub.

Acerca da instrumentação manual e sem código

Para este idioma, o OpenTelemetry define a instrumentação sem código como a prática de recolher telemetria de bibliotecas e frameworks sem fazer alterações ao código. No entanto, pode instalar módulos e definir variáveis de ambiente.

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

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

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro, tem de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

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

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

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro, tem de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

Create or select a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

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

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

Instrumente a sua app para recolher rastreios, métricas e registos

Para instrumentar a sua app de modo a recolher dados de rastreio e métricas, e escrever JSON estruturado para a saída padrão, siga os passos descritos nas secções subsequentes deste documento:

1. Configure o OpenTelemetry
2. Configure o registo estruturado

Configure o OpenTelemetry

Esta app de exemplo está configurada para usar o SDK Python do OpenTelemetry para exportar rastreios e métricas através do protocolo OTLP. Por predefinição, o SDK Python do OpenTelemetry usa o formato W3C Trace Context para propagar o contexto de rastreio, o que garante que os intervalos têm a relação principal-secundário correta num rastreio.

O seguinte exemplo de código ilustra um módulo Python para configurar o OpenTelemetry. Para ver o exemplo completo, clique em Mais e, de seguida, selecione Ver no GitHub.

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)

    event_logger_provider = EventLoggerProvider(logger_provider)
    events.set_event_logger_provider(event_logger_provider)

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

A app Flask baseia-se no Gunicorn para publicar pedidos HTTP de acordo com as recomendações no guia Implementação em produção do Flask. O Gunicorn inicia várias cópias da sua app em execução em processos de trabalho independentes para aumentar a taxa de transferência. Para garantir que as métricas dos processos de trabalho não entram em conflito entre si, recomendamos que cada processo de trabalho defina um valor único para o atributo de recurso service.instance.id. Uma forma de o fazer é incluir o ID do processo no elemento service.instance.id. Para mais informações, consulte o artigo Colisões de séries temporais.

Para mais informações e opções de configuração, consulte a instrumentação do OpenTelemetry Python.

Configure o registo estruturado

Para escrever registos estruturados associados a rastreios, configure a sua app para emitir registos formatados em JSON para a saída padrão com chaves que contenham informações de rastreio. O exemplo de código seguinte ilustra como configurar a biblioteca logging padrão para gerar registos estruturados JSON através da biblioteca python-json-logger e como usar o pacote opentelemetry-instrumentation-logging para incluir informações de rastreio.

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 intervalo ativo da mensagem de registo e, em seguida, adiciona essas informações como atributos ao registo estruturado JSON. Estes atributos podem ser usados para correlacionar um registo com um rastreio:

• logging.googleapis.com/trace: nome do recurso do rastreio associado à entrada do registo.
• logging.googleapis.com/spanId: o ID do intervalo com o rastreio associado à entrada do registo.
• logging.googleapis.com/trace_sampled: o valor deste campo tem de ser true ou false.

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

Execute uma app de exemplo configurada para recolher telemetria

A app de exemplo usa formatos neutros de fornecedores, incluindo JSON para registos e OTLP para métricas e rastreios. A telemetria da app é encaminhada para Google Cloud usando o OpenTelemetry Collector configurado com exportadores da Google. Usa o Flask para publicar pedidos HTTP e a biblioteca requests para fazer pedidos HTTP. Para gerar métricas e rastreios para o cliente e o servidor HTTP, a app de exemplo 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()

A app tem dois pontos finais:

• O ponto final /multi é processado pela função multi. O gerador de carga na app envia pedidos para o ponto final /multi. Quando este ponto final recebe um pedido, envia entre três e sete pedidos para o ponto final /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 ponto final /single é processado pela função single. Quando este ponto final recebe um pedido, fica inativo durante um breve período e, em seguida, 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"
  
  

Transfira e implemente a app

Nota: recomendamos que execute a app de exemplo através do Cloud Shell. No entanto, se quiser executar a app de exemplo localmente no Linux ou Mac, ignore o primeiro passo das instruções seguintes.

Para executar o exemplo, faça o seguinte:

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. Aceda ao diretório de exemplo:

   cd opentelemetry-operations-python/samples/instrumentation-quickstart
   

4. Crie e execute o exemplo:

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

   Se não estiver a usar o Cloud Shell, execute a aplicação com a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS a apontar para um ficheiro de credenciais. As Credenciais padrão da aplicação fornecem um ficheiro 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
   

Veja as suas métricas

A instrumentação do OpenTelemetry na app de exemplo gera métricas do Prometheus que pode ver através do Explorador de métricas:

• Prometheus/http_server_duration_milliseconds/histogram registam a duração dos pedidos do servidor e armazenam os resultados num histograma.

• Prometheus/http_client_duration_milliseconds/histogram regista a duração dos pedidos do cliente e armazena os resultados num histograma.

Para ver as métricas geradas pela app de amostra, faça o seguinte:

1. Na Google Cloud consola, aceda à página  Explorador de métricas:

   Aceda ao Metrics Explorer

   Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
3. No elemento Métrica, expanda o menu Selecionar uma métrica, introduza http_server na barra de filtro e, de seguida, use os submenus para selecionar um tipo de recurso e uma métrica específicos:
   1. No menu Recursos ativos, selecione Alvo do Prometheus.
   2. No menu Categorias de métricas ativas, selecione Http.
   3. No menu Métricas ativas, selecione uma métrica.
   4. Clique em Aplicar.
4. Configure a forma como os dados são vistos.
   

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

   Quando são medidos valores inteiros ou duplos, como com as duas métricas counter, o explorador de métricas soma automaticamente todas as séries cronológicas. Para ver os dados das rotas HTTP /multi e /single, defina o primeiro menu da entrada Agregação como Nenhuma.

   Para mais informações sobre como configurar um gráfico, consulte o artigo Selecione métricas quando usar o explorador de métricas.

Veja os seus rastreios

Pode demorar vários minutos até que os dados de rastreio estejam disponíveis. Por exemplo, quando o seu projeto recebe dados de rastreio, o Google Cloud Observability pode ter de criar uma base de dados para armazenar esses dados. A criação da base de dados pode demorar alguns minutos e, durante esse período, não estão disponíveis dados de rastreio para visualização.

Para ver os dados de rastreio, faça o seguinte:

1. Na Google Cloud consola, aceda à página Explorador de rastreios:

   Aceda ao Explorador de rastreios

   Também pode encontrar esta página através da barra de pesquisa.

2. Na secção de tabelas da página, selecione uma linha com o nome do intervalo /multi.

3. No gráfico de Gantt no painel Detalhes do rastreio, selecione o intervalo etiquetado como /multi.

   É aberto um painel que apresenta informações sobre o pedido HTTP. Estes detalhes incluem o método, o código de estado, o número de bytes e o agente do utilizador do autor da chamada.

4. Para ver os registos associados a este rastreio, selecione o separador Registos e eventos.

   O separador mostra registos individuais. Para ver os detalhes da entrada do registo, expanda a entrada do registo. Também pode clicar em Ver registos e ver o registo através do Explorador de registos.

Para mais informações sobre como usar o explorador do Cloud Trace, consulte o artigo Encontre e explore rastreios.

Veja os seus registos

No Explorador de registos, pode inspecionar os seus registos e também ver rastreios associados, quando existirem.

1. Na Google Cloud consola, aceda à página Explorador de registos:

   Aceda ao Explorador de registos

   Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

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

   Para ver os detalhes do registo, expanda a entrada do registo.

3. Clique em Rastreios numa entrada de registo com a mensagem "handle /multi request" e, de seguida, selecione Ver detalhes do rastreio.

   É aberto um painel Detalhes do rastreio que apresenta o rastreio selecionado.

   Os dados de registo podem estar disponíveis vários minutos antes dos dados de rastreio. Se encontrar um erro ao ver os dados de rastreio pesquisando um rastreio por ID ou seguindo os passos desta tarefa, aguarde um ou dois minutos e tente novamente a ação.

Para mais informações sobre a utilização do Explorador de registos, consulte o artigo Veja registos através do Explorador de registos.

O que se segue?

• OpenTelemetry
• Especificação OTLP
• Registo estruturado
• Resolução de problemas do Managed Service for Prometheus
• Resolva problemas do Cloud Trace