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
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.

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

Aplicável a:configurações do OpenTelemetry e do OpenCensus.

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 após o recebimento de uma resposta do servidor de destino. Ele carrega os atributos do lado de destino listados em Variáveis no intervalo 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 SSE do proxy visíveis no relatório de rastreamento.

Atributos de recurso padrão

Aplicável a:somente OpenTelemetry. Esta seção não se aplica à configuração do OpenCensus.

Quando você usa o OpenTelemetry com o protocolo de rastreamento OTLP, o tempo de execução da Apigee anexa os seguintes atributos de recurso de convenção semântica do OpenTelemetry a cada intervalo emitido:

Atributo Descrição
service.name Valor fixo apigee.googleapis.com.
service.instance.id Identificador da instância do processador de mensagens que emitiu o período. Omitido quando a identidade do pod de execução não está disponível.
cloud.provider Sempre gcp.
cloud.platform Sempre gcp_apigee.
cloud.region A região que hospeda o ambiente de execução da Apigee, voltando para global quando nenhuma região está configurada.
cloud.resource_id Caminho do recurso da Apigee totalmente qualificado no formato /apigee.googleapis.com/organizations/ORG/environments/ENV.
gcp.apigee.organization O nome da organização da Apigee.
gcp.apigee.environment O nome do ambiente da Apigee.
gcp.project_id O ID do projeto Google Cloud . Emitido somente quando o exportador é OPEN_TELEMETRY_CLOUD_TRACE.

Tipos de período

Aplicável a:configurações do OpenTelemetry e do OpenCensus.

A Apigee emite intervalos com os seguintes valores de SpanKind:

SpanKind Períodos emitidos com esse tipo
SERVER O intervalo do proxy raiz (um por invocação de proxy), que representa a solicitação recebida pelo ambiente de execução da Apigee.
INTERNAL Todos os outros períodos, incluindo períodos de fluxo (por exemplo, RESP_SENT e PROXY_POST_RESP_SENT) e todos os períodos de etapas de política (por exemplo, AssignMessage, VerifyAPIKey, ServiceCallout, JavaScript, KeyValueMapOperations).

A Apigee não emite intervalos CLIENT, PRODUCER ou CONSUMER. Em particular, as chamadas de saída da Apigee para o back-end de destino não são emitidas como intervalos CLIENT separados. A chamada de saída é representada nos intervalos de fluxo INTERNAL atuais, e o cabeçalho traceparent é propagado para o destino para que o serviço de destino possa emitir seu próprio intervalo SERVER e participar do mesmo rastreamento.

Variáveis no período RESP_SENT

As variáveis a seguir ficam visíveis no período RESP_SENT. A coluna Variável semântica OTEL mostra o nome da convenção semântica do OpenTelemetry usado quando spanSemantics é definido como OTEL. A coluna Atributo mostra o nome do atributo legado.

Variável legada Variável semântica OTEL Atributo Descrição
REQUEST_URL url.full request.url URL completo da solicitação do cliente recebida pelo proxy.
REQUEST_VERB http.request.method request.verb Verbo HTTP da solicitação do cliente recebida (por exemplo, GET ou POST).
RESPONSE_STATUS_CODE http.response.status_code response.status.code Código de status da resposta retornado pelo servidor de destino.
ROUTE_NAME gcp.apigee.route.name route.name Nome da regra de rota que selecionou o destino para esta solicitação.
ROUTE_TARGET gcp.apigee.route.target route.target Nome do endpoint de destino selecionado pela regra de rota.
TARGET_BASE_PATH gcp.apigee.target.basepath target.basepath Parte do caminho base do URL de destino.
TARGET_HOST server.address target.host Nome do host do servidor de destino contatado pelo proxy.
TARGET_IP server.address target.ip Endereço IP resolvido do servidor de destino.
TARGET_NAME gcp.apigee.target.name target.name Nome do endpoint de destino definido no proxy de API.
TARGET_PORT server.port target.port Porta TCP usada para se conectar ao servidor de destino.
TARGET_RECEIVED_END_TIMESTAMP gcp.apigee.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 gcp.apigee.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 gcp.apigee.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 gcp.apigee.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 gcp.apigee.target.ssl_enabled target.ssl.enabled Booleano que indica se a conexão com o servidor de destino usou TLS.
TARGET_URL url.full 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. A coluna Variável semântica OTEL mostra o nome da convenção semântica do OpenTelemetry usado quando spanSemantics é definido como OTEL. A coluna Atributo mostra o nome do atributo legado.

