Como ativar o rastreamento distribuído

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Nesta página, mostramos as etapas necessárias para configurar rastreamento distribuído para o ambiente de execução da Apigee. Se você não estiver familiarizado com o uso de sistemas de rastreamento distribuídos e quiser mais informações, consulte Noções básicas sobre rastreamento distribuído.

Para mais informações sobre os termos usados nesta página, consulte a visão geral do Cloud Trace.

Introdução

Os sistemas de rastreamento distribuído permitem rastrear uma solicitação em um sistema de software distribuído em vários aplicativos, serviços e bancos de dados, além de intermediários como proxies. Esses sistemas de rastreamento geram relatórios que mostram o tempo gasto por uma solicitação em cada etapa. Os relatórios de rastreamento também podem fornecer uma visão granular dos vários serviços chamados durante uma solicitação, permitindo uma compreensão mais profunda do que acontece em cada etapa do sistema de software.

A ferramenta de trace no Apigee Edge e a ferramenta de depuração no Apigee são úteis para resolver problemas e monitorar os proxies de API. No entanto, essas ferramentas não enviam dados para servidores de rastreamento distribuído, como o Cloud Trace, o Jaeger ou um coletor OpenTelemetry.

Para ver os dados do ambiente de execução da Apigee em um relatório de rastreamento distribuído, você precisa ativar explicitamente o rastreamento distribuído no ambiente de execução da Apigee. Depois que o rastreamento é ativado, o ambiente de execução pode enviar dados de trace para servidores de rastreamento distribuído e participar de um trace existente. Assim, é possível visualizar dados de dentro e fora do ecossistema da Apigee em um único local.

É possível ver as seguintes informações nos relatórios de rastreamento distribuído:

  • Tempo de execução de um fluxo inteiro.
  • Horário em que a solicitação é recebida.
  • Horário em que a solicitação é enviada para o destino.
  • Horário em que a resposta é recebida no destino.
  • Tempo de execução de cada política em um fluxo.
  • Chamadas de tempo de execução e fluxos de destino.
  • Horário em que a resposta é enviada ao cliente.

No relatório de rastreamento distribuído, é possível ver os detalhes de execução dos fluxos como períodos. Um período refere-se ao tempo gasto por um fluxo em um trace. O tempo necessário para executar um fluxo é exibido como um agregado do tempo necessário para executar cada política no fluxo. É possível ver cada um dos seguintes fluxos como períodos individuais:

Fase Endpoint Flow
Solicitação Proxy Pré-fluxo
Pós-fluxo
Destino Pré-fluxo
Pós-fluxo
Resposta Proxy Pré-fluxo
Pós-fluxo
Destino Pré-fluxo
Pós-fluxo

Depois de ativar o rastreamento distribuído, o ambiente de execução da Apigee rastreará um conjunto de variáveis predefinidas por padrão. Saiba mais em Variáveis de trace padrão no relatório de rastreamento. Use a política TraceCapture para ampliar o comportamento padrão do ambiente de execução e rastrear outros fluxos, políticas ou variáveis personalizadas. Para saber mais, consulte a política TraceCapture.

Variáveis de trace padrão no relatório de rastreamento

Depois que o rastreamento distribuído for ativado, será possível visualizar o seguinte conjunto de variáveis predefinidas no relatório de rastreamento. As variáveis são visíveis nos seguintes períodos:

  • RESP_SENT: esse período é adicionado depois que uma resposta é recebida do servidor de destino. Ele carrega os atributos do lado de destino listados em Variáveis no período RESP_SENT.
  • PROXY_POST_RESP_SENT: Esse período é adicionado após o envio da resposta do proxy ao cliente. Ele transmite os atributos do lado do proxy listados em Variáveis no intervalo PROXY_POST_RESP_SENT.
  • EVENT_FLOW_RESP e EVENT_FLOW_END: esses intervalos são adicionados para proxies de API que processam respostas de streaming de eventos enviados pelo servidor (SSE). EVENT_FLOW_RESP marca o fluxo de resposta do SSE (executado uma vez por mensagem de resposta). EVENT_FLOW_END marca o fim do fluxo de SSE. Esses intervalos não têm atributos padrão. Eles aparecem no rastreamento como intervalos nomeados para tornar as fases de SSE do proxy visíveis no relatório de rastreamento.

Atributos de período padrão (OpenTelemetry)

