Attivazione del tracciamento distribuito

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina mostra i passaggi necessari per configurare la tracciabilità distribuita per il runtime Apigee. Se non hai mai utilizzato sistemi di tracciamento distribuito e vuoi saperne di più, consulta Informazioni sul tracciamento distribuito.

Per ulteriori informazioni sui termini utilizzati in questa pagina, consulta la panoramica di Cloud Trace.

Introduzione

I sistemi di tracciamento distribuito consentono di monitorare una richiesta in un sistema software distribuito su più applicazioni, servizi e database, nonché intermediari come i proxy. Questi sistemi di tracciamento generano report che mostrano il tempo impiegato da una richiesta in ogni passaggio. I report di tracciamento possono anche fornire una visione granulare dei vari servizi chiamati durante una richiesta, consentendo una comprensione più approfondita di ciò che accade in ogni passaggio del sistema software.

Lo strumento di tracciamento in Apigee Edge e lo strumento di debug in Apigee sono utili per la risoluzione dei problemi e il monitoraggio dei proxy API. Tuttavia, questi strumenti non inviano dati a server di tracciamento distribuito come Cloud Trace, Jaeger o un agente di raccolta OpenTelemetry.

Per visualizzare i dati del runtime Apigee in un report di tracciamento distribuito, devi abilitare esplicitamente il tracciamento distribuito nel runtime Apigee. Una volta attivato il tracciamento, il runtime può inviare i dati di tracciamento ai server di tracciamento distribuito e partecipare a una traccia esistente. Di conseguenza, puoi visualizzare i dati all'interno e all'esterno del tuo ecosistema Apigee da un'unica posizione.

Nei report di tracciamento distribuito puoi visualizzare le seguenti informazioni:

  • Tempo di esecuzione di un intero flusso.
  • L'ora in cui viene ricevuta la richiesta.
  • Ora in cui la richiesta viene inviata al target.
  • Ora in cui la risposta viene ricevuta dal target.
  • Tempo di esecuzione di ogni policy in un flusso.
  • Tempo di esecuzione dei callout di servizio e dei flussi di destinazione.
  • Ora in cui la risposta viene inviata al client.

Nel report di tracciamento distribuito, puoi visualizzare i dettagli di esecuzione dei flussi come intervalli. Un intervallo si riferisce al tempo impiegato da un flusso in una traccia. Il tempo impiegato per eseguire un flusso viene visualizzato come aggregazione del tempo necessario per eseguire ogni policy nel flusso. Puoi visualizzare ciascuno dei seguenti flussi come intervalli individuali:

Fase Endpoint Flow
Richiesta Proxy Preflow
PostFlow
Target Preflow
PostFlow
Risposta Proxy Preflow
PostFlow
Target Preflow
PostFlow

Una volta attivato il tracciamento distribuito, il runtime Apigee traccerà un insieme di variabili predefinite per impostazione predefinita. Per saperne di più, vedi Variabili di traccia predefinite nel report di tracciamento. Puoi utilizzare la norma TraceCapture per estendere il comportamento di runtime predefinito e tracciare ulteriori variabili di flusso, norme o personalizzate. Per saperne di più, consulta le norme relative a TraceCapture.

Variabili di traccia predefinite nel report di tracciamento

Si applica a: entrambe le configurazioni OpenTelemetry e OpenCensus.

Una volta attivato il tracciamento distribuito, puoi visualizzare il seguente insieme di variabili predefinite nel report di tracciamento. Le variabili sono visibili nei seguenti intervalli:

  • RESP_SENT: questo intervallo viene aggiunto dopo aver ricevuto una risposta dal server di destinazione. Contiene gli attributi lato target elencati in Variabili nell'intervallo RESP_SENT.
  • PROXY_POST_RESP_SENT: Questo intervallo viene aggiunto dopo l'invio della risposta del proxy al client. Contiene gli attributi lato proxy elencati in Variabili nell'intervallo PROXY_POST_RESP_SENT.
  • EVENT_FLOW_RESP e EVENT_FLOW_END: questi intervalli vengono aggiunti per i proxy API che gestiscono le risposte streaming Server-Sent Events (SSE). EVENT_FLOW_RESP contrassegna il flusso di risposta SSE (eseguito una volta per messaggio di risposta). EVENT_FLOW_END indica la fine dello stream SSE. Questi intervalli attualmente non includono attributi predefiniti. Vengono visualizzati nella traccia come intervalli denominati per rendere visibili le fasi SSE del proxy nel report di tracciamento.

Attributi risorsa predefiniti

Si applica a: solo OpenTelemetry. Questa sezione non si applica alla configurazione di OpenCensus.

Quando utilizzi OpenTelemetry con il protocollo di traccia OTLP, il runtime Apigee collega i seguenti attributi di risorsa della convenzione semantica OpenTelemetry a ogni span emesso:

