Ativar o rastreio distribuído

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Pré-visualização

Este produto ou funcionalidade está sujeito aos "Termos de Ofertas de Pré-GA" na secção Termos Gerais do Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Esta página demonstra os passos necessários para configurar o rastreio distribuído para o seu tempo de execução do Apigee. Se está a usar sistemas de rastreio distribuído pela primeira vez e quer mais informações, consulte o artigo Compreender o rastreio distribuído.

Introdução

Os sistemas de rastreio distribuído permitem-lhe acompanhar um pedido num sistema de software distribuído por várias aplicações, serviços e bases de dados, bem como intermediários, como proxies. Estes sistemas de rastreio geram relatórios que mostram o tempo necessário para um pedido em cada passo. Os relatórios de rastreio também podem fornecer uma vista detalhada dos vários serviços chamados durante um pedido, o que permite uma compreensão mais profunda do que acontece em cada passo no seu sistema de software.

A ferramenta de rastreio no Apigee Edge e a ferramenta de depuração no Apigee são úteis para resolver problemas e monitorizar os seus proxies de API. No entanto, estas ferramentas não enviam dados para servidores de rastreio distribuídos, como o Cloud Trace ou o Jaeger. Para ver dados de tempo de execução do Apigee num relatório de rastreio distribuído, tem de ativar explicitamente o rastreio distribuído no tempo de execução do Apigee. Assim que o rastreio estiver ativado, o tempo de execução pode enviar dados de rastreio para servidores de rastreio distribuídos e participar num rastreio existente. Como resultado, pode ver dados de dentro e fora do seu ecossistema do Apigee a partir de uma única localização.

Pode ver as seguintes informações nos relatórios de rastreio distribuído:

• Tempo de execução de um fluxo completo.
• Hora em que o pedido é recebido.
• Hora em que o pedido é enviado para o destino.
• Hora em que a resposta é recebida do destino.
• Tempo de execução de cada política num fluxo.
• Tempo de execução dos pedidos de serviços e fluxos de destino.
• Hora em que a resposta é enviada ao cliente.

No relatório de rastreio distribuído, pode ver os detalhes de execução dos fluxos como intervalos. Um intervalo refere-se ao tempo necessário para um fluxo num rastreio. O tempo necessário para executar um fluxo é apresentado como um agregado do tempo necessário para executar cada política no fluxo. Pode ver cada um dos seguintes fluxos como intervalos individuais:

• Faça um pedido
  • Proxy
    • Preflow
    • PostFlow
  • Objetivo
    • Preflow
    • PostFlow
• Resposta
  • Proxy
    • Preflow
    • PostFlow
  • Objetivo
    • Preflow
    • PostFlow

Depois de ativar o rastreio distribuído, o tempo de execução do Apigee rastreia um conjunto de variáveis predefinidas por predefinição. Para mais informações, consulte o artigo Variáveis de rastreio predefinidas no relatório de rastreio. Pode usar a política TraceCapture para estender o comportamento de tempo de execução predefinido e rastrear variáveis adicionais de fluxo, políticas ou personalizadas. Para mais informações, consulte a política TraceCapture.

Uma chamada API recebida para o Apigee pode conter cabeçalhos de rastreio, uma vez que a chamada faz parte de um rastreio existente. Neste caso, o Apigee participa no rastreio existente e propaga os cabeçalhos para a chamada API de saída. O tempo de execução do Apigee compreende o formato do cabeçalho Zipkin B3. Por conseguinte, reconhece os cabeçalhos x-b3-traceid, x-b3-spanid e x-b3-sampled quando participa num rastreio existente. No entanto, se não existirem cabeçalhos de rastreio numa chamada API recebida, o Apigee adiciona os respetivos cabeçalhos de rastreio e propaga-os para a chamada API de saída. Outros serviços podem aceder aos cabeçalhos e participar na monitorização, se necessário.

Variáveis de rastreio predefinidas no relatório de rastreio

Depois de ativar o rastreio distribuído, pode ver o seguinte conjunto de variáveis predefinidas no relatório de rastreio. As variáveis são visíveis nos seguintes intervalos:

• POST_RESP_SENT: este intervalo é adicionado depois de ser recebida uma resposta do servidor de destino.
• POST_CLIENT_RESP_SENT: este intervalo é adicionado depois de a resposta do proxy ser enviada para o cliente.

Variáveis no intervalo POST_RESP_SENT

As seguintes variáveis estão visíveis no intervalo POST_RESP_SENT:

• REQUEST_URL (request.url)
• REQUEST_VERB (request.verb)
• RESPONSE_STATUS_CODE (response.status.code)
• ROUTE_NAME (route.name)
• ROUTE_TARGET (route.target)
• TARGET_BASE_PATH (target.basepath)
• TARGET_HOST (target.host)
• TARGET_IP (target.ip)
• TARGET_NAME (target.name)
• TARGET_PORT (target.port)
• TARGET_RECEIVED_END_TIMESTAMP (target.received.end.timestamp)
• TARGET_RECEIVED_START_TIMESTAMP (target.received.start.timestamp)
• TARGET_SENT_END_TIMESTAMP (target.sent.end.timestamp)
• TARGET_SENT_START_TIMESTAMP (target.sent.start.timestamp)
• TARGET_SSL_ENABLED (target.ssl.enabled)
• TARGET_URL (target.url)

Variáveis no intervalo POST_CLIENT_RESP_SENT

As seguintes variáveis estão visíveis no intervalo POST_CLIENT_RESP_SENT:

• API_PROXY_REVISION (apiproxy.revision)
• APIPROXY_NAME (apiproxy.name)
• CLIENT_RECEIVED_END_TIMESTAMP (client.received.end.timestamp)
• CLIENT_RECEIVED_START_TIMESTAMP (client.received.start.timestamp)
• CLIENT_SENT_END_TIMESTAMP (client.sent.end.timestamp)
• CLIENT_SENT_START_TIMESTAMP (client.sent.start.timestamp)
• ENVIRONMENT_NAME (environment.name)
• FAULT_SOURCE (message.header + InternalHeaders.FAULT_SOURCE)
• IS_ERROR (is.error)
• MESSAGE_ID (message.id)
• MESSAGE_STATUS_CODE (message.status.code)
• PROXY_BASE_PATH (proxy.basepath)
• PROXY_CLIENT_IP (proxy.client.ip)
• PROXY_NAME (proxy.name)
• PROXY_PATH_SUFFIX (proxy.pathsuffix)
• PROXY_URL (proxy.url)

Sistemas de rastreio distribuído suportados

O tempo de execução do Apigee suporta os seguintes sistemas de rastreio distribuído:

• Cloud Trace
• Jaeger

Pode configurar o tempo de execução do Apigee para enviar dados de rastreio para um Cloud Trace ou um sistema Jaeger.

Uma vez que o rastreio de todas as chamadas API no tempo de execução do Apigee afetaria o desempenho, o Apigee permite-lhe configurar uma taxa de amostragem probabilística. Ao usar a taxa de amostragem, pode especificar o número de chamadas API que são enviadas para o rastreio distribuído. Por exemplo, se especificar a taxa de amostragem como 0.4, significa que 40% das chamadas da API são enviadas para rastreio. Para mais informações, consulte o artigo Considerações sobre o desempenho.

A taxa de amostragem configurável máxima é 0.5.

Configure os tempos de execução do Apigee para o Cloud Trace

O tempo de execução do Apigee e o tempo de execução do Apigee Hybrid suportam o rastreio distribuído através do Cloud Trace. Se estiver a usar o Jaeger, pode ignorar esta secção e avançar para Ativar o rastreio distribuído para o Jaeger.

Configure o tempo de execução do Apigee para o Cloud Trace

Para usar o Cloud Trace com um runtime do Apigee, o seu projeto do Google Cloud tem de ter a API Cloud Trace ativada. Esta definição permite que o seu projeto do Google Cloud receba dados de rastreio de origens autenticadas.

Para confirmar que a API Cloud Trace está ativada, faça o seguinte:

1. Na Google Cloud Console, aceda a APIs e serviços:

   Aceda a APIs e serviços

