Guida per l'utente di BPA Distributed Tracing Framework v5.1

• Introduzione
  • Zipkin
  • @opentelemetria/api
• Componenti principali
• Prerequisiti
  • Requisiti di rete
• Docker compone la distribuzione
  • Abilitazione del profilo di monitoraggio
  • Verifica del contenitore Zipkin
• Abilitazione del trace nei servizi
  • Gerarchia caricamento configurazione
    • Configurazione specifica per il pod
      • Scenario d'uso
      • Scenario di esempio
    • Configurazione globale
      • Scenario d'uso
      • Scenario di esempio
    • Configurazione fallback
      • Scenario d'uso
  • Impostazione della configurazione di traccia
    • Proprietà di configurazione
  • Applicazione delle modifiche alla configurazione
    • Comando di aggiornamento del timone
• Installazione di Kubernetes e Helm
  • Abilitazione del monitoraggio nei valori
  • Distribuzione del servizio Zipkin
  • Verifica della distribuzione
  • Verifica dello stato del servizio
• Accesso e monitoraggio
  • Accesso a 1 nodo al dashboard Zipkin
  • Accesso Kubernetes a 3 nodi al dashboard Zipkin
  • Utilizzo dell'interfaccia utente Zipkin
• Tracce e estensioni

Introduzione

Zipkin

Zipkin è un sistema di traccia distribuita che consente di raccogliere i dati di temporizzazione necessari per risolvere i problemi di latenza nell'architettura del servizio. In questa guida vengono fornite istruzioni per la distribuzione di Zipkin e l'attivazione della traccia nei servizi della piattaforma BPA.

@opentelemetria/api

Il pacchetto @opentelemetry/api è l'API di base per OpenTelemetry in Node.js. Fornisce interfacce e classi per la creazione e la gestione di tracce, estensioni e propagazione del contesto. Questo pacchetto consente agli sviluppatori di instrumentare le loro applicazioni per raccogliere dati di telemetria come tracce e metriche, che possono poi essere esportati in back-end come Zipkin per l'analisi.

Componenti principali

I componenti principali di Zipkin includono:

• Server Zipkin: Interfaccia utente e raccoglitore di traccia centrale
• Telemetria aperta: Libreria di strumentazione per la traccia
• Elasticsearch: Back-end di archiviazione per dati di traccia
• SSL (Secure Sockets Layer) e TLS (Transport Layer Security): Comunicazioni sicure

Prerequisiti

Requisiti di rete

Per distribuire Zipkin e abilitare la traccia, sono necessari i seguenti requisiti di rete:

• Porta 9412: Endpoint API HTTPS (Zipkin Hypertext Transfer Protocol Secure)
• Porta 9411: Endpoint di gestione HTTP (Hypertext Transfer Protocol) Zipkin
• Porta 9200: Accesso al cluster Elasticsearch

Docker compone la distribuzione

Abilitazione del profilo di monitoraggio

1. Avviare l'alloggiamento di espansione a 1 nodo BPA dal seguente percorso:

   cd /opt/bpa/bpa-{build_version}/scripts

2. Eseguire lo script bash con l'opzione di monitoraggio utilizzando il comando seguente:

   ./startbpa.1node.sh monitoring

Verifica del contenitore Zipkin

1. Per controllare lo stato del contenitore, eseguire il comando seguente:

   docker ps | grep tracers-zipkin

2. Per visualizzare i log di un contenitore Zipkin. eseguire il comando seguente:

   docker logs tracers-zipkin -f

Abilitazione del trace nei servizi

L'applicazione BPA supporta una configurazione di traccia flessibile tramite i file "tracingConfig.json". Il sistema implementa un meccanismo di caricamento della configurazione gerarchica con tre (3) livelli di precedenza per adattarsi a diversi scenari di distribuzione.

Gerarchia caricamento configurazione

L'applicazione carica le configurazioni di traccia nel seguente ordine in base alla precedenza:

Configurazione specifica per il pod

Percorso: bpa-helm-chart/charts/<nome servizio>/public_conf

Scenario d'uso

• Configurazione di traccia individuale specifica per il pod
• Consente impostazioni di traccia diverse per servizi o pod specifici
• Posizionamento manuale richiesto: Gli utenti devono inserire manualmente questo file nel percorso della cartella del pod: bpa-helm-chart/charts/<nome servizio>/public_conf

Scenario di esempio

• Abilita traccia dettagliata solo per i servizi critici
• Frequenze di campionamento diverse per i diversi microservizi
• Traccia specifica del debug per la risoluzione dei problemi dei pod

Configurazione globale

Percorso: bpa-helm-chart/bpa/conf/common/globals/tracingConfig.json

Scenario d'uso

• Configurazione di traccia globale per tutti i contenitori e i pod
• Gestione centralizzata delle tracce
• Impatto globale: Le modifiche apportate a questo file influiscono su tutti i pod nella distribuzione