Attributo Descrizione
service.name Valore fisso apigee.googleapis.com.
service.instance.id Identificatore dell'istanza del processore di messaggi che ha emesso lo span. Omesso quando l'identità del pod di runtime non è disponibile.
cloud.provider Sempre gcp.
cloud.platform Sempre gcp_apigee.
cloud.region La regione che ospita il runtime Apigee, con fallback a global quando non è configurata alcuna regione.
cloud.resource_id Percorso della risorsa Apigee completo nel formato /apigee.googleapis.com/organizations/ORG/environments/ENV.
gcp.apigee.organization Il nome dell'organizzazione Apigee.
gcp.apigee.environment Il nome dell'ambiente Apigee.
gcp.project_id L'ID progetto Google Cloud . Emesso solo quando l'esportatore è OPEN_TELEMETRY_CLOUD_TRACE.

Tipi di span

Si applica a entrambe le configurazioni OpenTelemetry e OpenCensus.

Apigee emette span con i seguenti valori SpanKind:

SpanKind Span emessi con questo tipo
SERVER Lo span del proxy principale (uno per ogni chiamata al proxy), che rappresenta la richiesta in entrata ricevuta dal runtime Apigee.
INTERNAL Tutti gli altri intervalli, inclusi gli intervalli di flusso (ad esempio, RESP_SENT e PROXY_POST_RESP_SENT) e ogni intervallo di passaggi dei criteri (ad esempio, AssignMessage, VerifyAPIKey, ServiceCallout, JavaScript, KeyValueMapOperations).

Apigee non emette span CLIENT, PRODUCER o CONSUMER. In particolare, le chiamate in uscita da Apigee al backend di destinazione non vengono emesse come span CLIENT separati; la chiamata in uscita è rappresentata all'interno degli span di flusso INTERNAL esistenti e l'intestazione traceparent viene propagata alla destinazione in modo che il servizio di destinazione possa emettere il proprio span SERVER e unirsi alla stessa traccia.

Variabili nell'intervallo RESP_SENT

Le seguenti variabili sono visibili nell'intervallo RESP_SENT. La colonna Variabile semantica OTEL mostra il nome della convenzione semantica OpenTelemetry utilizzata quando spanSemantics è impostato su OTEL; la colonna Attributo mostra il nome dell'attributo legacy.