Quando você usa o OpenTelemetry, cada período emitido pelo ambiente de execução do Apigee inclui os seguintes atributos padrão, além das variáveis específicas do período descritas nas seções a seguir:

Atributo Descrição
apigee.proxy.name Identifica o proxy de API pai a que o intervalo está associado.
cloud.provider O provedor de nuvem que hospeda o ambiente de execução do Apigee. Sempre gcp.
cloud.resource.id Os detalhes da organização e do ambiente associados ao período.
gcp.project_id O ID do projeto Google Cloud associado ao intervalo.

Variáveis no período RESP_SENT

As variáveis a seguir ficam visíveis no período RESP_SENT:

Variável Atributo Descrição
REQUEST_URL request.url URL completo da solicitação do cliente recebida pelo proxy.
REQUEST_VERB request.verb Verbo HTTP da solicitação do cliente recebida (por exemplo, GET ou POST).
RESPONSE_STATUS_CODE response.status.code Código de status da resposta retornado pelo servidor de destino.
ROUTE_NAME route.name Nome da regra de rota que selecionou o destino para esta solicitação.
ROUTE_TARGET route.target Nome do endpoint de destino selecionado pela regra de rota.
TARGET_BASE_PATH target.basepath Parte do caminho base do URL de destino.
TARGET_HOST target.host Nome do host do servidor de destino contatado pelo proxy.
TARGET_IP target.ip Endereço IP resolvido do servidor de destino.
TARGET_NAME target.name Nome do endpoint de destino definido no proxy de API.
TARGET_PORT target.port Porta TCP usada para se conectar ao servidor de destino.
TARGET_RECEIVED_END_TIMESTAMP target.received.end.timestamp Carimbo de data/hora (milissegundos de época) em que o proxy terminou de receber a resposta do servidor de destino.
TARGET_RECEIVED_START_TIMESTAMP target.received.start.timestamp Carimbo de data/hora (milissegundos de época) em que o proxy começou a receber a resposta do servidor de destino.
TARGET_SENT_END_TIMESTAMP target.sent.end.timestamp Carimbo de data/hora (milissegundos da época) em que o proxy terminou de enviar a solicitação ao servidor de destino.
TARGET_SENT_START_TIMESTAMP target.sent.start.timestamp Carimbo de data/hora (milissegundos da época) em que o proxy começou a enviar a solicitação ao servidor de destino.
TARGET_SSL_ENABLED target.ssl.enabled Booleano que indica se a conexão com o servidor de destino usou TLS.
TARGET_URL target.url URL completo do servidor de destino contatado pelo proxy.

Variáveis no período PROXY_POST_RESP_SENT

As variáveis a seguir ficam visíveis no período PROXY_POST_RESP_SENT:

Variável Atributo Descrição
API_PROXY_REVISION apiproxy.revision Número da revisão do proxy de API que processou a solicitação.
APIPROXY_NAME apiproxy.name Nome do proxy de API que processou a solicitação.
CLIENT_RECEIVED_END_TIMESTAMP client.received.end.timestamp Carimbo de data/hora (milissegundos da época) em que o proxy terminou de receber a solicitação do cliente.
CLIENT_RECEIVED_START_TIMESTAMP client.received.start.timestamp Carimbo de data/hora (milissegundos de época) em que o proxy começou a receber a solicitação do cliente.
CLIENT_SENT_END_TIMESTAMP client.sent.end.timestamp Carimbo de data/hora (milissegundos de época) em que o proxy terminou de enviar a resposta ao cliente.
CLIENT_SENT_START_TIMESTAMP client.sent.start.timestamp Carimbo de data/hora (milissegundos de época) em que o proxy começou a enviar a resposta ao cliente.
ENVIRONMENT_NAME environment.name Nome do ambiente da Apigee em que o proxy foi executado.
FAULT_SOURCE message.header.X-Apigee-fault-source Origem da falha quando ocorre um erro durante a execução do proxy. Preenchido apenas em fluxos de erro.
IS_ERROR is.error Booleano que indica se a execução do proxy terminou em um fluxo de erros.
MESSAGE_ID message.id Identificador exclusivo atribuído pela Apigee à solicitação, útil para correlacionar registros e intervalos de rastreamento.
MESSAGE_STATUS_CODE message.status.code Código de status da resposta final, incluindo chamadas sem destinos e fluxos de erro.
PROXY_BASE_PATH proxy.basepath Caminho base do proxy de API que correspondeu à solicitação recebida.
PROXY_CLIENT_IP proxy.client.ip Endereço IP do cliente que enviou a solicitação ao proxy.
PROXY_NAME proxy.name Nome do endpoint de proxy no proxy de API que processou a solicitação.
PROXY_PATH_SUFFIX proxy.pathsuffix Parte do caminho do URL da solicitação que segue o caminho de base do proxy.
PROXY_URL proxy.url URL completo do endpoint de proxy recebido do cliente.

