Como rastrear a API

Após a implantação do Extensible Service Proxy (ESP) e do código de back-end da API, o ESP é usado para interceptar todas as solicitações e executar as verificações necessárias antes de encaminhar a solicitação ao back-end da API. Quando o back-end responde, a telemetria é coletada e relatada pelo ESP. Parte dos dados de telemetria capturados pelo ESP é de rastreamento do Cloud Trace.

Nesta página, descrevemos como:

  • visualizar traces no Console do Google Cloud;
  • estimar os custos do Trace;
  • configurar o ESP para desativar a amostragem de trace.

Como visualizar os traces da API

Para visualizar os traces da API:

  1. Acesse a página Endpoints > Serviços do projeto:

    Ir para a página Serviços do Endpoints

  2. Se você tiver mais de uma API, clique naquela que você quer rastrear.

  3. Verifique se você está na guia Visão geral.

  4. Role para baixo e clique em Ver rastreamentos. A página Lista de traces do Cloud Trace é exibida.

Um trace registra uma solicitação recebida pela API e os vários eventos, como chamadas de RPC ou seções instrumentadas de código que ocorreram, além de horários precisos. Esses eventos são representados como períodos no trace.

Na página Lista de traces, é possível detalhar um trace individual e ver os períodos criados nele pelo ESP.

Exemplo de trace com períodos

Para mais informações sobre a página Lista de traces, consulte Como visualizar traces no Console do Cloud.

Períodos criados pelo ESP

Quatro períodos por trace, no mínimo, são criados pelo ESP:

  • Um período para toda a solicitação e a resposta.
  • Um período CheckServiceControlpara a chamada ao método services.check do Service Control para conseguir a configuração da API.
  • Um período QuotaControl para verificar se há uma cota configurada na sua API.
  • Um período Backend que rastreia o tempo gasto no código de back-end da API.

Dependendo da configuração da API, o ESP cria períodos adicionais:

  • Se a API exigir autenticação, o ESP criará um período CheckAuth em cada trace. Para autenticar uma solicitação, o ESP armazena em cache por cinco minutos a chave pública necessária para esse procedimento. Se a chave pública não estiver no cache, o ESP vai recuperar e armazená-la em cache, além de criar um período HttpFetch.
  • Se a API precisar de uma chave de API, o ESP criará um período CheckServiceControlCache em cada trace. As informações necessárias para a validação da chave de API são armazenadas em cache pelo ESP. Se as informações não estiverem no cache, o ESP vai chamar o Service Control e criar um período Call ServiceControl server.
  • Se você tiver uma cota definida para a API, o ESP criará um período QuotaServiceControlCache em cada trace. As informações necessárias para a verificação da cota são armazenadas em cache pelo ESP. Se as informações não estiverem no cache, o ESP vai chamar o Service Control e criar um período Call ServiceControl server.

Taxa de amostragem do trace

Um pequeno número de solicitações para a API é coletado pelo ESP para recolher dados do trace. Para controlar a taxa de amostragem, um contador de solicitações e um timer são mantidos pelo ESP. O número de solicitações por segundo para a API determina a taxa de amostragem. Se não houver solicitações dentro de um segundo, o ESP não enviará um trace.

Se o número de pedidos em um segundo for:

  • menor ou igual a 999, um trace é enviado;
  • entre 1.000 e 1.999, dois traces são enviados;
  • entre 2.000 e 2.999, três traces são enviados;
  • e assim por diante.

Resumindo, você pode estimar a taxa de amostragem com a função ceiling: ceiling(requests per second/1000)

Como estimar o custo do Trace

Para estimar o custo do Trace, é preciso estimar o número de períodos enviados pelo ESP ao Trace em um mês.

Para estimar o número de períodos por mês:

  1. Estime o número de solicitações por segundo na sua API. Para receber essa estimativa, é possível usar o gráfico Solicitações na página Endpoints > Serviços ou no Cloud Logging. Consulte a seção Como monitorar a API para mais informações.
  2. Calcule o número de traces que o ESP envia ao Trace por segundo: ceiling(requests per second/1000)
  3. Estime o número de períodos em um trace. Para conseguir essa estimativa, use as informações em Períodos criados pelo ESP ou acesse a página Lista de traces para ver os traces da API.
  4. Estime o número de segundos em que sua API recebe tráfego por mês. Por exemplo, algumas APIs recebem solicitações apenas durante determinados horários do dia, enquanto outras recebem esporadicamente.
  5. Multiplique o número de segundos no mês pelo número de períodos.