Variabile legacy Variabile semantica OTEL Attributo Descrizione
REQUEST_URL url.full request.url L'URL completo della richiesta client in entrata ricevuta dal proxy.
REQUEST_VERB http.request.method request.verb Verbo HTTP della richiesta client in entrata (ad esempio, GET o POST).
RESPONSE_STATUS_CODE http.response.status_code response.status.code Codice di stato della risposta restituito dal server di destinazione.
ROUTE_NAME gcp.apigee.route.name route.name Nome della regola di instradamento che ha selezionato la destinazione per questa richiesta.
ROUTE_TARGET gcp.apigee.route.target route.target Nome dell'endpoint di destinazione selezionato dalla regola di instradamento.
TARGET_BASE_PATH gcp.apigee.target.basepath target.basepath La parte del percorso di base dell'URL di destinazione.
TARGET_HOST server.address target.host Nome host del server di destinazione contattato dal proxy.
TARGET_IP server.address target.ip Indirizzo IP risolto del server di destinazione.
TARGET_NAME gcp.apigee.target.name target.name Nome dell'endpoint di destinazione definito nel proxy API.
TARGET_PORT server.port target.port Porta TCP utilizzata per connettersi al server di destinazione.
TARGET_RECEIVED_END_TIMESTAMP gcp.apigee.target.received_end_timestamp target.received.end.timestamp Timestamp (in millisecondi dell'epoca) in cui il proxy ha terminato di ricevere la risposta dal server di destinazione.
TARGET_RECEIVED_START_TIMESTAMP gcp.apigee.target.received_start_timestamp target.received.start.timestamp Timestamp (in millisecondi epoch) in cui il proxy ha iniziato a ricevere la risposta dal server di destinazione.
TARGET_SENT_END_TIMESTAMP gcp.apigee.target.sent_end_timestamp target.sent.end.timestamp Timestamp (millisecondi epoch) in cui il proxy ha terminato l'invio della richiesta al server di destinazione.
TARGET_SENT_START_TIMESTAMP gcp.apigee.target.sent_start_timestamp target.sent.start.timestamp Timestamp (millisecondi epoch) in cui il proxy ha iniziato a inviare la richiesta al server di destinazione.
TARGET_SSL_ENABLED gcp.apigee.target.ssl_enabled target.ssl.enabled Valore booleano che indica se la connessione al server di destinazione ha utilizzato TLS.
TARGET_URL url.full target.url URL completo del server di destinazione contattato dal proxy.

Variabili nell'intervallo PROXY_POST_RESP_SENT

Le seguenti variabili sono visibili nello span PROXY_POST_RESP_SENT. La colonna Variabile semantica OTEL mostra il nome della convenzione semantica OpenTelemetry utilizzato quando spanSemantics è impostato su OTEL; la colonna Attributo mostra il nome dell'attributo legacy.

Variabile legacy Variabile semantica OTEL Attributo Descrizione
API_PROXY_REVISION gcp.apigee.proxy.revision apiproxy.revision Numero di revisione del proxy API che ha gestito la richiesta.
APIPROXY_NAME gcp.apigee.proxy.name apiproxy.name Nome del proxy API che ha gestito la richiesta.
CLIENT_RECEIVED_END_TIMESTAMP gcp.apigee.client.received_end_timestamp client.received.end.timestamp Timestamp (millisecondi epoch) in cui il proxy ha terminato la ricezione della richiesta dal client.
CLIENT_RECEIVED_START_TIMESTAMP gcp.apigee.client.received_start_timestamp client.received.start.timestamp Timestamp (in millisecondi dell'epoca) in cui il proxy ha iniziato a ricevere la richiesta dal client.
CLIENT_SENT_END_TIMESTAMP gcp.apigee.client.sent_end_timestamp client.sent.end.timestamp Timestamp (in millisecondi epoch) in cui il proxy ha terminato l'invio della risposta al client.
CLIENT_SENT_START_TIMESTAMP gcp.apigee.client.sent_start_timestamp client.sent.start.timestamp Timestamp (millisecondi epoch) in cui il proxy ha iniziato a inviare la risposta al client.
ENVIRONMENT_NAME gcp.apigee.environment environment.name Il nome dell'ambiente Apigee in cui è stato eseguito il proxy.
FAULT_SOURCE gcp.apigee.fault_source message.header.X-Apigee-fault-source Origine dell'errore quando si verifica un errore durante l'esecuzione del proxy. Valore compilato solo nei flussi di errore.
IS_ERROR gcp.apigee.is_error is.error Valore booleano che indica se l'esecuzione del proxy è terminata con un flusso di errori.
MESSAGE_ID gcp.apigee.message.id message.id Identificatore univoco assegnato da Apigee alla richiesta, utile per correlare log e intervalli di traccia.
MESSAGE_STATUS_CODE http.response.status_code message.status.code Codice di stato della risposta finale, anche per le chiamate senza target e per i flussi di errori.
PROXY_BASE_PATH http.route proxy.basepath Il percorso di base del proxy API che corrisponde alla richiesta in entrata.
PROXY_CLIENT_IP client.address proxy.client.ip L'indirizzo IP del client che ha inviato la richiesta al proxy.
PROXY_NAME gcp.apigee.proxy.name proxy.name Nome dell'endpoint proxy all'interno del proxy API che ha gestito la richiesta.
PROXY_PATH_SUFFIX url.path proxy.pathsuffix Porzione del percorso dell'URL della richiesta che segue il percorso di base del proxy.
PROXY_URL url.full proxy.url URL completo dell'endpoint proxy ricevuto dal client.

Sistemi di tracciamento distribuito supportati

Puoi configurare il runtime Apigee per inviare i dati di traccia ai seguenti sistemi di tracciamento distribuito:

Sistemi di tracciamento distribuito Descrizione
Cloud Trace con OpenTelemetry

Ideale per gli utenti che vogliono una configurazione semplice con OpenTelemetry e il cui backend di tracciamento principale o unico è Cloud Trace.

Per inviare i dati di traccia a Cloud Trace con OpenTelemetry:

  1. Configura il runtime Apigee per Cloud Trace.
  2. Abilita il tracciamento distribuito per Cloud Trace con OpenTelemetry.
OpenTelemetry Collector

Gestisci il tuo OpenTelemetry Collector per controllare la raccolta e l'elaborazione dei dati di traccia. Questa opzione è ideale se devi inviare dati a più sistemi (inclusi quelli non Google) o personalizzare il modo in cui i dati vengono elaborati, raggruppati o migliorati.

Per inviare i dati di traccia a un agente di raccolta OpenTelemetry, procedi come segue:

  1. Esegui il deployment e gestisci un OpenTelemetry Collector, come descritto in OpenTelemetry Collector.
  2. Abilita il tracciamento distribuito per un agente di raccolta OpenTelemetry.

Consulta Considerazioni sull'utilizzo di un collettore OpenTelemetry per i requisiti di raggiungibilità della rete, TLS e trasporto che devi soddisfare prima di abilitare questa opzione.
Cloud Trace con OpenCensus

Per inviare i dati di traccia a Cloud Trace con OpenCensus:

  1. Configura il runtime Apigee per Cloud Trace (OpenCensus).
  2. Attiva il tracciamento distribuito per Cloud Trace con OpenCensus.
Jaeger con OpenCensus

Per inviare i dati di tracciamento a Jaeger con OpenCensus, attiva il tracciamento distribuito per Jaeger.

Variabili di ambiente

Le procedure descritte in questa pagina utilizzano le seguenti variabili di ambiente. Ti consigliamo di impostarli nel tuo ambiente prima di iniziare.

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

Dove:

  • TOKEN definisce l'intestazione di autenticazione con un token di connessione. Utilizzi questa intestazione quando chiami le API Apigee. Per ulteriori informazioni, consulta la pagina di riferimento per il comando print-access-token.
  • ENV_NAME è il nome di un ambiente della tua organizzazione.
  • PROJECT_ID è l'ID del tuo progetto Google Cloud .

Configura il runtime Apigee per OpenTelemetry o OpenCensus

Il runtime Apigee supporta due standard di tracciamento: OpenTelemetry (consigliato per i nuovi deployment) e OpenCensus. Scegli lo standard di tracciamento più adatto al tuo ambiente, poi segui i passaggi di configurazione corrispondenti nella sezione seguente.

Per OpenTelemetry, il runtime Apigee riconosce il formato dell'intestazione del contesto di traccia W3C, incluse le intestazioni traceparent, tracestate e baggage.

Configura i prerequisiti per Cloud Trace (OpenTelemetry)

Il runtime Apigee (ApigeeX) supporta il tracciamento distribuito utilizzando Cloud Trace con OpenTelemetry. Se utilizzi un OpenTelemetry Collector gestito dal cliente, puoi saltare questa sezione e passare ad Abilitazione della tracciabilità distribuita per un OpenTelemetry Collector.

Configura il runtime ApigeeX per Cloud Trace

Per configurare il runtime Apigee per Cloud Trace, nel tuo progetto Google Cloud devono essere abilitate le seguenti API:

L'abilitazione di queste API consente al tuo progetto Google Cloud di ricevere dati di traccia tramite OpenTelemetry da origini autenticate.

Per abilitare le API:

  1. Nella console Google Cloud , vai ad API e servizi:

    Vai ad API e servizi

  2. Fai clic su Abilita API e servizi per aprire la libreria API.
  3. Dalla libreria API, abilita l'API Cloud Trace, l'API Telemetry e l'API Service Usage. Puoi trovare ogni API cercandola per nome (ad esempio, Telemetry API) dalla barra di ricerca della libreria API.

Oltre ad abilitare le API, devi concedere i seguenti ruoli all'account service agent:

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

Il account di servizio specifico dipende dall'ambiente Apigee:

  • ApigeeX (non ibrido): concedi i ruoli al service agent Apigee, un account di servizio per prodotto e per progetto (P4SA) gestito da Google che Apigee esegue il provisioning automaticamente per il progetto. L'account service agent ha il formato service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com.

Consulta Concedi un ruolo IAM utilizzando la console Google Cloud .

Attiva il tracciamento distribuito (OpenTelemetry)

Prima di attivare la tracciabilità distribuita, crea le variabili di ambiente richieste.

Abilita il tracciamento distribuito per Cloud Trace

L'esempio seguente mostra come abilitare la tracciabilità distribuita per Cloud Trace con OpenTelemetry:

  1. Esegui questa chiamata API 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"
        }'

    Il corpo della richiesta di esempio è costituito dai seguenti elementi:

    • Per supportare Cloud Trace con OpenTelemetry, il parametro exporter è impostato su OPEN_TELEMETRY_CLOUD_TRACE e il parametro traceProtocol è impostato su OTLP.
    • samplingRate è impostato su 0,05. Ciò significa che circa il 5% delle chiamate API viene inviato a distributed tracing. Per OpenTelemetry, puoi specificare una frequenza di campionamento fino a 1.0 (100%). Per ulteriori informazioni, vedi Considerazioni sul rendimento.
    • Il parametro endpoint è impostato sull'ID progetto Google Cloud che deve ricevere i dati di traccia (una stringa ID progetto semplice, non un URL).
    • Il parametro spanSemantics è facoltativo e controlla la denominazione degli attributi e degli span utilizzati negli span emessi. Valori supportati:
      • LEGACY (impostazione predefinita): utilizza l'attributo Apigee storico e i nomi degli intervalli mostrati nella colonna Attributo delle tabelle delle variabili.
      • OTEL: utilizza i nomi delle convenzioni semantiche OpenTelemetry mostrati nella colonna Variabile semantica OTEL. Richiede che traceProtocol sia OTLP.

    Una risposta corretta è simile alla seguente:

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

Abilita il tracciamento distribuito per un collettore OpenTelemetry

Per abilitare la tracciabilità distribuita per un agente di raccolta OpenTelemetry gestito dal cliente, esegui questa chiamata API 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"
        }'