Sistemas de rastreamento distribuído com suporte

É possível configurar o ambiente de execução da Apigee para enviar dados de rastreamento aos seguintes sistemas de rastreamento distribuído:

Sistemas de rastreamento distribuído Descrição
Cloud Trace com OpenTelemetry

Ideal para usuários que querem uma configuração simples com o OpenTelemetry e cujo back-end de rastreamento principal ou único é o Cloud Trace.

Para enviar dados de traces ao Cloud Trace com o OpenTelemetry, faça o seguinte:

  1. Configure o ambiente de execução da Apigee para o Cloud Trace.
  2. Ative o rastreamento distribuído para o Cloud Trace com o OpenTelemetry.
Coletor do OpenTelemetry

Gerencie seu próprio OpenTelemetry Collector para controlar a coleta e o processamento de dados de rastreamento. Isso é ideal se você precisar enviar dados para vários sistemas (incluindo os que não são do Google) ou personalizar como os dados são tratados, agrupados ou aprimorados.

Para enviar dados de rastreamento a um coletor do OpenTelemetry, faça o seguinte:

  1. Implante e gerencie um OpenTelemetry Collector, conforme descrito em OpenTelemetry Collector.
  2. Ative o rastreamento distribuído para um OpenTelemetry Collector.

Consulte Considerações ao usar um coletor do OpenTelemetry para saber mais sobre os requisitos de capacidade de rede, TLS, transporte e custo que você precisa atender antes de ativar essa opção.
Cloud Trace com OpenCensus

Para enviar dados de traces ao Cloud Trace com o OpenCensus, faça o seguinte:

  1. Configure o ambiente de execução da Apigee para o Cloud Trace (OpenCensus).
  2. Ative o rastreamento distribuído para o Cloud Trace com o OpenCensus.
Jaeger com OpenCensus

Para enviar dados de rastreamento ao Jaeger com o OpenCensus, ative o rastreamento distribuído para o Jaeger.

Variáveis de ambiente

Os procedimentos nesta página usam as seguintes variáveis de ambiente. Recomendamos que você defina essas variáveis no seu ambiente antes de começar.

TOKEN="Authorization: Bearer $(gcloud auth application-default print-access-token)"
ENV_NAME=YOUR_ENVIRONMENT_NAME
PROJECT_ID=YOUR_GOOGLE_CLOUD_PROJECT_ID

Em que:

  • TOKEN define o cabeçalho Authentication com um token do portador. Você usará esse cabeçalho ao chamar as APIs da Apigee. Saiba mais na página de referência do comando print-access-token.
  • ENV_NAME é o nome de um ambiente na organização.
  • PROJECT_ID é o ID do projeto do Google Cloud .

Configurar o ambiente de execução da Apigee para OpenTelemetry ou OpenCensus

O ambiente de execução da Apigee é compatível com dois padrões de rastreamento: OpenTelemetry (recomendado para novas implantações) e OpenCensus. Escolha o padrão de rastreamento adequado para seu ambiente e siga as etapas de configuração correspondentes na guia abaixo.

Para o OpenTelemetry, o ambiente de execução da Apigee reconhece o formato de cabeçalho W3C, incluindo os cabeçalhos traceparent e tracestate. Ele ignora os cabeçalhos B3, mesmo que estejam presentes na solicitação.

Configurar ambientes de execução da Apigee para o Cloud Trace (OpenTelemetry)

Tanto o ambiente de execução do Apigee quanto o ambiente de execução híbrido da Apigee são compatíveis com o rastreamento distribuído usando o Cloud Trace. Se você estiver usando um OpenTelemetry Collector gerenciado pelo cliente, pule esta seção e acesse Como ativar o rastreamento distribuído para um OpenTelemetry Collector.

