Início rápido

Neste guia de início rápido, você usa o Cloud Shell para implantar um aplicativo de amostra em um cluster do Google Kubernetes Engine (GKE). O aplicativo é escrito em Python. Após a implantação, use curl para emitir uma solicitação HTTP. Essa ação faz com que um trace seja capturado e enviado para seu projeto do Google Cloud. Por fim, use a interface do Cloud Trace para visualizar as informações de latência do trace gerado.

Antes de começar

  1. Faça login na sua conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. No Console do Cloud, na página de seletor de projetos, selecione ou crie um projeto do Cloud.

    Acessar a página do seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud. Saiba como confirmar se a cobrança está ativada para o seu projeto.

Fazer o download e implantar o aplicativo

Para fazer o download e implantar o aplicativo, faça o seguinte:

  1. Para abrir o Cloud Shell, clique em Ativar o Cloud Shell na barra de ferramentas do Console do Google Cloud:

    Ative o Cloud Shell.

    Após alguns instantes, uma sessão do Cloud Shell é aberta no Console do Google Cloud:

    Sessão do Cloud Shell.

  2. Para fazer o download do código-fonte do GitHub, execute o seguinte comando:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

  3. Para ativar a API do Google Kubernetes Engine, emita o seguinte comando no Cloud Shell:

    gcloud services enable container.googleapis.com

  4. Para criar o cluster do GKE chamado demo, execute o seguinte comando no Cloud Shell:

    gcloud container clusters create demo --zone us-west1-b

    Esse comando leva de três a cinco minutos para ser concluído. Após a conclusão, o projeto do Google Cloud conterá o cluster do GKE chamado demo. Você precisa ter permissão para criar clusters com acesso externo no projeto do Google Cloud. Se o Google Cloud estiver em uma organização ou em uma pasta, talvez você não tenha essas permissões, mesmo que seja o proprietário do projeto. Se esse comando falhar, entre em contato com o administrador do sistema.

  5. Para verificar a criação, execute o seguinte comando kubectl:

    kubectl get nodes

    Um exemplo de saída desse comando é:

    NAME                                  STATUS   ROLES    AGE   VERSION
gke-demo-default-pool-24680f3d-bzvg   Ready    <none>   26m   v1.14.10-gke.27
gke-demo-default-pool-24680f3d-hfnq   Ready    <none>   26m   v1.14.10-gke.27
gke-demo-default-pool-24680f3d-qnh6   Ready    <none>   26m   v1.14.10-gke.27

  6. Implante o aplicativo de amostra executando o seguinte comando:

    cd python-docs-samples/trace/cloud-trace-demo-app && ./setup.sh

    O script setup.sh, que faz parte desse projeto, configura três serviços diferentes, marcados como cloud-trace-demo-a, cloud-trace-demo-b e cloud-trace-demo-c. Como o script de configuração ajusta um serviço por vez, a configuração leva vários minutos para ser concluída. Veja a seguir um exemplo do que o script imprime no Cloud Shell durante a execução:

     Creating service a
 deployment.apps/cloud-trace-demo-a unchanged
 service/cloud-trace-demo-a unchanged
 Fetching the external IP of service a
 Passing external IP for the first service 34.82.132.95 to the second service template
 deployment.apps/cloud-trace-demo-b created
 service/cloud-trace-demo-b created
 Fetching the external IP of service b
 Passing external IP for the service b 35.230.0.131 to the service c
 deployment.apps/cloud-trace-demo-c created
 service/cloud-trace-demo-c created

Criar um trace

Um trace descreve o tempo que um aplicativo leva para concluir uma única operação. Cada trace consiste em um ou mais períodos. Um período descreve quanto tempo leva para executar uma suboperação completa. Por exemplo, um trace pode descrever quanto tempo leva para processar uma solicitação recebida de um usuário e retornar uma resposta. Um período pode descrever por quanto tempo uma chamada RPC específica leva. Para mais informações, consulte Modelo de dados do Cloud Trace.

Para criar um trace, execute o seguinte comando:

curl $(kubectl get svc cloud-trace-demo-c -ojsonpath='{.status.loadBalancer.ingress[0].ip}')