Il corpo della richiesta di esempio è costituito dai seguenti elementi:

  • Per supportare un raccoglitore OpenTelemetry gestito dal cliente, il parametro exporter è impostato su OPEN_TELEMETRY_COLLECTOR e il parametro traceProtocol è impostato su OTLP.
  • Il parametro endpoint è impostato sull'URL HTTP/HTTPS completo dell'endpoint di inserimento OTLP di OpenTelemetry Collector (ad esempio, http://my-otel-collector.example.com:4318/v1/traces). A differenza dell'esportatore Cloud Trace, che accetta un ID progetto Google Cloud semplice, l'esportatore OPEN_TELEMETRY_COLLECTOR richiede un URL completo che includa schema, host, porta e percorso. A differenza dell'endpoint Cloud Trace, il raccoglitore OpenTelemetry endpoint è modificabile: puoi riconfigurarlo in un secondo momento con un altro PATCH per traceConfig.
  • samplingRate è impostato su 0,05. Ciò significa che circa il 5% delle chiamate API viene inviato a distributed tracing. Per ulteriori informazioni, vedi Considerazioni sul rendimento.
  • Il parametro otelCollectorSecurityScheme è facoltativo e il valore predefinito è NONE. Impostalo su MTLS per abilitare mutual TLS tra Apigee e l'agente di raccolta. Per i campi mtlsConfig obbligatori e il corpo completo della richiesta API, consulta Configurare mTLS per un agente di raccolta OpenTelemetry.

Una risposta corretta è simile alla seguente:

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

Considerazioni sull'utilizzo di un collettore OpenTelemetry

Prima di attivare la tracciabilità distribuita in un agente di raccolta OpenTelemetry gestito dal cliente, esamina i seguenti requisiti.

Connettività di rete

  • Assicurati che Apigee possa raggiungere OpenTelemetry Collector.
  • Per raggiungere un agente di raccolta non esposto su internet pubblico, utilizza Private Service Connect (PSC).
  • Se nella configurazione è presente un proxy di inoltro, configurarlo in OpenTelemetry Collector. Le connessioni dal processore di messaggi al collettore OpenTelemetry sono sempre dirette.

Protocollo di trasporto

Per i raccoglitori OpenTelemetry è supportato solo il trasporto OTLP/HTTP (porta 4318 e percorso /v1/traces per convenzione OTLP). OTLP/gRPC (porta 4317) non è supportato.

TLS e mTLS

Apigee supporta due schemi di sicurezza per la connessione a un collettore OpenTelemetry, impostati tramite otelCollectorSecurityScheme su traceConfig:

  • Nessuna sicurezza (HTTP) (NONE, impostazione predefinita): Apigee si connette all'agente di raccolta tramite HTTP senza mutual TLS.
  • mTLS (MTLS): mutual TLS, in modo che l'agente di raccolta possa anche autenticare Apigee come client. Per abilitare mTLS, imposta otelCollectorSecurityScheme su MTLS su traceConfig e fornisci un mtlsConfig che faccia riferimento ai keystore e ai truststore gestiti da Apigee. Per la configurazione end-to-end, vedi Configura mTLS per un agente di raccolta OpenTelemetry.

Configura mTLS per un agente di raccolta OpenTelemetry

mutual TLS (mTLS) consente a OpenTelemetry Collector di autenticare il runtime Apigee come client, oltre ad Apigee che convalida il certificato server dell'agente di raccolta.

Prima di configurare mTLS, verifica i seguenti prerequisiti:

  • Il raccoglitore è configurato per richiedere l'autenticazione del certificato client (ad esempio, l'impostazione tls.client_ca_file di OpenTelemetry Collector) e viene implementato con un file dell'autorità di certificazione (CA) che contiene la catena di certificati che carichi nel passaggio 1 della configurazione.
  • endpoint utilizza lo schema https://.
  • Il valore exporter è OPEN_TELEMETRY_COLLECTOR e il valore traceProtocol è OTLP. mTLS non viene applicato all'esportatore OPEN_TELEMETRY_CLOUD_TRACE, che esegue l'autenticazione utilizzando Google Cloud OAuth.