Configurar o ambiente de execução do ApigeeX para o Cloud Trace

Para configurar o ambiente de execução do Apigee para o Cloud Trace, seu projeto Google Cloud precisa ter as seguintes APIs ativadas:

Ao ativar essas APIs, seu projeto do Google Cloud pode receber dados de rastreamento do OpenTelemetry de fontes autenticadas.

Para ativar as APIs, faça o seguinte:

  1. No console do Google Cloud , acesse APIs e serviços:

    Acessar APIs e Serviços

  2. Clique em Ativar APIs e serviços.
  3. Ative a API Cloud Trace, a API Telemetry e a API Service Usage.

Além de ativar as APIs, é necessário conceder os seguintes papéis à conta do agente de serviço:

  • roles/telemetry.tracesWriter
  • roles/serviceusage.serviceUsageConsumer

A conta de serviço específica depende do seu ambiente da Apigee:

  • Apigee (não híbrido): conceda os papéis ao agente de serviço da Apigee. A conta do agente de serviço geralmente tem o formato: service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com.
  • Apigee híbrida:conceda os papéis à conta de serviço do ambiente de execução conforme descrito em Configurar o ambiente de execução híbrido da Apigee para o Cloud Trace.

Consulte Conceder um papel do IAM usando o console do Google Cloud .

Configurar o ambiente de execução híbrido da Apigee para o Cloud Trace

Para configurar o ambiente de execução híbrido da Apigee para o Cloud Trace, ative as APIs descritas em Configurar o ambiente de execução da Apigee para o Cloud Trace.

Além de ativar as APIs, você precisa adicionar a conta de serviço iam.gserviceaccount.com para usar o Cloud Trace com o ambiente de execução híbrido. Para adicionar a conta de serviço com as funções e chaves necessárias, execute as seguintes etapas:

  1. Crie uma nova conta de serviço: 
    gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID
  2. Adicione vinculações de política do IAM à conta de serviço para conceder a ela os papéis necessários: 
    gcloud projects add-iam-policy-binding \
    PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/telemetry.tracesWriter --project PROJECT_ID
     
    gcloud projects add-iam-policy-binding \
    PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/serviceusage.serviceUsageConsumer --project PROJECT_ID
  3. Crie uma chave de conta de serviço: 
    gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
  4. Adicione a conta de serviço ao arquivo overrides.yaml. 
    envs:
 - name: ENV_NAME
   serviceAccountPaths:
     runtime: apigee-runtime.json
     synchronizer: apigee-sync.json
     udca: apigee-udca.json
  5. Aplique as mudanças ao ambiente de execução usando Helm: 
    helm upgrade ENV_NAME apigee-env/ \
    --namespace APIGEE_NAMESPACE \
    --set env=ENV_NAME \
    --atomic \
    -f overrides.yaml

Ativar o rastreamento distribuído (OpenTelemetry)

Antes de ativar o rastreamento distribuído, crie as variáveis de ambiente necessárias.

Ativar o rastreamento distribuído para o Cloud Trace com o OpenTelemetry

O exemplo a seguir mostra como ativar o rastreamento distribuído para o Cloud Trace com o OpenTelemetry:

  1. Execute esta chamada de API da Apigee: 
    curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter":"OPEN_TELEMETRY_CLOUD_TRACE",
          "endpoint": "'"$PROJECT_ID"'",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05},
          "traceProtocol": "OTLP"
        }'

    O corpo da solicitação de exemplo consiste nos seguintes elementos:

    • Para oferecer suporte ao Cloud Trace com o OpenTelemetry, o parâmetro exporter é definido como OPEN_TELEMETRY_CLOUD_TRACE e o parâmetro traceProtocol é definido como OTLP.
    • O samplingRate é definido como 0,05. Isso significa que aproximadamente 5% das chamadas de API são enviadas para o rastreamento distribuído. No OpenTelemetry, é possível especificar uma taxa de amostragem de até 1.0 (100%). Para mais informações, consulte Considerações sobre desempenho.
    • O parâmetro endpoint é definido como o Google Cloud ID do projeto que vai receber os dados de rastreamento (uma string de ID do projeto simples, não um URL).

    Uma resposta bem-sucedida é semelhante a esta:

    {
  "exporter": "OPEN_TELEMETRY_CLOUD_TRACE",
  "endpoint": "my-gcp-project-id",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  },
  "traceProtocol": "OTLP"
}

