Rastrear a sua API

OpenAPI   |  gRPC

Depois de implementar o Extensible Service Proxy (ESP) ou o Extensible Service Proxy V2 (ESPv2) e o código de back-end da sua API, o proxy interceta todos os pedidos e executa todas as verificações necessárias antes de encaminhar o pedido para o back-end da API. Quando o back-end responde, o proxy recolhe e comunica a telemetria. Um dos dados de telemetria que o proxy captura é o rastreio, através do Cloud Trace.

Esta página explica como:

• Veja rastreios na Google Cloud consola.
• Estime o custo do Trace.
• Configure o proxy para desativar a amostragem de rastreios.

Visualizar rastreios

Um rastreio acompanha um pedido recebido para a sua API e os vários eventos (como chamadas RPC ou secções de código instrumentadas), juntamente com as horas precisas de cada evento. Estes eventos são representados como intervalos no rastreio.

Para ver os rastreios do seu projeto, aceda à página do Cloud Trace em Google Cloud console:

Aceda ao rastreio

Na página Explorador de rastreios, pode analisar detalhadamente um rastreio individual e ver os intervalos que o ESP cria num rastreio. Pode usar o filtro para ver rastreios de uma única API ou operação.

Os rastreios e os intervalos criados para a sua API diferem consoante a API use o ESPv2 ou o ESP. Segue-se um resumo dos formatos de rastreio para cada implementação.

Para mais informações sobre a página Explorador de rastreios, consulte o artigo Encontre e explore rastreios.

Intervalos criados pelo ESPv2

O ESPv2 cria rastreios no seguinte formato:

No mínimo, o ESPv2 cria 2 intervalos por rastreio:

• Um intervalo ingress OPERATION_NAME para todo o pedido e resposta.
• Um intervalo router BACKEND egress para o tempo que o ESPv2 aguarda que o back-end processe o pedido e responda. Isto inclui o salto de rede entre o ESPv2 e o back-end.

Consoante a configuração da sua API, o ESPv2 pode criar intervalos adicionais:

• Se a sua API exigir autenticação, o ESPv2 armazena em cache a chave pública de que precisa para autenticar durante 5 minutos. Se a chave pública não estiver na cache, o ESPv2 obtém e coloca em cache a chave pública e cria um intervalo JWT Remote PubKey Fetch.
• Se a sua API exigir uma chave de API, o ESPv2 armazena em cache as informações necessárias para validar a chave de API. Se as informações não estiverem na cache, o ESPv2 chama o Service Control e cria um intervalo Service Control remote call: Check.

Em geral, o ESPv2 só cria intervalos para chamadas de rede que bloqueiam o pedido recebido. Os pedidos não bloqueantes não são rastreados. Qualquer processamento local cria eventos de tempo em vez de intervalos. Por exemplo:

• A aplicação da quota requer chamadas remotas, mas as chamadas não ocorrem no caminho de um pedido de API e não têm intervalos associados no rastreio.
• As chaves da API são colocadas em cache pelo ESPv2 durante um curto período. Todos os pedidos que usam a cache têm um evento de tempo associado no rastreio.

Intervalos criados pelo ESP

Aviso: o ESP não fornece informações detalhadas para os intervalos. Também cria intervalos adicionais que não são significativos. Migre para o ESPv2 para ver rastreios detalhados que seguem as práticas recomendadas de rastreio.

O ESP cria rastreios no seguinte formato:

No mínimo, o ESP cria 4 intervalos por rastreio:

• Um intervalo para todo o pedido e resposta.
• Um intervalo CheckServiceControl para a chamada ao método Service Control's services.check para obter a configuração da sua API.
• Um intervalo QuotaControl para verificar se existe uma quota configurada na sua API.
• Um intervalo Backend que acompanha o tempo gasto no código de back-end da sua API.

Consoante a configuração da sua API, o ESP cria intervalos adicionais:

• Se a sua API exigir autenticação, o ESP cria um CheckAuthintervalo em cada rastreio. Para autenticar um pedido, o ESP armazena em cache a chave pública de que precisa para autenticar durante 5 minutos. Se a chave pública não estiver na cache, o ESP obtém e coloca em cache a chave pública e cria um intervalo HttpFetch.
• Se a sua API exigir uma chave de API, o ESP cria um intervalo CheckServiceControlCache em cada rastreio. O ESP armazena em cache as informações de que precisa para validar a chave da API. Se as informações não estiverem na cache, o ESP chama o Service Control e cria um intervalo Call ServiceControl server.
• Se tiver uma quota definida para a sua API, o ESP cria um intervalo QuotaServiceControlCacheem cada rastreio. O ESP armazena em cache as informações necessárias para verificar a quota. Se as informações não estiverem na cache, o ESP chama o Service Control e cria um intervalo Call ServiceControl server.

Taxa de amostragem de rastreios

O ESP faz uma amostragem de um pequeno número de pedidos à sua API para obter dados de rastreio. Para controlar a taxa de amostragem, o ESP mantém um contador de pedidos e um temporizador. O número de pedidos por segundo à sua API determina a taxa de amostragem. Se não existirem pedidos no prazo de um segundo, o ESP não envia um rastreio.

Se o número de pedidos num segundo for:

• Inferior ou igual a 999, o ESP envia 1 rastreio.
• Entre 1000 e 1999, o ESP envia 2 rastreios.
• Entre 2000 e 2999, o ESP envia 3 rastreios.
• E assim sucessivamente.

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

Estimar o custo do Trace

Para estimar o custo do Trace, tem de estimar o número de intervalos que o ESP envia para o Trace num mês.

Para estimar o número de intervalos por mês:

1. Estime o número de pedidos por segundo para a sua API. Para obter esta estimativa, pode usar o gráfico Pedidos na página Endpoints > Serviços ou no Cloud Logging. Consulte o artigo Monitorizar a sua API para mais informações.
2. Calcular o número de rastreios que o ESP envia para Rastreios por segundo: ceiling(requests per second/1000)
3. Estime o número de intervalos num rastreio. Para obter esta estimativa, pode usar as informações em Intervalos criados pelo ESP ou ver a página Lista de rastreios para ver rastreios da sua API.
4. Estime o número de segundos num mês em que a sua API recebe tráfego. Por exemplo, algumas APIs recebem pedidos apenas durante determinadas horas do dia e outras APIs recebem pedidos esporadicamente.
5. Multiplique o número de segundos no mês pelo número de intervalos.

Por exemplo:

1. Suponha que o número máximo de pedidos por segundo para uma API é 5.
2. A taxa de amostragem de rastreios é o limite máximo (5/1000) = 1
3. A API não tem uma quota configurada, não requer uma chave da API e não requer autenticação. Por conseguinte, o número de intervalos que o ESP cria por rastreio é 4.
4. Esta API recebe pedidos apenas durante o horário de funcionamento, de segunda a sexta-feira. O número de segundos num mês em que a API recebe tráfego é aproximadamente: 3600 X 8 X 20 = 576 000
5. O número de intervalos por mês é de aproximadamente 576 000 x 4 = 2 304 000

Depois de saber o número aproximado de intervalos num mês, consulte a página Preços de rastreio para obter informações detalhadas sobre os preços.

Desativar a amostragem de rastreios

Se quiser impedir que o ESP faça a amostragem de pedidos e envie rastreios, pode definir uma opção de arranque do ESP e reiniciar o ESP. Os rastreios que o ESP envia para o Cloud Trace são independentes dos gráficos apresentados na página Endpoints > Serviços. Os gráficos continuam disponíveis se desativar a amostragem de rastreio.

A secção seguinte pressupõe que já implementou a sua API e ESP, ou que está familiarizado com o processo de implementação. Para mais informações, consulte o artigo Implementar o back-end da API.

App Engine

Para desativar a amostragem de rastreio do ESP no ambiente flexível do App Engine:

1. Edite o ficheiro app.yaml. Na secção endpoints_api_service trace_sampling, adicione a opção false e defina o respetivo valor como. Por exemplo:

   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     trace_sampling: false

   Se a sua aplicação se basear em microsserviços, tem de incluir trace_sampling: false em todos os ficheiros app.yaml.

2. Se não atualizou a CLI do Google Cloud recentemente, execute o seguinte comando:

   gcloud components update

3. Guarde o ficheiro (ou os ficheiros) app.yaml.
4. Implemente o código de back-end e o ESP no App Engine:

   gcloud app deploy

Para reativar a amostragem de rastreios:

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

   gcloud app deploy

Compute Engine

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

1. Estabeleça ligação à sua instância de VM:

   gcloud compute ssh [INSTANCE_NAME]

2. Nos sinalizadores ESP para o 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 rastreios:

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

GKE

Para desativar a amostragem de rastreio do ESP no GKE:

1. Abra o ficheiro de manifesto de implementação, denominado deployment.yaml, e adicione o seguinte à secçã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 Kubernetes com o comando kubectl create:

   kubectl create -f deployment.yaml

Para reativar a amostragem de rastreios:

1. Remova a opção --disable_cloud_trace_auto_sampling.
2. Inicie o serviço Kubernetes:

   kubectl create -f deployment.yaml

Se estiver a executar o ESP numa instância de VM do Compute Engine sem um contentor Docker, não existe um par de chave-valor de metadados da instância de VM equivalente para a opção --disable_cloud_trace_auto_sampling. Se quiser desativar a amostragem de rastreio, tem de executar o ESP num contentor.

Um cliente pode forçar o rastreio de um pedido adicionando o cabeçalho X-Cloud-Trace-Context ao pedido, conforme descrito em Forçar o rastreio de um pedido. Se um pedido contiver o cabeçalho X-Cloud-Trace-Context, o ESP envia os dados de rastreio para o Trace, mesmo que tenha desativado a amostragem de rastreio.

Propagação do contexto de rastreio

Para o rastreio distribuído, um cabeçalho de pedido pode conter um contexto de rastreio que especifica um ID de rastreio. O ID de rastreio é usado quando o ESPv2 cria novos intervalos de rastreio e os envia para o Cloud Trace. O ID de rastreio é usado para pesquisar todos os rastreios e juntar intervalos para um único pedido. Se não for especificado nenhum contexto de rastreio no pedido e o rastreio estiver ativado, é gerado um ID de rastreio aleatório para todos os intervalos de rastreio.

No exemplo seguinte, o Cloud Trace correlaciona os intervalos criados pelo ESPv2 (1) com os intervalos criados pelo back-end (2) para um único pedido. Isto ajuda a depurar problemas de latência em todo o sistema:

Para mais detalhes, leia o artigo Conceitos principais do OpenTelemetry: propagação de contexto

Nota: o rastreio distribuído requer que os seus clientes e/ou back-ends suportem o rastreio. Isto está fora do âmbito desta documentação. Recomendamos a utilização do OpenTelemetry.

Cabeçalhos suportados

O ESPv2 suporta os seguintes cabeçalhos de propagação do contexto de rastreio:

• traceparent: o cabeçalho de propagação do contexto de rastreio W3C padrão. Suportado pela maioria das frameworks de rastreio modernas.
• x-cloud-trace-context: cabeçalho de propagação do contexto de rastreio da GCP. Suportado por frameworks de rastreio mais antigos e pelas bibliotecas da Google, mas específico do fornecedor.
• grpc-trace-bin: cabeçalho de propagação do contexto de rastreio usado por back-ends gRPC com a biblioteca de rastreio OpenCensus.

Se estiver a criar uma nova aplicação, recomendamos que use a propagação do contexto de rastreio.traceparent O ESPv2 extrai e propaga este cabeçalho por predefinição. Consulte as opções de inicialização da monitorização ESPv2 para ver detalhes sobre a alteração do comportamento predefinido.

Nota: ao contrário do ESPv2, a propagação do contexto de rastreio no ESP tem de ser ativada manualmente através das opções de arranque. O ESP não suporta o cabeçalho traceparent.