Passaggio 1: carica la chiave e il certificato client

Crea un archivio chiavi per il certificato client Apigee che il collector autentica, quindi carica la chiave e il certificato come 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"

Il file client.crt deve essere firmato da un'autorità di certificazione considerata attendibile da tls.client_ca_file del raccoglitore. Per una configurazione autofirmata, client.crt può essere lo stesso file che l'agente di raccolta utilizza come client_ca_file.

Passaggio 2: carica il certificato del server del raccoglitore

Crea un truststore che il runtime Apigee utilizza per convalidare il certificato server del raccoglitore, quindi carica il certificato CA del raccoglitore come 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"

Passaggio 3: attiva mTLS su traceConfig

APPLICA UNA PATCH a traceConfig per impostare lo schema di sicurezza su MTLS e fai riferimento al keystore e al truststore che hai appena creato:

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

L'oggetto mtlsConfig ha tre campi obbligatori:

  • keyStore: il nome del keystore che contiene la chiave e il certificato client Apigee del passaggio 1 (ad esempio, otel-mtls). Per utilizzare un riferimento Apigee, specifica ref://REFERENCE_NAME.
  • keyAlias: il nome dell'alias KEY_CERT all'interno di keyStore (ad esempio, mp-client).
  • trustStore: il nome del keystore che contiene il certificato CA server del raccoglitore del passaggio 2 (ad es. otel-mtls-truststore). Per utilizzare invece un riferimento Apigee, specifica ref://REFERENCE_NAME.

Apigee applica la seguente convalida a traceConfig quando otelCollectorSecurityScheme è MTLS:

  • exporter deve essere OPEN_TELEMETRY_COLLECTOR.
  • traceProtocol deve essere OTLP.
  • endpoint deve utilizzare lo schema https://.
  • Tutti e tre i campi mtlsConfig devono essere compilati. Se manca un campo, viene restituito l'errore HTTP 400.
  • Gli archivio chiavi, gli alias e i riferimenti a cui viene fatto riferimento devono già esistere. Le risorse mancanti restituiscono HTTP 400.

Ruotare la chiave o il certificato client