Ativar o rastreamento distribuído para um coletor do OpenTelemetry

Para ativar o rastreamento distribuído em um coletor OpenTelemetry gerenciado pelo cliente, execute esta chamada de API da Apigee:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter":"OPEN_TELEMETRY_COLLECTOR",
          "endpoint": "https://my-otel-collector.example.com:4318/v1/traces",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05},
          "traceProtocol": "OTLP"
        }'

O corpo da solicitação de exemplo consiste nos seguintes elementos:

  • Para oferecer suporte a um OpenTelemetry Collector gerenciado pelo cliente, o parâmetro exporter é definido como OPEN_TELEMETRY_COLLECTOR e o parâmetro traceProtocol é definido como OTLP.
  • O parâmetro endpoint é definido como o URL HTTPS completo do endpoint de ingestão OTLP do coletor do OpenTelemetry (por exemplo, https://my-otel-collector.example.com:4318/v1/traces). Ao contrário do exportador do Cloud Trace, que usa um ID do projeto Google Cloud simples, o exportador OPEN_TELEMETRY_COLLECTOR exige um URL completo que inclua esquema, host, porta e caminho.
  • O samplingRate está definido como 0,05. Isso significa que aproximadamente 5% das chamadas de API são enviadas para o rastreamento distribuído. Veja mais informações em Considerações sobre desempenho.

Uma resposta bem-sucedida é semelhante a esta:

{
  "exporter": "OPEN_TELEMETRY_COLLECTOR",
  "endpoint": "https://my-otel-collector.example.com:4318/v1/traces",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  },
  "traceProtocol": "OTLP"
}

Considerações ao usar um coletor do OpenTelemetry

Antes de ativar o rastreamento distribuído em um coletor OpenTelemetry gerenciado pelo cliente, revise os requisitos a seguir.

Acessibilidade da rede

  • Verifique se o Apigee pode acessar o OpenTelemetry Collector.
  • Para acessar um coletor que não está exposto na Internet pública, use o Private Service Connect (PSC).
  • Para a Apigee híbrida, se um proxy de encaminhamento estiver configurado, os dados de rastreamento passarão por ele até o OpenTelemetry Collector e seu back-end.

Protocolo de transporte

Somente o transporte OTLP/HTTP é compatível com coletores do OpenTelemetry (porta 4318 e caminho /v1/traces pela convenção OTLP). OTLP/gRPC (porta 4317) não é compatível.

TLS e mTLS

  • Validação do certificado do servidor TLS:quando o endpoint do coletor usa https://, o ambiente de execução do Apigee valida o certificado do servidor em relação ao truststore padrão do JDK, que contém o conjunto padrão de autoridades de certificação publicamente confiáveis. Portanto, seu coletor precisa apresentar um certificado emitido por uma CA publicamente confiável. Certificados autoassinados e emitidos por uma CA particular não são aceitos no Apigee. No Apigee híbrido, é possível adicionar uma CA particular ao truststore do processador de mensagens usando a configuração da JVM.
  • O TLS mútuo (mTLS) não é compatível:o Apigee não apresenta um certificado de cliente ao coletor. Se o coletor exigir autenticação de certificado de cliente, coloque um proxy de encerramento de TLS na frente dele que não exija mTLS.

Restrições de URL do endpoint

