O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Rastrear o tráfego de entrada com o Cloud Trace

Neste documento, explicamos como configurar o rastreamento distribuído para balanceadores de carga de aplicativo usando o Cloud Trace. Crie uma política de telemetria que tenha como destino a regra de encaminhamento do balanceador de carga e, em seguida, visualize os traces resultantes no Cloud Trace.

Os exemplos neste documento usam um aplicativo de e-commerce com a seguinte arquitetura:

Um balanceador de carga de aplicativo externo global que recebe o tráfego de clientes para uma vitrine da Web.
Um balanceador de carga de aplicativo interno regional que encaminha solicitações de finalização de compra da vitrine para serviços internos de carrinho, inventário e pagamento.

Para informações sobre como o trace distribuído funciona, incluindo modos de amostragem e processamento de cabeçalho de contexto de trace, consulte Visão geral do trace distribuído.

Antes de começar

Ative a API Cloud Trace e a API Network Services no seu projeto:

gcloud services enable \
    cloudtrace.googleapis.com \
    networkservices.googleapis.com

Verifique se você tem um balanceador de carga compatível implantado. Para ver mais informações, consulte os seguintes tópicos:
Observação: os balanceadores de carga de aplicativo clássicos não são compatíveis com o rastreamento distribuído.
Anote o nome e o escopo da regra de encaminhamento do balanceador de carga. O escopo da regra de encaminhamento depende do tipo de balanceador de carga:
- Regra de encaminhamento global: usada por balanceadores de carga de aplicativo externos globais e balanceadores de carga de aplicativo internos entre regiões.
- Regra de encaminhamento regional: usada por balanceadores de carga de aplicativo externos regionais e balanceadores de carga de aplicativo internos regionais.
Para listar as regras de encaminhamento no projeto, use o comando gcloud compute forwarding-rules list:
```
gcloud compute forwarding-rules list
```

Funções exigidas

Para receber as permissões necessárias para configurar políticas de telemetria e visualizar traces, peça ao administrador para conceder a você os seguintes papéis do Identity and Access Management (IAM) no projeto:

Para criar, atualizar ou excluir políticas de telemetria: Administrador de rede do Compute (roles/compute.networkAdmin) ou Administrador do Compute (roles/compute.admin)
Para visualizar traces no console do Google Cloud : Usuário do Cloud Trace (roles/cloudtrace.user)

Para permitir que o balanceador de carga grave períodos de trace no Cloud Trace, conceda o papel de agente do Cloud Trace (roles/cloudtrace.agent) no projeto às seguintes contas de serviço:

Agente de serviço do Compute Engine: service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com
Agente de serviço de segurança de rede: service-PROJECT_NUMBER@gcp-sa-networksecurity.iam.gserviceaccount.com
As contas de serviço das cargas de trabalho de back-end, se os back-ends exportarem os próprios períodos para o Cloud Trace. Sem esse papel, o Cloud Trace mostra apenas o período do balanceador de carga, e o trace não contém períodos de back-end.

Substitua PROJECT_NUMBER pelo número do projeto doGoogle Cloud .

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Configuração da política de telemetria

Defina uma política de telemetria em um arquivo YAML que use o seguinte formato:

name: "projects/PROJECT_ID/locations/LOCATION/telemetryPolicies/POLICY_NAME"
displayName: "DISPLAY_NAME"
telemetryTarget:
  resources:
  - "FORWARDING_RULE_URI"
tracingConfiguration:
  samplingRate: SAMPLING_RATE
  parentBasedSampling:
    enabled: ENABLE_PARENT_BASED_SAMPLING
    samplingRate: PARENT_BASED_SAMPLING_RATE

A tabela a seguir descreve os campos em uma política de telemetria:

Campo	Descrição
`name`	O nome do recurso da política de telemetria. Substitua: `PROJECT_ID`: o ID do seu projeto do Google Cloud . `LOCATION`: o local da política de telemetria, que precisa corresponder ao escopo das regras de encaminhamento que a política segmenta. Para regras de encaminhamento globais, use `global`. Para regras de encaminhamento regionais, use a região da regra de encaminhamento, como `us-central1`. `POLICY_NAME`: o nome da política de telemetria. O nome precisa ter de 4 a 63 caracteres, começar com uma letra minúscula, conter apenas letras minúsculas, números e hifens e terminar com uma letra minúscula ou um número.
`displayName`	Opcional. Um nome legível por humanos (`DISPLAY_NAME`) para a política de telemetria.
`telemetryTarget.resources`	Uma lista dos nomes de recursos completos (`FORWARDING_RULE_URI`) das regras de encaminhamento a que a política se aplica. É possível especificar até 50 recursos. Use um dos seguintes formatos: Regra de encaminhamento global: `//compute.googleapis.com/projects/PROJECT_ID/global/forwardingRules/FORWARDING_RULE_NAME` Regra de encaminhamento regional: `//compute.googleapis.com/projects/PROJECT_ID/regions/REGION/forwardingRules/FORWARDING_RULE_NAME` Substitua: `FORWARDING_RULE_NAME`: o nome da regra de encaminhamento `REGION`: a região da regra de encaminhamento, como `us-central1`
`tracingConfiguration.samplingRate`	A proporção de solicitações a serem rastreadas (`SAMPLING_RATE`), especificada como um valor de `0.0` (0%) a `1.0` (100%). Por exemplo, `0.01` faz uma amostragem de 1% das solicitações. O valor padrão é `0.0`.
`tracingConfiguration.parentBasedSampling.enabled`	Opcional. Se o balanceador de carga respeita a flag de amostragem no cabeçalho `traceparent` do W3C (`ENABLE_PARENT_BASED_SAMPLING`) é `true` ou `false`. O valor padrão é `false`. Compatível apenas com balanceadores de carga de aplicativo internos.
`tracingConfiguration.parentBasedSampling.samplingRate`	Opcional. A proporção de solicitações de amostragem upstream a serem rastreadas (`PARENT_BASED_SAMPLING_RATE`), especificada como um valor de `0.0` a `1.0`. Por exemplo, `1.0` rastreia todas as solicitações que um cliente ou serviço upstream já amostrou.

Configurar o trace para um balanceador de carga externo

Neste exemplo, configuramos a amostragem probabilística na regra de encaminhamento de um balanceador de carga de aplicativo externo global para uma vitrine de e-commerce. Uma taxa de amostragem de 0.01 rastreia 1% das solicitações, o que captura a latência e os erros de borda, mantendo os custos de ingestão do Cloud Trace previsíveis durante o tráfego intenso.

Crie um arquivo YAML chamado storefront-tracing-policy.yaml:
```
cat <<EOF > storefront-tracing-policy.yaml
name: "projects/PROJECT_ID/locations/global/telemetryPolicies/storefront-tracing-policy"
displayName: "Tracing policy for the storefront load balancer"
telemetryTarget:
  resources:
    - "//compute.googleapis.com/projects/PROJECT_ID/global/forwardingRules/FORWARDING_RULE_NAME"
tracingConfiguration:
  samplingRate: 0.01
EOF
```
Substitua:
- PROJECT_ID: o ID do projeto do Google Cloud
- FORWARDING_RULE_NAME: o nome da regra de encaminhamento global do balanceador de carga.
Para um balanceador de carga de aplicativo externo regional, substitua global no nome da política pela região da regra de encaminhamento e use o formato de regra de encaminhamento regional.

Importe a política de telemetria usando o comando gcloud beta network-services telemetry-policies import:

gcloud beta network-services telemetry-policies import storefront-tracing-policy \
    --source=storefront-tracing-policy.yaml \
    --location=global

Configurar o trace para um balanceador de carga interno

Neste exemplo, configuramos um balanceador de carga de aplicativo interno regional para serviços internos de finalização de compra e pagamento. A política usa as seguintes configurações de amostragem:

Uma referência samplingRate de 0.01 (1%) para solicitações que não têm uma decisão de amostragem upstream.
Amostragem baseada em pai com um samplingRate de 1.0 (100%), para que cada solicitação de finalização de compra que já tenha sido amostrada na vitrine ou por qualquer serviço upstream seja rastreada pelo balanceador de carga interno.