O comando curl gera uma solicitação HTTP GET e emite a solicitação para o serviço chamado cloud-trace-demo-c. Quando essa solicitação é concluída, Helloworld! é impresso no shell.

É possível executar o comando curl várias vezes para gerar vários traces.

Visualizar os dados de trace

Para abrir a interface do Cloud Trace, no Console do Google Cloud, clique em Menu de navegação e selecione Trace ou clique no botão a seguir:

Acessar o "Trace"

Janela de visão geral

A janela Visão geral é a visualização padrão no Trace. Essa janela exibe dados de latência e informações resumidas, incluindo um relatório de análise. Se você criou um novo projeto, o painel mais interessante da janela Visão geral é o painel Traces recentes:

Painel de traces recentes que exibe os traces mais recentes e a latência deles.

Esse painel lista os traces mais recentes e a latência deles. Para ver os detalhes de um trace, clique no link dele.

Janela da lista de traces

No painel de navegação do Trace, clique em Lista de trace:

Janela da lista de traces para o início rápido.

Essa janela exibe um gráfico e uma tabela. Cada ponto no gráfico representa um trace. Cada ponto também corresponde a uma linha na tabela. Na captura de tela anterior, vários traces são listados, indicando que o comando curl foi executado várias vezes.

Para visualizar um trace em detalhes, selecione um ponto no gráfico ou uma linha na tabela. Essa ação resulta na abertura de dois painéis que exibem os detalhes do trace selecionado:

Exibição em cascata para o início rápido.

Um painel exibe o trace em um gráfico de cascata, e o painel mostra os detalhes. Cada linha no gráfico de cascata corresponde a um período. Os detalhes do período, como as informações resumidas, método e os rótulos de trace sobre a latência do comando, são exibidos na tabela de detalhes. Para ver detalhes sobre um período, clique na linha correspondente no gráfico de cascata. Observe que os períodos são para três endereços IP diferentes; eles correspondem aos endereços IP dos três serviços. A partir desse trace, é possível ver que uma solicitação HTTP recebida pelo nome do serviço cloud-trace-demo-c é transmitida para o serviço cloud-trace-demo-b e, em seguida, para cloud-trace-demo-a.

A tabela de detalhes pode incluir um link para os dados que foram enviados para o Cloud Logging. Para ver as informações na interface do Cloud Logging, clique em Visualizar. A captura de tela a seguir ilustra um exemplo de registro gerado por dados de trace:

LogEntry para um trace do início rápido.

Observe que os endereços IP exibidos na visualização em cascata correspondem aos endereços IP dos serviços chamados cloud-trace-demo-a e cloud-trace-demo-b.

Janela "Relatórios de análise"

Para visualizar ou criar um relatório, no painel de navegação do Trace, clique em Relatórios de análise. O Trace cria relatórios diários automaticamente. Para este projeto, não há dados suficientes para criar um novo relatório.

Sobre o aplicativo

O aplicativo de amostra usado neste guia de início rápido está disponível em um repositório do GitHub. Esse repositório contém informações sobre como usar o aplicativo em ambientes diferentes do Cloud Shell. O aplicativo de amostra é escrito em Python, usa o framework Flask e os pacotes OpenCensus e é executado em um cluster do Google Kubernetes Engine.

Os autores do aplicativo escolheram usar o framework do Flask porque seu uso simplifica o desenvolvimento de aplicativos e porque queriam usar o middleware do OpenCensus Flask. Você não precisa usar o framework Flask se estiver usando Python.

Instrumentação

O arquivo app.py no repositório do GitHub contém a instrumentação necessária para capturar e enviar dados do trace para seu projeto do Google Cloud:

  • As instruções de importação do aplicativo incluem uma instrução para Flask e para vários pacotes do OpenCensus. O StackdriverExporter é o objeto que envia dados de trace para seu projeto do Google Cloud:

    from flask import Flask