Variável legada Variável semântica OTEL Atributo Descrição
API_PROXY_REVISION gcp.apigee.proxy.revision apiproxy.revision Número da revisão do proxy de API que processou a solicitação.
APIPROXY_NAME gcp.apigee.proxy.name apiproxy.name Nome do proxy de API que processou a solicitação.
CLIENT_RECEIVED_END_TIMESTAMP gcp.apigee.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 gcp.apigee.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 gcp.apigee.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 gcp.apigee.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 gcp.apigee.environment environment.name Nome do ambiente da Apigee em que o proxy foi executado.
FAULT_SOURCE gcp.apigee.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 gcp.apigee.is_error is.error Booleano que indica se a execução do proxy terminou em um fluxo de erros.
MESSAGE_ID gcp.apigee.message.id message.id Identificador exclusivo atribuído pela Apigee à solicitação, útil para correlacionar registros e intervalos de rastreamento.
MESSAGE_STATUS_CODE http.response.status_code message.status.code Código de status da resposta final, incluindo chamadas sem destinos e fluxos de erro.
PROXY_BASE_PATH http.route proxy.basepath Caminho base do proxy de API que correspondeu à solicitação recebida.
PROXY_CLIENT_IP client.address proxy.client.ip Endereço IP do cliente que enviou a solicitação ao proxy.
PROXY_NAME gcp.apigee.proxy.name proxy.name Nome do endpoint de proxy no proxy de API que processou a solicitação.
PROXY_PATH_SUFFIX url.path proxy.pathsuffix Parte do caminho do URL da solicitação que segue o caminho de base do proxy.
PROXY_URL url.full 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 coletor do OpenTelemetry.

Consulte Considerações ao usar um coletor do OpenTelemetry para saber mais sobre os requisitos de alcance de rede, TLS e transporte 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 oferece suporte a 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 seção abaixo.

Para o OpenTelemetry, o ambiente de execução da Apigee reconhece o formato de cabeçalho de contexto de rastreamento W3C, incluindo os cabeçalhos traceparent, tracestate e baggage.

Configurar pré-requisitos para o Cloud Trace (OpenTelemetry)

O ambiente de execução da Apigee (ApigeeX) oferece suporte ao rastreamento distribuído usando o Cloud Trace com o OpenTelemetry. 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 para abrir a biblioteca de APIs.
  3. Na Biblioteca de APIs, ative a API Cloud Trace, a API Telemetry e a API Service Usage. Para encontrar cada API, pesquise pelo nome (por exemplo, Telemetry API) na barra de pesquisa da biblioteca de APIs.

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:

  • ApigeeX (não híbrido): conceda os papéis ao agente de serviço da Apigee, uma P4SA (conta de serviço por produto por projeto) gerenciada pelo Google que a Apigee provisiona automaticamente para o projeto. A conta do agente de serviço tem o formato service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com.

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

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

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",
          "spanSemantics": "OTEL"
        }'

    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 está 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).
    • O parâmetro spanSemantics é opcional e controla o atributo e a nomenclatura de intervalo usados nos intervalos emitidos. Valores aceitos:
      • LEGACY (padrão): use o atributo histórico do Apigee e os nomes de período mostrados na coluna Atributo das tabelas de variáveis.
      • OTEL: use os nomes de convenção semântica do OpenTelemetry mostrados na coluna Variável semântica do OTEL. Exige que traceProtocol seja OTLP.

    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",
  "spanSemantics": "OTEL"
}

Ativar o rastreamento distribuído para um OpenTelemetry Collector

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": "http://my-otel-collector.example.com:4318/v1/traces",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05},
          "traceProtocol": "OTLP",
          "spanSemantics": "OTEL"
        }'

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 HTTP/HTTPS completo do endpoint de ingestão OTLP do coletor do OpenTelemetry (por exemplo, http://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. Ao contrário do endpoint do Cloud Trace, o endpoint do OpenTelemetry Collector é mutável: é possível reconfigurá-lo mais tarde com outro PATCH para traceConfig.
  • 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.
  • O parâmetro otelCollectorSecurityScheme é opcional e tem NONE como padrão. Defina como MTLS para ativar o TLS mútuo entre a Apigee e o coletor. Consulte Configurar o mTLS para um coletor do OpenTelemetry (em inglês) para ver os campos mtlsConfig obrigatórios e o corpo completo da solicitação de API.

Uma resposta bem-sucedida é semelhante a esta:

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

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).
  • Se um proxy de encaminhamento estiver presente na sua configuração, configure-o no OpenTelemetry Collector. As conexões do processador de mensagens com o OpenTelemetry Collector são sempre diretas.

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

