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

Nesta página, descrevemos como:

  • ver os traces no Console do Google Cloud Platform;
  • 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:

    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 do rastreamento 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 do rastreamento, é 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 do rastreamento, consulte Como visualizar traces no Console do GCP.

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 a fim de 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 períodos adicionais:

  • 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 a recuperará e a armazenará 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 houver 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 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.

Resumidamente, é 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 feitas por segundo para a API. Para conseguir essa estimativa, use o gráfico Solicitações na página Endpoints > Serviços ou o 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 do rastreamento 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ê quer que o ESP pare de fazer solicitações de amostragens e enviar traces, é possível definir uma opção de inicialização do ESP e reiniciá-lo. Os traces enviados ao Stackdriver Trace são independentes 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 esteja 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 para o comando docker run, inclua a opção --disable_trace_sampling=true:
    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_trace_sampling=true
  3. Emita o comando docker run para reiniciar o ESP.

Para reativar a amostragem de traces:

  1. Remova a opção --disable_trace_sampling ou defina-a como false.
  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 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_trace_sampling=true"
      ]
  2. Inicie o serviço do Kubernetes com o comando kubectl create:
    kubectl create -f deployment.yaml

Para reativar a amostragem de traces:

  1. Remova a opção --disable_trace_sampling ou defina-a como false.
  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 de metadados da instância de VM equivalente para a opção --disable_trace_sampling. Se você 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 a ela, conforme descrito na solução de problemas do Trace. Se uma solicitação contiver o cabeçalho X-Cloud-Trace-Context, o ESP enviará os dados de trace ao Trace mesmo que você tenha desativado a amostragem de traces.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Cloud Endpoints com gRPC
Precisa de ajuda? Acesse nossa página de suporte.