Para configurar a política, faça o seguinte:

Crie um arquivo YAML chamado checkout-tracing-policy.yaml:

cat <<EOF > checkout-tracing-policy.yaml
name: "projects/PROJECT_ID/locations/REGION/telemetryPolicies/checkout-tracing-policy"
displayName: "Tracing policy for the internal checkout load balancer"
telemetryTarget:
  resources:
    - "//compute.googleapis.com/projects/PROJECT_ID/regions/REGION/forwardingRules/FORWARDING_RULE_NAME"
tracingConfiguration:
  samplingRate: 0.01
  parentBasedSampling:
    enabled: true
    samplingRate: 1.0
EOF

Substitua:

PROJECT_ID: o ID do projeto do Google Cloud
REGION: a região da regra de encaminhamento, como us-central1
FORWARDING_RULE_NAME: o nome da regra de encaminhamento regional do balanceador de carga.

Para um balanceador de carga de aplicativo interno entre regiões, use global como o local no nome da política e use o formato de regra de encaminhamento global.

Importe a política de telemetria:

gcloud beta network-services telemetry-policies import checkout-tracing-policy \
    --source=checkout-tracing-policy.yaml \
    --location=REGION

Verificar a política de telemetria

Para verificar se a política de telemetria existe e segmenta as regras de encaminhamento corretas, use o comando gcloud beta network-services telemetry-policies describe:

gcloud beta network-services telemetry-policies describe POLICY_NAME \
    --location=LOCATION

Substitua:

POLICY_NAME: o nome da política de telemetria.
LOCATION: global ou a região da política de telemetria

Para listar todas as políticas de telemetria em um local, use o comando gcloud beta network-services telemetry-policies list:

gcloud beta network-services telemetry-policies list \
    --location=LOCATION

Atualizar uma política de telemetria

Para alterar as configurações de amostragem ou aplicar a mesma política a outras regras de encaminhamento, faça o seguinte:

Edite o arquivo YAML da política. Por exemplo, para aplicar a política de vitrine a várias regras de encaminhamento global, adicione cada regra de encaminhamento à lista telemetryTarget.resources:

telemetryTarget:
  resources:
    - "//compute.googleapis.com/projects/PROJECT_ID/global/forwardingRules/storefront-https-fr"
    - "//compute.googleapis.com/projects/PROJECT_ID/global/forwardingRules/cart-https-fr"

Importe a política atualizada:

gcloud beta network-services telemetry-policies import POLICY_NAME \
    --source=POLICY_FILE \
    --location=LOCATION

Substitua POLICY_FILE pelo caminho para o arquivo YAML da política.

Ver traces

Depois de configurar o trace e enviar tráfego pelo balanceador de carga, visualize os traces no console do Google Cloud :

No console do Google Cloud , acesse a página Análise de traces.

Acessar o Explorador de traces
Selecionar o projeto Google Cloud .
No campo Filtro, insira um filtro para encontrar os traces que você quer inspecionar. Por exemplo, ID do atributo ou limite de latência.
Se quiser, para analisar um trace específico, acesse a barra de ferramentas, clique em ID do trace e insira o ID.
Clique em um trace para ver os períodos dele nas visualizações de linha do tempo e de gráfico.
Inspecione o período do balanceador de carga para ver detalhes como a duração total e o back-end que atendeu à solicitação.

Para mais informações sobre como usar o Trace Explorer, consulte Encontrar e explorar traces.

Correlacionar traces com registros e métricas

É possível correlacionar períodos de trace do balanceador de carga com registros e métricas de solicitação para isolar a origem da latência ou dos erros.

Correlacionar traces com registros

Se você ativar a geração de registros no serviço de back-end, o balanceador de carga vai adicionar um campo trace a cada entrada de registro de uma solicitação de amostra. O campo usa o seguinte formato:

projects/PROJECT_ID/traces/TRACE_ID

Ver um trace de uma entrada de registro do balanceador de carga

No console do Google Cloud , acesse a página Análise de registros.

Acessar a Análise de registros
Abra uma entrada de registro do balanceador de carga.
No resumo da entrada de registro, clique no ícone de trace.
Selecione Ver detalhes do trace.