A Apigee oferece suporte a dois esquemas de segurança para a conexão com um coletor do OpenTelemetry, definidos por otelCollectorSecurityScheme em traceConfig:

  • Sem segurança (HTTP) (NONE, o padrão): a Apigee se conecta ao coletor por HTTP sem TLS mútuo.
  • mTLS (MTLS): TLS mútuo para que o coletor também possa autenticar a Apigee como cliente. Para ativar o mTLS, defina otelCollectorSecurityScheme como MTLS em traceConfig e forneça um mtlsConfig que faça referência a keystores e truststores gerenciados pela Apigee. Consulte Configurar mTLS para um coletor do OpenTelemetry para a configuração completa.

Configurar o mTLS para um coletor do OpenTelemetry

O TLS mútuo (mTLS) permite que o OpenTelemetry Collector autentique o tempo de execução do Apigee como cliente, além de o Apigee validar o certificado do servidor do coletor.

Antes de configurar o mTLS, verifique os seguintes pré-requisitos:

  • O coletor está configurado para exigir a autenticação de certificado do cliente (por exemplo, a configuração tls.client_ca_file do coletor OpenTelemetry) e é implantado com um arquivo de autoridade de certificação (CA) que contém a cadeia de certificados enviada na etapa 1 da configuração.
  • O endpoint usa o esquema https://.
  • O exporter é OPEN_TELEMETRY_COLLECTOR e o traceProtocol é OTLP. A mTLS não é aplicada ao exportador OPEN_TELEMETRY_CLOUD_TRACE, que faz a autenticação usando o OAuth Google Cloud .

Etapa 1: fazer upload da chave e do certificado do cliente

Crie um keystore para o certificado do cliente da Apigee que o coletor autentica e faça upload da chave e do certificado como um alias:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores \
    -X POST \
    -d '{ "name": "otel-mtls" }'

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls/aliases?alias=mp-client&format=keycertfile" \
    -X POST \
    -F "keyFile=@client.key" \
    -F "certFile=@client.crt"

O arquivo client.crt precisa ser assinado por uma autoridade certificadora em que o tls.client_ca_file do coletor confia. Em uma configuração autoassinada, client.crt pode ser o mesmo arquivo que o coletor usa como client_ca_file.

Etapa 2: fazer o upload do certificado do servidor do coletor

Crie um truststore que o ambiente de execução da Apigee usa para validar o certificado do servidor do coletor e faça upload do certificado de CA do coletor como um alias CERT:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores \
    -X POST \
    -d '{ "name": "otel-mtls-truststore" }'

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls-truststore/aliases?alias=server-ca&format=keycertfile" \
    -X POST \
    -F "certFile=@server-ca.pem"

Etapa 3: ativar o mTLS no traceConfig

Adicione um PATCH ao traceConfig para definir o esquema de segurança como MTLS e referenciar o keystore e o truststore que você acabou de criar:

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",
          "traceProtocol": "OTLP",
          "spanSemantics": "OTEL",
          "otelCollectorSecurityScheme": "MTLS",
          "mtlsConfig": {
            "keyStore":   "otel-mtls",
            "keyAlias":   "mp-client",
            "trustStore": "otel-mtls-truststore"
          }
        }'

O objeto mtlsConfig tem três campos obrigatórios:

  • keyStore: o nome do keystore que contém a chave e o certificado do cliente da Apigee da etapa 1 (por exemplo, otel-mtls). Para usar uma referência da Apigee, especifique ref://REFERENCE_NAME.
  • keyAlias: o nome do alias KEY_CERT em keyStore (por exemplo, mp-client).
  • trustStore: o nome do keystore que contém o certificado de CA do servidor do coletor da etapa 2 (por exemplo, otel-mtls-truststore). Para usar uma referência da Apigee, especifique ref://REFERENCE_NAME.

A Apigee aplica a seguinte validação em traceConfig quando otelCollectorSecurityScheme é MTLS:

  • exporter precisa ser OPEN_TELEMETRY_COLLECTOR.
  • traceProtocol precisa ser OTLP.
  • endpoint precisa usar o esquema https://.
  • Todos os três campos mtlsConfig precisam ser preenchidos. Se algum campo estiver faltando, o retorno será HTTP 400.
  • Os keystores, aliases e referências precisam existir. Recursos ausentes retornam HTTP 400.

Trocar a chave ou o certificado do cliente