Per ruotare la chiave o il certificato client senza una modifica traceConfig, carica il nuovo materiale della chiave nell'alias mp-client esistente con un 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"

Il runtime Apigee rileva la modifica della revisione dell'alias alla successiva sincronizzazione della configurazione e ricompila l'esportatore OTLP mTLS con le nuove credenziali. Non è richiesto il riavvio del pod e non vengono eliminate richieste in corso.

Criteri di campionamento

Il runtime Apigee decide se registrare una traccia per ogni richiesta combinando le intestazioni delle richieste in entrata con la configurazione delle tracce dell'ambiente.

Intestazione del contesto della traccia W3C

Nella configurazione di OpenTelemetry, il runtime rispetta l'intestazione Contesto di traccia W3C traceparent. L'ultimo byte di traceparent (il byte trace-flags) contiene il flag sampled: un valore pari a 01 indica che il chiamante ha già deciso di registrare la traccia, mentre 00 indica che non l'ha fatto.

Le raccomandazioni per il flag di campionamento della specifica del contesto di traccia W3C consigliano a un componente di rispettare il flag di campionamento in entrata quando prende una decisione di registrazione e di riflettere una decisione di registrazione definitiva nel flag. Apigee segue questi consigli: rispetta il flag di campionamento in entrata quando decide se registrare una traccia (vedi Precedenza dell'intestazione rispetto alla configurazione locale) e imposta il flag di campionamento nell'intestazione traceparent che propaga ai servizi downstream per indicare se la richiesta viene registrata. Come controllo di sicurezza contro il tracciamento indesiderato attivato dal flag in entrata, imposta sampler su OFF (vedi Disattivare la configurazione del tracciamento distribuito), che disattiva il tracciamento anche per le richieste il cui traceparent ha il flag di campionamento impostato.

Precedenza dell'intestazione sulla configurazione locale

Quando una richiesta in entrata include un'intestazione traceparent, il runtime Apigee utilizza il flag di campionamento di questa intestazione anziché il proprio samplingConfig locale. Una richiesta con il flag di campionamento impostato su 01 viene sempre tracciata; una richiesta con il flag impostato su 00 non viene tracciata. samplingConfig a livello di ambiente si applica solo alle richieste che arrivano senza un'intestazione traceparent.

Disattivare la traccia

Per disattivare la tracciabilità per ogni proxy in un ambiente (esclude gli override del proxy), imposta sampler su OFF nell'ambiente traceConfig. Consulta Disattivare la configurazione del tracciamento distribuito.

Override per proxy

Per attivare la tracciabilità solo per un sottoinsieme di proxy in un ambiente, lascia l'ambiente samplingConfig con sampler impostato su OFF e crea un override per proxy (con sampler impostato su PROBABILITY e un valore samplingRate diverso da zero) per ogni proxy che vuoi tracciare. Consulta Ignora le impostazioni di traccia per i proxy API.

Impatto sul rendimento della frequenza di campionamento

Il samplingRate che configuri influisce direttamente sulle prestazioni del runtime. Ogni richiesta campionata comporta un lavoro aggiuntivo della CPU sul processore di messaggi (generazione ed esportazione degli span) e aggiunge latenza al percorso della richiesta. All'aumentare della frequenza di campionamento, aumenta anche il volume del traffico tracciato per MP, il che può ridurre il throughput e aumentare la latenza finale (p95, p99). L'impatto aumenta con il volume di traffico: a basse velocità di richiesta il sovraccarico è in genere trascurabile, mentre ad alte velocità di richiesta un elevato tasso di campionamento può ridurre in modo significativo la velocità effettiva sostenibile e richiedere una capacità MP aggiuntiva. Nei benchmark interni, l'esecuzione a samplingRate=1.0 (campionamento al 100%) in condizioni di traffico intenso e sostenuto ha ridotto il throughput fino a circa il 15% rispetto all'esecuzione con la tracciabilità disattivata.

Come linea guida generale, mantieni samplingRate basso (ad esempio, 0.1 o inferiore) in produzione e aumentalo solo per proxy specifici tramite override per proxy quando hai bisogno di una visibilità più approfondita. Per un'analisi dettagliata dell'impatto previsto e delle indicazioni sulla capacità, consulta Considerazioni sul rendimento.

Considerazioni sulle prestazioni

Quando abiliti la tracciabilità distribuita per un ambiente runtime Apigee, è previsto un impatto sul rendimento. L'impatto può comportare un aumento dell'utilizzo della memoria, dei requisiti della CPU e della latenza. L'entità dell'impatto dipende dalla complessità del proxy API (ad esempio, il numero di policy), dalla frequenza di campionamento probabilistico (impostata come samplingRate) e, soprattutto, dal volume di traffico tracciato rispetto alla capacità di esportazione degli intervalli per processore di messaggi (MP).

L'MP di Apigee ha una velocità di esportazione dello span finita. Con la configurazione predefinita, un singolo MP può esportare in modo sostenibile circa 820 intervalli al secondo. L'esecuzione di un tipico proxy API genera circa 10 intervalli (pre-flusso proxy, flusso di destinazione, post-flussi, criteri collegati), quindi un singolo MP può tracciare in modo sostenibile circa 82 richieste al secondo con un campionamento del 100%. L'aumento del conteggio delle repliche MP incrementa il limite aggregato in modo lineare.

La seguente tabella riassume l'impatto previsto a samplingRate=1.0 (probabilità del 100%) in due regimi di traffico:

Regime di traffico (per MP) Impatto previsto alle ore samplingRate=1.0 Azione consigliata
Traffico scorrevole (meno di circa 82 richieste tracciate al secondo per MP) Il throughput diminuisce di circa l'1-2%; la latenza media aumenta di circa l'1%; la latenza p99 aumenta di circa il 15-20%. Trascurabile nella pratica. È sicuro abilitare l'impostazione al 100%.
Traffico intenso (molto al di sopra di circa 82 richieste tracciate al secondo per MP) Il throughput diminuisce di circa il 14%; la latenza media aumenta di circa il 24%; la latenza p75 aumenta di circa il 52%; il tasso di errore aumenta di circa 1 punto percentuale. Abbassa samplingRate (ad esempio, a 0.1 o 0.05) o fai lo scale up del numero di repliche MP in modo che ogni MP gestisca un numero inferiore di richieste tracciate al secondo.

Per gli ambienti con requisiti di traffico elevato e bassa latenza, il tasso di campionamento probabilistico consigliato è inferiore o uguale al 10%. Se vuoi utilizzare il tracciamento distribuito per la risoluzione dei problemi, valuta la possibilità di aumentare il campionamento probabilistico (samplingRate) solo per proxy API specifici tramite override per proxy.

Configura i runtime Apigee per Cloud Trace (OpenCensus)

Sia il runtime Apigee che il runtime Apigee hybrid supportano il tracciamento distribuito utilizzando Cloud Trace con OpenCensus. Se utilizzi Jaeger, puoi saltare questa sezione e passare ad Abilitare il tracciamento distribuito per Jaeger con OpenCensus.

Configura il runtime Apigee per Cloud Trace

Per configurare il runtime Apigee per Cloud Trace, il tuo progetto Google Cloud deve avere l'API Cloud Trace abilitata.

Per abilitare l'API:

  1. Nella console Google Cloud , vai ad API e servizi:

    Vai ad API e servizi

  2. Fai clic su Abilita API e servizi.
  3. Abilita l'API Cloud Trace.

Configura il runtime di Apigee hybrid per Cloud Trace

Per configurare il runtime di Apigee hybrid per Cloud Trace, abilita l'API Cloud Trace.

Oltre ad attivare l'API, devi aggiungere il account di servizio iam.gserviceaccount.com per utilizzare Cloud Trace con il runtime ibrido. Per aggiungere il service account, insieme al ruolo e alle chiavi roles/cloudtrace.agent richiesti, segui questi passaggi:

  1. Crea un nuovo account di servizio: 
    gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID
  2. Aggiungi un'associazione della policy IAM al account di servizio: 
    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. Crea una chiave account di servizio e aggiorna overrides.yaml come descritto nei passaggi seguenti.
  4. Crea una chiave dell'account di servizio: 
    gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
  5. Aggiungi il account di servizio al file overrides.yaml. 
    envs:
 - name: ENV_NAME
   serviceAccountPaths:
     runtime: apigee-runtime.json
     synchronizer: apigee-sync.json
     udca: apigee-udca.json
  6. Applica le modifiche al runtime utilizzando Helm: 
    helm upgrade ENV_NAME apigee-env/ \
    --namespace APIGEE_NAMESPACE \
    --set env=ENV_NAME \
    --atomic \
    -f overrides.yaml

Attivare il tracciamento distribuito (OpenCensus)

Prima di attivare la tracciabilità distribuita, crea le variabili di ambiente richieste.

Abilita il tracciamento distribuito per Cloud Trace con OpenCensus

Il seguente esempio mostra come attivare il tracciamento distribuito per Cloud Trace con OpenCensus:

  1. Esegui questa chiamata API 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}
        }'

    Il corpo della richiesta di esempio è costituito dai seguenti elementi:

    • Per supportare Cloud Trace, il parametro exporter è impostato su CLOUD_TRACE. Il parametro traceProtocol, che non è specificato, ha come valore predefinito OpenCensus.
    • Il parametro endpoint è impostato sul progetto Google Cloud in cui vuoi che venga inviata la traccia.
    • samplingRate è impostato su 0,1. Ciò significa che circa il 10% delle chiamate API viene inviato a Distributed Tracing. Per OpenCensus, la frequenza di campionamento massima configurabile è 0.5.

    Una risposta corretta è simile alla seguente:

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