O valor endpoint do coletor é validado no lado do servidor no momento da configuração. Para evitar a sondagem de falsificação de solicitação do lado do servidor (SSRF) da infraestrutura interna Google Cloud , as solicitações com qualquer uma das seguintes formas de endpoint são rejeitadas com um erro FailedPrecondition:

  • Esquemas diferentes de http ou https.
  • URLs que incorporam credenciais (por exemplo, https://user:password@host:4318/v1/traces). As credenciais não podem ser fornecidas no URL do endpoint.
  • Nomes de host localhost, metadata ou metadata.google.internal.
  • Literais de IP que resolvem para loopback (127.0.0.0/8, ::1), link-local (169.254.0.0/16, incluindo o endereço de metadados da nuvem 169.254.169.254), não especificados (0.0.0.0, ::) ou intervalos de rede privada do IETF (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16).
  • Codificações numéricas de IPv4 que são decodificadas para qualquer um dos endereços bloqueados acima. Por exemplo, http://2130706433/, http://0x7f000001/ e http://0177.0.0.1/ são decodificados para 127.0.0.1 e são rejeitados.

Custo

Você é responsável por todos os custos relacionados ao OpenTelemetry Collector.

OpenCensus

Configurar ambientes de execução da Apigee para o Cloud Trace (OpenCensus)

Tanto o ambiente de execução do Apigee quanto o ambiente de execução híbrido da Apigee são compatíveis com o rastreamento distribuído usando o Cloud Trace com o OpenCensus. Se você estiver usando o Jaeger, pule esta seção e acesse Como ativar o rastreamento distribuído para o Jaeger com o OpenCensus.

Configurar o ambiente de execução da Apigee para o Cloud Trace

Para configurar o ambiente de execução do Apigee para o Cloud Trace, seu projeto Google Cloud precisa ter a API Cloud Trace ativada.

Para ativar a API, faça o seguinte:

  1. No console do Google Cloud , acesse APIs e serviços:

    Acessar APIs e Serviços

  2. Clique em Ativar APIs e serviços.
  3. Ative a API Cloud Trace.

Configurar o ambiente de execução híbrido da Apigee para o Cloud Trace

Para configurar o ambiente de execução híbrido da Apigee para o Cloud Trace, ative a API Cloud Trace.

Além de ativar a API, você precisa adicionar a conta de serviço iam.gserviceaccount.com para usar o Cloud Trace com o ambiente de execução híbrido. Para adicionar a conta de serviço com o papel e as chaves roles/cloudtrace.agent necessários, siga estas etapas:

  1. Crie uma nova conta de serviço: 
    gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID
  2. Adicione uma vinculação de política do IAM à conta de serviço: 
    gcloud projects add-iam-policy-binding \
    PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/cloudtrace.agent --project PROJECT_ID
  3. Crie uma chave de conta de serviço e atualize seu overrides.yaml conforme descrito nas etapas a seguir.
  4. Crie uma chave de conta de serviço: 
    gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
  5. Adicione a conta de serviço ao arquivo overrides.yaml. 
    envs:
 - name: ENV_NAME
   serviceAccountPaths:
     runtime: apigee-runtime.json
     synchronizer: apigee-sync.json
     udca: apigee-udca.json
  6. Aplique as mudanças ao ambiente de execução usando Helm: 
    helm upgrade ENV_NAME apigee-env/ \
    --namespace APIGEE_NAMESPACE \
    --set env=ENV_NAME \
    --atomic \
    -f overrides.yaml

Ativar o rastreamento distribuído (OpenCensus)

Antes de ativar o rastreamento distribuído, crie as variáveis de ambiente necessárias.

Ativar o rastreamento distribuído para o Cloud Trace com o OpenCensus

O exemplo a seguir mostra como ativar o rastreamento distribuído para o Cloud Trace com o OpenCensus:

  1. Execute esta chamada de API da Apigee: 
    curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter":"CLOUD_TRACE",
          "endpoint": "'"$PROJECT_ID"'",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}
        }'

    O corpo da solicitação de exemplo consiste nos seguintes elementos:

    • Para oferecer suporte ao Cloud Trace, o parâmetro exporter é definido como CLOUD_TRACE. O parâmetro traceProtocol, que não está especificado, tem OpenCensus como padrão.
    • O parâmetro endpoint está definido como o projeto Google Cloud para onde você quer enviar o trace.
    • O samplingRate está definido como 0.1. Isso significa que aproximadamente 10% das chamadas de API são enviadas para o rastreamento distribuído. Para o OpenCensus, a taxa de amostragem máxima configurável é 0.5.

    Uma resposta bem-sucedida é semelhante a esta:

    {
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}

Ativar o rastreamento distribuído para o Jaeger com o OpenCensus

O exemplo a seguir mostra como ativar o rastreamento distribuído para o Jaeger:

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig' \
    -X PATCH \
    -H "content-type:application/json" -d '{
    "samplingConfig": {
    "samplingRate": 0.4,
    "sampler": "PROBABILITY"},
    "endpoint": "http://DOMAIN:9411/api/v2/spans",
    "exporter": "JAEGER"
    }'