Para rotacionar a chave ou o certificado do cliente sem uma mudança de traceConfig, faça upload do novo material de chave para o alias mp-client atual com um PUT:

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls/aliases/mp-client" \
    -X PUT \
    -F "keyFile=@client-v2.key" \
    -F "certFile=@client-v2.crt"

O ambiente de execução da Apigee detecta a mudança de alias-revisão na próxima sincronização de configuração e recompila o exportador OTLP mTLS com as novas credenciais. Não é necessário reiniciar o pod, e nenhuma solicitação em andamento é descartada.

Critérios de amostragem

O ambiente de execução da Apigee decide se vai registrar um rastreamento para cada solicitação combinando os cabeçalhos de solicitação recebidos com a configuração de rastreamento do ambiente.

Cabeçalho de contexto de rastreamento do W3C

Na configuração do OpenTelemetry, o tempo de execução respeita o cabeçalho contexto de rastreamento do W3C traceparent. O último byte de traceparent (o byte trace-flags) carrega a flag sampled: um valor de 01 indica que o caller já decidiu gravar o rastreamento, e 00 indica que não.

As recomendações para a flag de amostragem (link em inglês) da especificação de contexto de rastreamento do W3C aconselham que um componente respeite a flag de amostragem recebida ao tomar uma decisão de gravação e reflita uma decisão definitiva de gravação na flag. O Apigee segue estas recomendações: ele respeita a flag de amostragem recebida ao decidir se vai gravar um rastreamento (consulte Precedência do cabeçalho sobre a configuração local) e define a flag de amostragem no cabeçalho traceparent que ele propaga para serviços downstream para refletir se a solicitação está sendo gravada. Como um controle de segurança contra rastreamento indesejado impulsionado pela flag de entrada, defina sampler como OFF (consulte Desativar a configuração de rastreamento distribuído), o que desativa o rastreamento mesmo para solicitações em que traceparent tem a flag de amostragem definida.

Precedência do cabeçalho sobre a configuração local

Quando uma solicitação recebida tem um cabeçalho traceparent, o ambiente de execução do Apigee usa a flag de amostragem desse cabeçalho em vez do samplingConfig local. Uma solicitação com a flag de amostragem definida como 01 é sempre rastreada. Uma solicitação com a flag definida como 00 não é rastreada. O samplingConfig no nível do ambiente se aplica apenas a solicitações que chegam sem um cabeçalho traceparent.

Como desativar o rastreamento

Para desativar o rastreamento de todos os proxies em um ambiente (exclui substituições de proxy), defina sampler como OFF no ambiente traceConfig. Consulte Desativar a configuração de rastreamento distribuído.

Substituições por proxy

Para ativar o rastreamento apenas para um subconjunto de proxies em um ambiente, deixe o ambiente samplingConfig com sampler definido como OFF e crie uma substituição por proxy (com sampler definido como PROBABILITY e um samplingRate diferente de zero) para cada proxy que você quer rastrear. Consulte Modificar as configurações de trace para proxies de API.

Impacto da taxa de amostragem na performance

O samplingRate que você configura afeta diretamente a performance de execução. Cada solicitação amostrada gera trabalho extra de CPU no processador de mensagens (geração e exportação de intervalos) e adiciona latência ao caminho da solicitação. À medida que a taxa de amostragem aumenta, o mesmo acontece com o volume de tráfego rastreado por MP, o que pode reduzir a capacidade de processamento e aumentar a latência de cauda (p95, p99). O impacto aumenta com o volume de tráfego: em taxas de solicitação baixas, o excesso é geralmente insignificante, enquanto em taxas altas, uma alta taxa de amostragem pode reduzir significativamente a capacidade de processamento sustentável e exigir mais capacidade de MP. Em comparativos internos, a execução em samplingRate=1.0 (amostragem de 100%) sob tráfego intenso e constante reduziu a capacidade em até 15% em comparação com a execução com o rastreamento desativado.

Como diretriz geral, mantenha samplingRate baixo (por exemplo, 0.1 ou menos) na produção e aumente apenas para proxies específicos usando substituições por proxy quando precisar de uma visibilidade mais detalhada. Para um detalhamento do impacto esperado e orientações sobre capacidade, consulte Considerações sobre desempenho.

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 da Apigee tem uma taxa de exportação de período finita. Com a configuração padrão, um único MP pode exportar de forma sustentável aproximadamente 820 intervalos por segundo. Uma execução típica de proxy de API emite aproximadamente 10 intervalos (pré-fluxo do proxy, fluxo de destino, pós-fluxos, políticas anexadas). Portanto, 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 aproximadamente 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.

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 do Apigee híbrida 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 do Apigee híbrida 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. 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 \

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 a 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.