Attiva il tracciamento distribuito per Jaeger con OpenCensus

L'esempio seguente mostra come abilitare la tracciabilità distribuita per 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"
    }'

In questo esempio:

  • Per supportare Jaeger, il parametro exporter è impostato su JAEGER. Il parametro traceProtocol, che non è specificato, ha come valore predefinito OpenCensus.
  • Il parametro endpoint è impostato sulla posizione in cui è installato e configurato Jaeger.
  • samplingRate è impostato su 0,4. Ciò significa che circa il 40% delle chiamate API viene inviato a Distributed Tracing.

Quando abiliti la tracciabilità distribuita per un ambiente runtime Apigee, è previsto un impatto sul rendimento. L'impatto può comportare un aumento della memoria utilizzata, dei requisiti della CPU e della latenza. L'entità dell'impatto dipenderà in parte dalla complessità del proxy API (ad esempio, il numero di policy) e dalla frequenza di campionamento probabilistico (impostata come samplingRate). Maggiore è la frequenza di campionamento, maggiore è l'impatto sulle prestazioni.

Per ulteriori informazioni, vedi Considerazioni sul rendimento.

Visualizzare la configurazione del tracciamento distribuito

Per visualizzare la configurazione di tracciamento distribuito esistente nel runtime, accedi al runtime ed esegui questo comando: 

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

