Como rastrear a API

OpenAPI | gRPC

Após a implantação do Extensible Service Proxy (ESP) ou do Extensible Service Proxy V2 (ESPv2) e do código de back-end da API, o proxy intercepta todas as solicitações e executa as verificações necessárias antes de encaminhar a solicitação ao back-end da API. Quando o back-end responde, o proxy coleta e relata a telemetria. Parte dos dados de telemetria capturados pelo proxy é de rastreamento do Cloud Trace.

Nesta página, descrevemos como:

• visualizar traces no console do Google Cloud;
• Estimar os custos do Trace;
• Configure o proxy para desativar a amostragem de traces.

Como visualizar traces

Um trace registra uma solicitação recebida pela API e os vários eventos (como chamadas de RPC ou seções de código instrumentadas) com horários precisos de cada evento. Esses eventos são representados como períodos no trace.

Para conferir os traces do seu projeto, acesse a página do Cloud Trace no console do Google Cloud:

Acessar o "Trace"

Na página Trace Explorer, é possível detalhar um trace individual e conferir os períodos criados nele pelo ESP. É possível usar o filtro para visualizar traces de uma única API ou operação.

Os traces e períodos criados para a API serão diferentes se ela usar ESPv2 ou ESP. Veja abaixo um resumo dos formatos de rastreamento para cada implementação.

Para mais informações sobre a página Explorador de trace, consulte Encontrar e analisar traces.

Períodos criados pelo ESPv2

O ESPv2 cria traces no seguinte formato:

No mínimo, o ESPv2 cria dois períodos por trace:

• Um período ingress OPERATION_NAME para toda a solicitação e a resposta.
• Um período router BACKEND egress pelo tempo que o ESPv2 aguarda até que o back-end processe a solicitação e responda. Isso inclui o salto de rede entre o ESPv2 e o back-end.

Dependendo da configuração da API, o ESPv2 pode criar períodos adicionais:

• Se a API exigir autenticação, o ESPv2 armazenará em cache a chave pública necessária para autenticação por cinco minutos. 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 JWT Remote PubKey Fetch.
• Se a API exigir uma chave de API, o ESPv2 armazenará em cache as informações necessárias para validar a chave de API. Se as informações não estiverem no cache, o ESP vai chamar o Service Control e criar um período Service Control remote call: Check.

Em geral, o ESPv2 cria períodos para chamadas de rede que bloqueiam a solicitação de entrada. Solicitações sem bloqueio não serão rastreadas. Qualquer processamento local criará eventos de tempo em vez de períodos. Exemplo:

• A aplicação da cota requer chamadas remotas, mas elas não ocorrem no caminho de uma solicitação da API e não terão períodos associados a elas no trace.
• As chaves de API são armazenadas em cache pelo ESPv2 por um curto período. As solicitações que usam o cache terão um evento de tempo associado ao trace.

Períodos criados pelo ESP

Aviso: o ESP não fornece informações detalhadas sobre períodos. Também cria períodos extras que não são significativos. Faça a migração para o ESPv2 para visualizar traces detalhados que seguem as práticas recomendadas de rastreamento.

Os traces são criados no seguinte formato:

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 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 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 rastros 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, consulte a página Preços do Trace para informações detalhadas sobre preços.

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 esteja 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 a Google Cloud CLI recentemente, execute o seguinte 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.

Propagação do contexto de trace

Para o rastreamento distribuído, um cabeçalho de solicitação pode ter um contexto de rastreamento que especifica um ID de trace. O ID de trace é usado quando o ESPv2 cria novos períodos de trace e os envia ao Cloud Trace. O ID do trace é usado para pesquisar todos os traces e períodos de junção para uma única solicitação. Se nenhum contexto de rastreamento for especificado na solicitação e o trace estiver ativado, um ID de trace aleatório será gerado para todos os períodos no trace.

No exemplo a seguir, o Cloud Trace correlaciona os períodos criados pelo ESPv2 (1) com períodos criados pelo back-end (2) para uma única solicitação. Isso ajuda a depurar problemas de latência em todo o sistema:

Para mais detalhes, leia Conceitos principais do OpenTelemetry: propagação no contexto (em inglês)

Observação: o rastreamento distribuído exige que os clientes e/ou os back-ends sejam compatíveis com o recurso. Isso está fora do escopo desta documentação. Recomendamos o uso de OpenTelemetry.

Cabeçalhos compatíveis

O ESPv2 é compatível com os seguintes cabeçalhos de propagação de contexto de rastreamento:

• traceparent: o cabeçalho de propagação de contexto de trace padrão do W3C. Com suporte da maioria das estruturas de rastreamento modernas.
• x-cloud-trace-context: cabeçalho de propagação de contexto de rastreamento do GCP Compatível com estruturas de rastreamento mais antigas e bibliotecas do Google, mas específicas de fornecedores.
• grpc-trace-bin: rastrear o cabeçalho de propagação do contexto usado pelos back-ends do gRPC com a biblioteca de rastreamento OpenCensus (em inglês).

Se você estiver criando um novo aplicativo, recomendamos o uso de propagação de contexto de rastreamento traceparent. O ESPv2 extrairá e propagará esse cabeçalho por padrão. Consulte as opções de inicialização de rastreamento do ESPv2 para ver detalhes sobre como alterar o comportamento padrão.

Observação: ao contrário do ESPv2, a propagação de contexto de rastreamento no ESP precisa ser ativada manualmente por meio das opções de inicialização. O ESP não é compatível com o cabeçalho traceparent.