O trace é aberto na página Explorador de traces.

Ver registros do balanceador de carga de um trace

No console do Google Cloud , acesse a página Análise de traces.

Acessar o Explorador de traces
Clique em um trace para abrir o painel Detalhes.
Clique em Ver registros.

As entradas de registro do balanceador de carga para a solicitação são exibidas.

Correlacionar traces com métricas

Compare picos de latência nas métricas do balanceador de carga com detalhamentos de períodos de trace para determinar se a latência se origina no balanceador de carga ou no back-end. É possível conferir e consultar essas métricas no Metrics Explorer no Cloud Monitoring. Use as seguintes métricas:

Balanceador de carga de aplicativo externo global: loadbalancing.googleapis.com/https/total_latencies e loadbalancing.googleapis.com/https/backend_latencies
Balanceador de carga de aplicativo externo regional: loadbalancing.googleapis.com/https/external/regional/total_latencies
Balanceador de carga de aplicativo interno: loadbalancing.googleapis.com/https/internal/total_latencies

Desativar rastreamento

Para interromper o rastreamento de solicitações de um balanceador de carga, siga um destes procedimentos:

Remova a regra de encaminhamento da lista telemetryTarget.resources da política e importe a política atualizada.
Exclua a política de telemetria usando o comando gcloud beta network-services telemetry-policies delete:
```
gcloud beta network-services telemetry-policies delete POLICY_NAME \
    --location=LOCATION
```

Práticas recomendadas

Considere as práticas recomendadas a seguir ao configurar o rastreamento distribuído:

Defina as taxas de amostragem de acordo com o volume de tráfego: para cargas de trabalho de produção de alto tráfego, use um samplingRate de 0.01 (1%) ou 0.001 (0,1%) para equilibrar a observabilidade com os custos de ingestão do Cloud Trace.
Use a amostragem baseada em pai para arquiteturas de vários níveis: em balanceadores de carga de aplicativo internos, ative a amostragem baseada em pai para que as solicitações amostradas upstream sejam rastreadas em cada salto interno.
Instrumente seus back-ends: use um SDK do OpenTelemetry com o propagador de contexto de traces do W3C nos serviços de back-end para que os períodos de back-end se juntem ao trace iniciado pelo balanceador de carga.

Resolver problemas

Nesta seção, descrevemos problemas comuns e as soluções para eles.

Os traces não aparecem no Cloud Trace

Se os traces não aparecerem no Cloud Trace, faça o seguinte:

Verifique se a API Cloud Trace está ativada no seu projeto:

gcloud services enable cloudtrace.googleapis.com \
    --project=PROJECT_ID

Verifique se o papel de agente do Cloud Trace (roles/cloudtrace.agent) foi concedido às contas de serviço listadas em Papéis necessários.
Verifique se a política de telemetria existe no local correto e se ela segmenta a regra de encaminhamento correta. Para mais informações, consulte Verificar a política de telemetria.
Verifique o samplingRate configurado. Se o volume de tráfego ou a taxa de amostragem for baixa, o balanceador de carga pode não capturar os traces imediatamente. Para confirmar se o rastreamento funciona, defina temporariamente samplingRate como 1.0 e restaure a taxa de produção quando terminar o teste.

Os períodos de trace estão desconectados ou incompletos

Se os períodos do balanceador de carga aparecerem como traces raiz separados, em vez de fazerem parte dos traces do aplicativo, faça o seguinte:

Para balanceadores de carga de aplicativo internos, verifique se a amostragem baseada em pai está ativada (parentBasedSampling.enabled: true) na política de telemetria.
Verifique se as contas de serviço das cargas de trabalho do cliente e do back-end têm o papel de agente do Cloud Trace (roles/cloudtrace.agent) para que os períodos possam ser exportados para o Cloud Trace.
Verifique se os aplicativos usam um SDK do OpenTelemetry com a propagação de contexto de traces do W3C ativada, para que o cabeçalho traceparent seja propagado entre os limites do serviço. Para mais informações, consulte a documentação de propagação de contexto do OpenTelemetry.