Neste exemplo:

  • Para oferecer suporte ao Jaeger, o parâmetro exporter é definido como JAEGER. O parâmetro traceProtocol, que não está especificado, tem OpenCensus como padrão.
  • O parâmetro endpoint é definido como o local em que o Jaeger está instalado e configurado.
  • O samplingRate está definido como 0.4. Isso significa que aproximadamente 40% das chamadas de API são enviadas para o rastreamento distribuído.

É esperado um impacto no desempenho quando você ativa o rastreamento distribuído em um ambiente de execução da Apigee. O impacto pode resultar em aumento no uso da memória, nos requisitos de CPU e na latência. A magnitude do impacto depende em parte da complexidade do proxy de API (por exemplo, o número de políticas) e da taxa de amostragem probabilística (definida como samplingRate). Quanto maior a taxa de amostragem, maior o impacto no desempenho.

Para mais informações, consulte Considerações sobre desempenho.

Visualizar a configuração de rastreamento distribuído

Para visualizar a configuração de rastreamento distribuído atual no ambiente de execução, faça login no ambiente de execução e execute o seguinte comando:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig

Ao executar o comando, você vai ver uma resposta semelhante a esta:

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "my-gcp-project-id",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  },
  "revisionId": "7",
  "updateTime": "2026-06-08T14:25:13.512000Z"
}

O revisionId aumenta com cada atualização bem-sucedida, e o updateTime reflete o carimbo de data/hora do servidor da mudança mais recente. Use esses dois campos para confirmar se o plano de controle aceitou uma atualização de configuração. Ambos também são retornados pela resposta PATCH .../traceConfig.

Atualizar a configuração de rastreamento distribuído

O comando a seguir mostra como atualizar a configuração de rastreamento distribuído atual para o Cloud Trace:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.6}
        }'

Ao executar o comando, você vai ver uma resposta semelhante a esta:

{
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.6
  },
  "traceProtocol": "OTLP"
}
 Neste exemplo, a taxa de amostragem foi atualizada para 0.6.

Desativar a configuração de rastreamento distribuído

O exemplo a seguir mostra como desativar o rastreamento distribuído configurado para o Cloud Trace:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "samplingConfig": {"sampler": "OFF"}
        }'

Ao executar o comando, você vai ver uma resposta semelhante a esta:

{
  "samplingConfig": {
    "sampler": "OFF"
  },
  "traceProtocol": "OTLP"
}

Modificar as configurações de trace para proxies de API

Quando você ativa o rastreamento distribuído no ambiente de execução da Apigee, todos os proxies de API no ambiente de execução usam a mesma configuração de rastreamento. No entanto, é possível modificar a configuração de rastreamento distribuído para um proxy de API ou um grupo de proxies de API. Isso oferece um controle mais granular sobre a configuração de rastreamento.

O exemplo a seguir modifica a configuração de rastreamento distribuído para o proxy de API hello-world:

curl -s -H "$TOKEN" \
     'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
     -X POST \
     -H "content-type:application/json" \
     -d '{"apiProxy": "hello-world","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'

É possível substituir a configuração para resolver problemas específicos de um proxy de API sem precisar alterar a configuração de todos os proxies de API.

Atualizar substituições de configurações de trace

Para atualizar uma substituição da configuração de rastreamento de um proxy de API ou grupo de proxies de API, siga estas etapas:

  1. Use o comando a seguir para recuperar as substituições existentes da configuração de rastreamento: 
    curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

    Esse comando retorna algo semelhante à seguinte resposta, que contém um campo "name" que identifica o proxy ou os proxies regidos pela modificação: 

    {
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}
  2. Para atualizar o proxy, use o valor do campo "name" para enviar uma solicitação POST à configuração de substituição para o proxy com os valores de campo atualizados. Por exemplo: 
    curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X POST \
    -H "content-type:application/json" \
    -d '{"apiProxy": "proxy1","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05}}'

Excluir substituições de configuração de trace

Para excluir uma substituição da configuração de rastreamento de um proxy de API ou grupo de proxies de API, siga estas etapas:

  1. Use o comando a seguir para recuperar as substituições existentes da configuração de rastreamento: 
    curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
    -X GET

    Esse comando retorna algo semelhante à seguinte resposta, que contém um campo "name" que identifica o proxy ou os proxies regidos pela modificação: 

    {
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}
  2. Para excluir o proxy, use o valor do campo "name" para enviar uma solicitação DELETE para a configuração de substituição desse proxy com os valores de campo atualizados. Por exemplo: 
    curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
    -X DELETE \