Scenario di esempio

• Abilitare e disabilitare la traccia nell'intera distribuzione BPA
• Impostazione di criteri di traccia uniformi per l'ambiente di produzione
• Conformità centralizzata e requisiti di monitoraggio

Configurazione fallback

Percorso: ../conf/tracingConfig.json (fallback)

Scenario d'uso

• Configurazione di traccia predefinita fornita con l'applicazione
• Impostazioni predefinite ambiente di sviluppo
• Assicura che l'applicazione non abbia mai esito negativo a causa di una configurazione di traccia mancante

Se un file di configurazione è in formato non corretto o illeggibile, il sistema:

• Registra l'errore
• Per impostazione predefinita {enable: false} per evitare errori di traccia
• Continua l'avvio delle applicazioni

Impostazione della configurazione di traccia

Creare o aggiornare il file "tracingConfig.json" con il seguente contenuto nel percorso della cartella del pod:

bpa-helm-chart/charts/<nome servizio>/public_conf/

Esempi:

• Per abilitare la traccia

  {
  
          "enable": true
  
      }

• Per disabilitare la traccia:

  {
  
        "enable": false
  
      }

Proprietà di configurazione

• enable (booleano) (obbligatorio): Controlla se la traccia è abilitata o disabilitata per l'applicazione
• vero: Abilita la traccia distribuita
  • L'applicazione inizializza l'helper di traccia
  • Le tracce vengono raccolte e inviate al back-end configurato
  • Funzionalità di monitoraggio e debug delle prestazioni attivate
• falso: Disabilita la traccia distribuita
  • Nessun sovraccarico di analisi sulle prestazioni delle applicazioni
  • Nessuna raccolta o trasmissione di dati di traccia
  • L'applicazione viene eseguita senza la strumentazione di analisi

Applicazione delle modifiche alla configurazione

Comando di aggiornamento del timone

Dopo aver posizionato i file "tracingConfig.json" nelle posizioni appropriate, applicare le modifiche utilizzando il comando di aggiornamento Helm:

helm upgrade bpa-rel --namespace bpa-ns /opt/bpa-helm-chart

Analisi stratificata comandi:

• aggiornamento helm: Aggiorna una release di Helm esistente
• bpa-rel: Nome della release del timone BPA
• —namespace bpa-ns: Specifica lo spazio dei nomi Kubernetes in cui viene distribuito BPA
• /opt/bpa-helm-chart: Percorso della directory del grafico del timone BPA

Installazione di Kubernetes e Helm

Abilitazione del monitoraggio nei valori

Nel seguente percorso del grafico a elmetto, modificare i valori di elmetto nel file "values.yaml" per abilitare il monitoraggio:

yaml
  global:
  enableMonitoring: true

Distribuzione del servizio Zipkin

Distribuire il servizio Zipkin utilizzando il seguente comando Helm:

helm install bpa-rel --create-namespace --namespace bpa-ns 

Verifica della distribuzione

Utilizzare i comandi seguenti per verificare la distribuzione:

kubectl get pods -n bpa-ns | grep tracers-zipkin
kubectl get svc -n bpa-ns | grep tracers-zipkin

Verifica dello stato del servizio

Per visualizzare i registri del pod, utilizzare il comando seguente:

kubectl logs -n bpa-ns deployment/tracers-zipkin -f

Per controllare gli endpoint del servizio, utilizzare il comando seguente:

kubectl describe svc tracers-zipkin -n bpa-ns

Accesso e monitoraggio

Accesso a 1 nodo al dashboard Zipkin

URL: https://<SERVER IP>:9412/zipkin/

Accesso Kubernetes a 3 nodi al dashboard Zipkin

URL: https://<cluster-ip>:30900/zipkin/

Utilizzo dell'interfaccia utente Zipkin

Il dashboard Zipkin fornisce un'interfaccia utente per la ricerca e la visualizzazione delle tracce. I componenti principali includono:

• Elenco a discesa Nome servizio: Filtra le tracce in base al nome del servizio

Nome servizio

• Selettore intervallo di tempo: Definire la finestra temporale per la ricerca di traccia

• Elenco di traccia: Visualizza un elenco di tracce corrispondenti ai criteri di ricerca

• Sequenza temporale traccia: Rappresentazione visiva degli intervalli di tempo (ad esempio, span) all'interno di una traccia

• Dettagli estensione: Visualizzazione dettagliata di ciascun intervallo, inclusi durata, tag e log.

Tracce e estensioni

I tracciatori sono responsabili della creazione e della gestione delle estensioni. Un oggetto tracer è associato a un servizio o a un componente dell'applicazione specifico. Gli span rappresentano una singola unità di lavoro o di operazione all'interno di una traccia. Ogni estensione contiene informazioni quali il nome dell'operazione, l'ora di inizio e di fine, gli attributi e le relazioni padre-figlio con altre estensioni.