from opencensus.ext.flask.flask_middleware import FlaskMiddleware
from opencensus.ext.stackdriver.trace_exporter import StackdriverExporter
from opencensus.trace import execution_context
from opencensus.trace.propagation import google_cloud_format
from opencensus.trace.samplers import AlwaysOnSampler

  • O aplicativo cria um componente de middleware que usa o Flask como o framework HTTP:

    propagator = google_cloud_format.GoogleCloudFormatPropagator()

def createMiddleWare(exporter):
    # Configure a flask middleware that listens for each request and applies automatic tracing.
    # This needs to be set up before the application starts.
    middleware = FlaskMiddleware(
        app,
        exporter=exporter,
        propagator=propagator,
        sampler=AlwaysOnSampler())
    return middleware

    Neste aplicativo, o campo sampler é definido pelo método OpenCensus AlwaysOnSampler(). Esse método retorna True para cada decisão de amostragem e garante que 100% das solicitações gerem traces. A amostragem de todas as solicitações não é recomendada em um ambiente de produção. Para mais informações, consulte Taxa de amostragem.

  • Na função main do aplicativo, construa o middleware do Flask que usa o StackdriverExporter():

    createMiddleWare(StackdriverExporter())

  • O aplicativo contém mais uma modificação que não é necessária. Em vez disso, essa modificação é ilustrativa. No aplicativo, a resposta para a rota / inclui o cabeçalho X-Cloud-Trace-Context:

    trace_context_header = propagator.to_header(execution_context.get_opencensus_tracer().span_context)
response = requests.get(
    url,
    params=data,
    headers={
      'X-Cloud-Trace-Context' : trace_context_header}
)

    O cabeçalho X-Cloud-Trace-Context é um cabeçalho HTTP que contém informações sobre o trace atual, incluindo o identificador de trace. Para que serviços diferentes possam adicionar informações de período ao mesmo trace, esses serviços precisam ser capazes de reconhecer o identificador de trace. Por padrão, o pacote do OpenCensus inclui automaticamente esse contexto nos cabeçalhos de resposta.

Como o aplicativo funciona

Para maior clareza, nesta seção, cloud-trace-demo é omitido dos nomes de serviço. Por exemplo, o serviço cloud-trace-demo-c é referenciado como c.

Este aplicativo cria três serviços chamados a, b e c. Ele configura o serviço c para chamar o serviço b e para o serviço b chamar o serviço a. Para detalhes sobre a configuração dos serviços, consulte os arquivos YAML no repositório do GitHub.

Ao emitir uma solicitação HTTP para o serviço c neste guia de início rápido, você usou o seguinte comando curl:

curl $(kubectl get svc cloud-trace-demo-c -ojsonpath='{.status.loadBalancer.ingress[0].ip}')

O comando curl funciona da seguinte maneira:

  1. kubectl busca o endereço IP do serviço chamado cloud-trace-demo-c.
  2. O comando curl envia a solicitação HTTP para o serviço c.
  3. O serviço c recebe a solicitação HTTP e envia uma solicitação ao serviço b.
  4. O serviço b recebe a solicitação HTTP e envia uma solicitação ao serviço a.
  5. O serviço a recebe a solicitação e retorna a string Hello. A string Hello é uma palavra-chave passada como um argumento padrão para esse serviço.
  6. O serviço b recebe a resposta do serviço a, anexa a string world e retorna Helloworld. A string world é uma palavra-chave passada como um argumento padrão para esse serviço.
  7. O serviço c recebe a resposta do serviço b, anexa ! e retorna Helloworld!.
  8. A resposta do serviço c é impressa no Cloud Shell.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste guia de início rápido, siga estas etapas:

  • Se você criou um novo projeto do Google Cloud para este guia de início rápido, exclua o projeto para parar de acumular cobranças. Para excluir seu projeto, faça o seguinte:

    1. No Console do Google Cloud, clique em menu de navegação e selecione Página inicial.
    2. No painel Informações do projeto, clique em Acessar as configurações do projeto.
    3. Na janela Configurações, clique em Encerrar e conclua as etapas restantes.

  • Se você não criou um novo projeto do Google Cloud para este guia de início rápido, exclua o cluster do Google Kubernetes Engine chamado demo executando o seguinte comando:

    gcloud container clusters delete demo --zone us-west1-b

A seguir