2. Clique em Ativar APIs e serviços.
3. Na barra de pesquisa, introduza API Trace.
4. Se for apresentado o texto API ativada, significa que esta API já está ativada e não tem de fazer nada. Caso contrário, clique em Ativar.

Configure o tempo de execução do Apigee Hybrid para o Cloud Trace

A API Cloud Trace tem de estar ativada para usar o Cloud Trace com um runtime híbrido do Apigee. Para confirmar que a API Cloud Trace está ativada, siga os passos em Configure o tempo de execução do Apigee para o Cloud Trace.

Além de ativar a Cloud Trace API, tem de adicionar a conta de serviço iam.gserviceaccount.com para usar o Cloud Trace com o tempo de execução híbrido. Para adicionar a conta de serviço, juntamente com as funções e as chaves necessárias, siga estes passos:

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 associação de política 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:

   gcloud iam service-accounts keys \
       create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com

   As chaves das contas de serviço representam um risco de segurança se não forem geridas corretamente. É responsável pela segurança da chave privada e por outras operações descritas nas Práticas recomendadas de gestão de chaves de contas de serviço. Se não conseguir criar uma chave de conta de serviço, a criação de chaves de contas de serviço pode estar desativada para a sua organização. Para mais informações, consulte o artigo Gerir recursos da organização seguros por predefinição.

   Se adquiriu a chave da conta de serviço a partir de uma fonte externa, tem de a validar antes de a usar. Para mais informações, consulte o artigo Requisitos de segurança para credenciais de origem externa".

4. Adicione a conta de serviço ao ficheiro overrides.yaml.

envs:
 - name: ENV_NAME
   serviceAccountPaths:
   runtime: apigee-runtime.json
   synchronizer: apigee-sync.json
   udca: apigee-udca.json

5. Aplique as alterações ao tempo de execução através do Helm:

   helm upgrade ENV_NAME apigee-env/ \
       --namespace APIGEE_NAMESPACE \
       --set env=ENV_NAME \
       --atomic \
       -f overrides.yaml

No ambiente híbrido do Apigee, pode usar o Anthos Service Mesh, com o Cloud Trace. Para mais informações sobre como ativar o Cloud Trace na malha de serviços, consulte o artigo Aceder a rastreios no Cloud Trace.

Ative o rastreio distribuído

Antes de ativar o rastreio distribuído para o Cloud Trace ou o Jaeger, crie as seguintes variáveis de ambiente:

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

Onde:

• TOKEN define o cabeçalho de autenticação com um token de portador. Use este cabeçalho quando chamar as APIs Apigee. Para mais informações, consulte a página de referência do comando print-access-token.
• ENV_NAME é o nome de um ambiente na sua organização.
• PROJECT_ID é o ID do seu projeto do Google Cloud.

Ative o rastreio distribuído para o Cloud Trace

O exemplo seguinte mostra como ativar o rastreio distribuído para o Cloud Trace:

1. Execute esta chamada API do 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 do pedido de exemplo é composto pelos seguintes elementos:

   • O valor de samplingRate está definido como 0,1. Isto significa que aproximadamente 10% das chamadas API são enviadas para o rastreio distribuído. Para mais informações sobre como definir um samplingRate para o seu ambiente de tempo de execução, consulte Considerações sobre o desempenho.
   • O parâmetro exporter está definido como CLOUD_TRACE.
   • O ponto final está definido para o projeto do Google Cloud para o qual quer enviar o rastreio. NOTA: tem de corresponder à conta de serviço que foi criada no passo de configuração.

   Uma resposta bem-sucedida tem um aspeto semelhante ao seguinte:

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

Ative o rastreio distribuído para o Jaeger

O exemplo seguinte mostra como ativar o rastreio 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:

• O valor de samplingRate está definido como 0,4. Isto significa que aproximadamente 40% das chamadas API são enviadas para o rastreio distribuído.
• O parâmetro exporter está definido como JAEGER.
• O ponto final está definido para o local onde o Jaeger está instalado e configurado.

Quando executa o comando, pode ver uma resposta semelhante à seguinte:

{
  "exporter": "JAEGER",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.4
  }
}