Considerações sobre desempenho

É esperado um impacto no desempenho quando você ativa o rastreamento distribuído em um ambiente de execução da Apigee. O impacto pode resultar em aumento no uso da memória, nos requisitos de CPU e na latência. A magnitude do impacto depende da complexidade do proxy de API (por exemplo, o número de políticas), da taxa de amostragem probabilística (definida como samplingRate) e, principalmente, do volume de tráfego rastreado em relação à capacidade de exportação de períodos por processador de mensagens (MP).

O MP do Apigee tem uma taxa de exportação de períodos finita. Com a configuração padrão, um único MP pode exportar de forma sustentável aproximadamente 820 períodos por segundo. Uma execução típica de proxy de API emite aproximadamente 10 períodos (pré-fluxo do proxy, fluxo de destino, pós-fluxos, políticas anexadas). Assim, um único MP pode rastrear de forma sustentável aproximadamente 82 solicitações por segundo com amostragem de 100% . O escalonamento da contagem de réplicas do MP aumenta o limite agregado de maneira linear.

A tabela a seguir resume o impacto esperado em samplingRate=1.0 (100% de probabilidade) em dois regimes de tráfego:

Regime de tráfego (por MP) Impacto esperado em samplingRate=1.0 Ação recomendada
Trânsito tranquilo (menos de aproximadamente 82 solicitações rastreadas por segundo por MP) A capacidade de processamento cai em aproximadamente 1 a 2%, a latência média aumenta em cerca de 1% e a latência p99 aumenta em aproximadamente 15 a 20%. Negligenciável na prática. Pode ser ativada em 100%.
Tráfego intenso (significativamente acima de aproximadamente 82 solicitações rastreadas por segundo por MP) A capacidade de processamento cai em aproximadamente 14%, a latência média aumenta em aproximadamente 24%, a latência p75 aumenta em aproximadamente 52% e a taxa de erros aumenta em aproximadamente 1 ponto percentual. Diminua samplingRate (por exemplo, para 0.1 ou 0.05) ou escalonar verticalmente a contagem de réplicas do MP para que cada MP atenda a menos solicitações rastreadas por segundo.

Para ambientes com tráfego alto e requisitos de baixa latência, a taxa de amostragem probabilística recomendada é menor ou igual a 10%. Se você quiser usar o rastreamento distribuído para resolver problemas, aumente a amostragem probabilística (samplingRate) apenas para proxies de API específicos usando substituições por proxy.

Detectar intervalos descartados

Se o tráfego rastreado exceder a capacidade de processamento de intervalos do MP do Apigee ou se o destino não puder aceitar o tráfego, os intervalos serão descartados antes de chegarem ao back-end de rastreamento. Para detectar intervalos descartados, use os seguintes indicadores específicos do back-end:

  • Cloud Trace (OPEN_TELEMETRY_CLOUD_TRACE ou CLOUD_TRACE): revise as cotas e os limites do Cloud Trace para o projeto de destino. Erros de cota persistentes resultam em períodos descartados. Monitore o uso da cota da API Cloud Trace no console Google Cloud .
  • OpenTelemetry Collector gerenciado pelo cliente: monitore as métricas padrão do receptor do seu coletor (por exemplo, otelcol_receiver_refused_spans e otelcol_exporter_send_failed_spans) para detectar intervalos rejeitados ou que não são encaminhados para o back-end downstream.

Resolver problemas de rastreamento distribuído

Para resolver problemas de rastreamento distribuído, faça o seguinte:

  • Verifique a configuração de rastreamento distribuído usando a API traceConfig para garantir que ela atenda às suas necessidades.
  • Confirme se a conta de serviço tem as permissões (papéis) corretas do IAM no projeto de destino.
  • Se você estiver usando o Cloud Trace com o OpenTelemetry, verifique os períodos de entrada e os erros de ativação ou cota da API.
  • Se você estiver usando um coletor do OpenTelemetry gerenciado pelo cliente, faça o seguinte:
    • Confirme se o Apigee pode acessar o endpoint do coletor. Verifique a configuração do Private Service Connect (PSC), se usado.
    • Verifique os registros do OpenTelemetry Collector para problemas de dados ou conexão.
    • Verifique se o certificado TLS do coletor é válido.
  • Examine os registros do ambiente de execução da Apigee em busca de erros de exportação de rastreamento.