Exemplo:

  1. Suponha que o número máximo de solicitações por segundo para uma API seja 5.
  2. A taxa de amostragem de trace é: ceiling(5/1000) = 1.
  3. A API não tem uma cota configurada, não exige uma chave de API e não requer autenticação. Portanto, o número de períodos que o ESP cria por trace é 4.
  4. Essa API recebe solicitações somente durante o horário comercial, de segunda a sexta-feira. O número de segundos em que a API recebe tráfego por mês é de aproximadamente: 3600 x 8 x 20 = 576.000.
  5. O número de períodos por mês é de aproximadamente: 576.000 x 4 = 2.304.000

Depois que você souber o número aproximado de períodos em um mês, veja informações detalhadas sobre preços na página Preços do Trace.

Como desativar a amostragem de traces

Se você quiser parar as solicitações de amostragem e o envio de traces do ESP, defina uma opção de inicialização e reinicie o ESP. Os traces que o ESP envia ao Cloud Trace não dependem dos gráficos exibidos na página Endpoints > Serviços. Os gráficos continuam disponíveis se você desativar a amostragem de traces.

Na seção a seguir, supomos que você já implantou a API e o ESP ou que está familiarizado com o processo de implantação. Para mais informações, consulte Como implantar o back-end da API.

App Engine

Para desativar a amostragem de trace do ESP no ambiente flexível do App Engine, faça o seguinte:

  1. Edite o arquivo app.yaml. Na seção endpoints_api_service, adicione a opção trace_sampling e defina o valor dela como false. Exemplo:
    endpoints_api_service:
      name: example-project-12345.appspot.com
      rollout_strategy: managed
      trace_sampling: false
    

    Se o aplicativo for baseado em microsserviços, você deverá incluir trace_sampling: false em cada arquivo app.yaml.

  2. Se você não atualizou o SDK do Cloud recentemente, execute o comando:
    gcloud components update
    
  3. Salve o arquivo app.yaml.
  4. Implante o código de back-end e o ESP no App Engine:
    gcloud app deploy
    

Para reativar a amostragem de traces:

  1. Remova a opção trace_sampling de app.yaml.
  2. Implante o código de back-end e o ESP no App Engine:
    gcloud app deploy
    

Compute Engine

Para desativar a amostragem de traces do ESP no Compute Engine com Docker:

  1. Conecte-se à instância de VM:
    gcloud compute ssh [INSTANCE_NAME]
  2. Nas sinalizações do ESP do comando docker run, adicione a opção --disable_cloud_trace_auto_sampling:
    sudo docker run \
        --name=esp \
        --detach \
        --publish=80:8080 \
        --net=esp_net \
        gcr.io/endpoints-release/endpoints-runtime:1 \
        --service=[SERVICE_NAME] \
        --rollout_strategy=managed \
        --backend=[YOUR_API_CONTAINER_NAME]:8080 \
        --disable_cloud_trace_auto_sampling
  3. Emita o comando docker run para reiniciar o ESP.

Para reativar a amostragem de traces:

  1. Remova --disable_cloud_trace_auto_sampling.
  2. Emita o comando docker run para reiniciar o ESP.

GKE

Para desativar a amostragem de traces do ESP no GKE:

  1. Abra o arquivo de manifesto de implantação, conhecido como deployment.yaml, e adicione o seguinte comando à seção containers:
    containers:
    - name: esp
      image: gcr.io/endpoints-release/endpoints-runtime:1
      args: [
        "--http_port=8081",
        "--backend=127.0.0.1:8080",
        "--service=[SERVICE_NAME]",
        "--rollout_strategy=managed",
        "--disable_cloud_trace_auto_sampling"
      ]
  2. Inicie o serviço do Kubernetes usando o comando kubectl create:
    kubectl create -f deployment.yaml

Para reativar a amostragem de traces:

  1. Remova a opção --disable_cloud_trace_auto_sampling.
  2. Inicie o serviço do Kubernetes:
    kubectl create -f deployment.yaml

Se você estiver executando o ESP em uma instância de VM do Compute Engine sem um contêiner do Docker, não haverá par de chave-valor para os metadados da instância da VM equivalente para a opção --disable_cloud_trace_auto_sampling. Se quiser desativar a amostragem de traces, precisará executar o ESP em um contêiner.

Um cliente pode forçar o trace de uma solicitação adicionando o cabeçalho X-Cloud-Trace-Context à solicitação, conforme descrito em Como forçar uma solicitação a ser rastreada. Se uma solicitação contiver o cabeçalho X-Cloud-Trace-Context, o ESP enviará os dados de rastreamento para o Trace mesmo se a amostragem de traces tiver sido desativada.