Veja a configuração do rastreio distribuído

Para ver a configuração de rastreio distribuído existente no seu tempo de execução, inicie sessão no tempo de execução e, em seguida, execute o seguinte comando:

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

Quando executa o comando, pode ver uma resposta semelhante à seguinte:

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

Atualize a configuração do rastreio distribuído

O comando seguinte mostra como atualizar a configuração de rastreio distribuído existente para o Cloud Trace:

curl -s \
    -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig?updateMask=endpoint,samplingConfig,exporter' \
    -X PATCH -H "content-type:application/json" \
    -d '{"samplingConfig": {"samplingRate": 0.05, "sampler":"PROBABILITY"},
    "endpoint":"staging", exporter:"CLOUD_TRACE"}'

Quando executa o comando, pode ver uma resposta semelhante à seguinte:

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

Neste exemplo, a taxa de amostragem é atualizada para 0.05.

Para atualizar a configuração do Jaeger, defina o campo exporter no pedido como JAEGER.

Desative a configuração do rastreio distribuído

O exemplo seguinte mostra como desativar o rastreio 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 '{"exporter": "CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'","samplingConfig":
    {"sampler": "OFF","samplingRate": 0.1}}'

Quando executa o comando, pode ver uma resposta semelhante à seguinte:

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

Substitua as definições de rastreio para proxies de API

Quando ativa o rastreio distribuído no tempo de execução do Apigee, todos os proxies de API no tempo de execução usam a mesma configuração para o rastreio. No entanto, pode substituir a configuração do rastreio distribuído para um proxy de API ou um grupo de proxies de API. Isto oferece-lhe um controlo mais detalhado sobre a configuração de rastreio.

O exemplo seguinte substitui a configuração do rastreio distribuído para o proxy da 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}}'

Pode substituir a configuração para resolver problemas específicos de um proxy de API sem ter de alterar a configuração de todos os proxies de API.

Atualize as substituições das definições de rastreio

Para atualizar uma substituição da configuração de rastreio para um proxy de API ou um grupo de proxies de API, siga estes passos:

1. Use o seguinte comando para obter quaisquer substituições existentes da configuração de rastreio:

   curl -s -H "$TOKEN" \
       'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
       -X GET 

   Este comando deve devolver uma resposta semelhante à seguinte, que contém um campo "name" que identifica o proxy ou os proxies regidos pela substituiçã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 um pedido POST para a configuração de substituição desse proxy,juntamente com os valores dos campos 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}}'

Elimine substituições de definições de rastreio

Para eliminar uma substituição da configuração de rastreio para um proxy de API ou um grupo de proxies de API, siga estes passos:

1. Use o seguinte comando para obter quaisquer substituições existentes da configuração de rastreio:

   curl -s -H "$TOKEN" \
       'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
       -X GET 

   Este comando deve devolver uma resposta semelhante à seguinte, que contém um campo "name" que identifica o proxy ou os proxies regidos pela substituição:

   {
     "traceConfigOverrides": [
       {
         "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
         "apiProxy": "proxy1",
         "samplingConfig": {
           "sampler": "PROBABILITY",
           "samplingRate": 0.25
         }
       }
     ]
   }

2. Para eliminar o proxy, use o valor do campo "name" para enviar um pedido DELETE para a configuração de substituição desse proxy,juntamente com os valores dos campos 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 o desempenho

Espera-se um impacto no desempenho quando ativa o rastreio distribuído para um ambiente de tempo de execução do Apigee. O impacto pode resultar num aumento da utilização da memória, dos requisitos da CPU e da 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 mais elevada for a taxa de amostragem, maior é o impacto no desempenho. Embora o impacto no desempenho dependa de vários fatores, pode esperar uma diminuição de 10 a 20% no desempenho quando usar o rastreio distribuído.

Para ambientes com requisitos de tráfego elevado e latência baixa, a taxa de amostragem probabilística recomendada é inferior ou igual a 10%. Se quiser usar o rastreio distribuído para resolver problemas, considere aumentar a amostragem probabilística (samplingRate) apenas para proxies de API específicos.