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.

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 ou o Jaeger. 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:

Solicitação
- Proxy
  - Pré-fluxo
  - PostFlow
- Destino
  - Pré-fluxo
  - PostFlow
Resposta
- Proxy
  - Pré-fluxo
  - PostFlow
- Destino
  - Pré-fluxo
  - PostFlow

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.

Uma chamada de API para a Apigee pode conter cabeçalhos de trace, porque a chamada faz parte de um trace existente. Nesse caso, a Apigee participa do trace atual e propaga os cabeçalhos para a chamada de API de saída. O ambiente de execução da Apigee entende o formato de cabeçalho Zipkin B3. Portanto, ele reconhece os cabeçalhos x-b3-traceid, x-b3-spanid e x-b3-sampled ao participar de um trace existente. No entanto, se não houver cabeçalhos de trace em uma chamada de API recebida, a Apigee adicionará os cabeçalhos de trace e os propagará para a chamada de API enviada. Outros serviços podem acessar os cabeçalhos e participar do rastreamento, se necessário.

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:

POST_RESP_SENT:: esse período é adicionado após o recebimento de uma resposta do servidor de destino.
POST_CLIENT_RESP_SENT:: esse período é adicionado após o envio da resposta do proxy ao cliente.

Variáveis no período POST_RESP_SENT

As variáveis a seguir ficam visíveis no período 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 período POST_CLIENT_RESP_SENT

As variáveis a seguir ficam visíveis no período 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 rastreamento distribuído com suporte

O ambiente de execução da Apigee oferece suporte para os seguintes sistemas de rastreamento distribuídos:

Cloud Trace
Jaeger

É possível configurar o ambiente de execução da Apigee para enviar os dados de trace a um sistema do Cloud Trace ou do Jaeger.

Como o rastreamento de todas as chamadas de API no ambiente de execução da Apigee afeta o desempenho, a Apigee permite configurar uma taxa de amostragem probabilística. Ao usar a taxa de amostragem, é possível especificar o número de chamadas de API enviadas para o rastreamento distribuído. Por exemplo, se você especificar a taxa de amostragem como 0.4, isso significa que 40% das chamadas de API vão ser enviadas para o rastreamento. Veja mais informações em Considerações sobre desempenho.

A taxa de amostragem máxima configurada é de 0.5.

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

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 o Jaeger, pule esta seção e acesse Como ativar o rastreamento distribuído para o Jaeger.

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

Para usar o Cloud Trace com um ambiente de execução do Apigee, o projeto do Google Cloud precisa ter a API Cloud Trace ativada. Essa configuração permite que o projeto do Google Cloud receba dados de trace de fontes autenticadas.

Para confirmar se a API Cloud Trace está ativada, faça isto:

No console do Google Cloud, acesse APIs e serviços:
Acessar APIs e Serviços
Clique em Ativar APIs e serviços.
Na barra de pesquisa, digite Trace API.
Se a API ativada for exibida, essa API já estará ativada e não haverá nada para fazer. Caso contrário, clique em Ativar.

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

A API Cloud Trace precisa estar ativada para usar o Cloud Trace com um ambiente de execução híbrido da Apigee. Para confirmar se a API Cloud Trace está ativada, siga as etapas em Configurar o ambiente de execução do Apigee para o Cloud Trace.

Além de ativar a API Cloud Trace, você precisa adicionar a conta de serviço iam.gserviceaccount.com para usar o Cloud Trace com esse 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:

Crie uma nova conta de serviço:

gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID

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

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 da conta de serviço são um risco de segurança quando não são gerenciadas corretamente. Você é responsável pela segurança da chave privada e por outras operações descritas em Práticas recomendadas para gerenciar chaves de contas de serviço. Se não for possível criar uma chave de conta de serviço, a criação pode ser desativada para sua organização. Para mais informações, consulte Gerenciar recursos da organização com segurança por padrão.
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

Aplique as alterações ao ambiente de execução.

apigeectl apply -f overrides.yaml --env=ENV_NAME

Ativar rastreamento distribuído

Antes de ativar o rastreamento 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

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 seu projeto do Google Cloud.

Ativar o rastreamento distribuído para o Cloud Trace

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

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:
- 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 mais informações sobre como definir um samplingRate para o ambiente de execução, consulte Considerações sobre desempenho.
- O parâmetro exporter está definido como CLOUD_TRACE.
- O endpoint está definido como o projeto do Google Cloud para o qual você quer enviar o trace. OBSERVAÇÃO: é preciso ser igual à conta de serviço que foi feita na etapa de configuração.
Uma resposta bem-sucedida é semelhante a esta:
```
{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}
```

Ativar rastreamento distribuído para o Jaeger

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:

O samplingRate está definido como 0.4. Isso significa que aproximadamente 40% das chamadas de API são enviadas para o rastreamento distribuído.
O parâmetro exporter está definido como JAEGER.
O endpoint é definido como o local em que o Jaeger está instalado e configurado.

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

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

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": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}

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 -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"}'

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

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

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

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

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 '{"exporter": "CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'","samplingConfig":
    {"sampler": "OFF","samplingRate": 0.1}}'

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

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

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:

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
      }
    }
  ]
}

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:

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
      }
    }
  ]
}

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 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. Embora o impacto no desempenho dependa de vários fatores, é possível esperar uma queda de 10% a 20% no desempenho ao usar o rastreamento distribuído.

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.