Quando esegui il comando, puoi visualizzare una risposta simile alla seguente:

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

revisionId aumenta a ogni aggiornamento riuscito e updateTime riflette il timestamp del server della modifica più recente. Utilizza questi due campi per confermare che il control plane ha accettato un aggiornamento della configurazione. Entrambi vengono restituiti anche dalla risposta PATCH .../traceConfig.

Aggiorna la configurazione del tracciamento distribuito

Il seguente comando mostra come aggiornare la configurazione di tracciamento distribuito esistente per 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}
        }'

Quando esegui il comando, puoi visualizzare una risposta simile alla seguente:

{
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.6
  },
  "traceProtocol": "OTLP"
}
 In questo esempio, la frequenza di campionamento viene aggiornata a 0.6.

Disattiva la configurazione del tracciamento distribuito

L'esempio seguente mostra come disattivare la tracciabilità distribuita configurata per 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"}
        }'

Quando esegui il comando, puoi visualizzare una risposta simile alla seguente:

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

Eseguire l'override delle impostazioni di traccia per i proxy API

Quando abiliti il tracciamento distribuito nel runtime Apigee, tutti i proxy API nel runtime utilizzano la stessa configurazione per il tracciamento. Tuttavia, puoi ignorare la configurazione del tracciamento distribuito per un proxy API o un gruppo di proxy API. In questo modo avrai un controllo più granulare sulla configurazione della tracciatura.

L'esempio seguente esegue l'override della configurazione di tracciamento distribuito per il proxy 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}}'

Puoi ignorare la configurazione per risolvere i problemi specifici di un proxy API senza dover modificare la configurazione di tutti i proxy API.

Aggiornare gli override delle impostazioni di tracciamento

Per aggiornare l'override della configurazione di tracciamento per un proxy API o un gruppo di proxy API, segui questi passaggi:

  1. Utilizza il seguente comando per recuperare eventuali override esistenti della configurazione di tracciamento: 
    curl -s -H "$TOKEN" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides \
    -X GET

    Questo comando dovrebbe restituire una risposta simile alla seguente, che contiene un campo "name" che identifica il proxy o i proxy regolati dall'override: 

    {
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}
  2. Per aggiornare il proxy, utilizza il valore del campo "name" per inviare una richiesta POST alla configurazione di override per quel proxy,insieme ai valori dei campi aggiornati. Ad esempio: 
    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}}'

Elimina gli override delle impostazioni di traccia

Per eliminare una sostituzione della configurazione di tracciamento per un proxy API o un gruppo di proxy API, segui questi passaggi:

  1. Utilizza il seguente comando per recuperare eventuali override esistenti della configurazione di tracciamento: 
    curl -s -H "$TOKEN" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides \
    -X GET

    Questo comando dovrebbe restituire una risposta simile alla seguente, che contiene un campo "name" che identifica il proxy o i proxy regolati dall'override: 

    {
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}
  2. Per eliminare il proxy, utilizza il valore del campo "name" per inviare una richiesta DELETE alla configurazione di override per quel proxy,insieme ai valori dei campi aggiornati. Ad esempio: 
    curl -s -H "$TOKEN" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1 \
    -X DELETE \

Risolvere i problemi di tracciamento distribuito

Per risolvere i problemi relativi al tracciamento distribuito:

  • Verifica la configurazione del tracciamento distribuito utilizzando l'API traceConfig per assicurarti che corrisponda alle tue esigenze.
  • Verifica che il account di servizio disponga delle autorizzazioni IAM (ruoli) corrette nel progetto di destinazione.
  • Se utilizzi Cloud Trace con OpenTelemetry, controlla gli intervalli in entrata e gli errori relativi all'abilitazione dell'API o alla quota.
  • Se utilizzi un agente di raccolta OpenTelemetry gestito dal cliente, segui questi passaggi:
    • Verifica che Apigee possa raggiungere l'endpoint dell'agente di raccolta. Se utilizzato, controlla la configurazione di Private Service Connect (PSC).
    • Controlla i log di OpenTelemetry Collector per problemi di dati o di connessione.
    • Assicurati che il certificato TLS del raccoglitore sia valido.
  • Esamina i log del runtime Apigee per individuare gli errori di esportazione delle tracce.