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 coletados pelo ESP é rastreada pelo Stackdriver Trace.

Nesta página, descrevemos como:

  • ver os 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 seu projeto:

    Acessar 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 Stackdriver é 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 ver 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 CheckServiceControl para 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 API.
  • Um período Backend para rastrear o tempo gasto no código de back-end da API.

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

  • Se a API precisar de 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 fará a recuperação e armazenamento dela em cache e criará um período HttpFetch.
  • Se a API precisar de uma chave, 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 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 todos os traces. 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 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.

Em resumo, é possível estimar a taxa de amostragem com a função ceiling (em inglês): 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 para sua API. Para ver essa estimativa, use o gráfico Solicitações na página Endpoints > Serviços ou no Stackdriver Logging. Consulte 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 Stackdriver.

Como desativar a amostragem de traces

Se você não quiser que o ESP faça a amostragem de solicitações e envie traces, defina uma opção de inicialização do ESP e o reinicie. Os traces enviados ao Stackdriver Trace não dependem dos gráficos exibidos na página Endpoints > Services. Os gráficos continuarão 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.

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 no 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, chamado de deployment.yaml, e adicione o seguinte à 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. Use o comando kubectl create (em inglês) para iniciar o serviço do Kubernetes:
    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ê executa o ESP em uma instância de VM do Compute Engine sem um contêiner do Docker, não haverá um par de chave-valor de metadados equivalente na opção --disable_cloud_trace_auto_sampling. Se você quiser desativar a amostragem de traces, será necessário executar o ESP em um contêiner.

Um cliente pode forçar o trace de uma solicitação ao adicionar o cabeçalho X-Cloud-Trace-Context a ela, conforme descrito em Solução de problemas do Trace. Se uma solicitação tiver o cabeçalho X-Cloud-Trace-Context, o ESP enviará os dados de trace para o Trace mesmo se você tiver desativado a amostragem.