Debug e risoluzione dei problemi
Raccogli le informazioni sul cluster e i log di debug per risolvere i problemi relativi a Standard Edition.
Standard Edition in proprio 1.10.3 and earlier versions:
- Per le installazioni online (non isolate fisicamente), la maggior parte dei comandi relativi al ciclo di vita
stanctl, come ad esempio, nonstanctl upvengono eseguiti. - Per le installazioni in modalità air-gap, i
stanctlcomandi continuano a funzionare.
Azione richiesta: eseguire l'aggiornamento stanctl a 1.10.4 o o versioni successive prima di eseguire un'operazione relativa al ciclo di vita.
stanctl1.10.3 o versioni precedenti, qualsiasi flusso di lavoro che arresti i servizi, ad esempio un stanctl down comando, prima di un backup, non può essere completato perché il comando stanctl up successivo non va a buon fine. Esegui l'aggiornamento stanctl a 1.10.4 o o a una versione successiva prima di procedere con questi passaggi.Raccogliere i dati diagnostici per la risoluzione dei problemi
Utilizzare il comando di diagnostica per raccogliere informazioni diagnostiche relative a Kubernetes, piattaforma, nodo e datastore, al fine di risolvere i problemi in un ambiente Standard Edition ( k3s ).
Per eseguire il comando, utilizzare la seguente sintassi:
stanctl diagnostics [flags]
stanctl debug [flags] # Alias (identical behavior)
Una volta completata la raccolta, il comando visualizza il percorso del pacchetto diagnostico generato.
Done! Diagnostics package -> <output-dir> <output-dir>/diagnostics_<YYYYMMDDHHmmss>.tar.gz
Comportamento della directory di output
Il comando crea sempre una cartella con data e ora diagnostics_<YYYYMMDDHHmmss> all'interno della cartella specificata con --output-dir. Se si omette --output-dir, il comando utilizza la directory di lavoro corrente.
Opzioni di comando
I seguenti flag controllano il comportamento della raccolta dei dati diagnostici.
| Contrassegno | Breve | Immettere | Predefinito | Descrizione |
|---|---|---|---|---|
| --output-dir | -o | Indirizzario | Directory di lavoro corrente | Directory principale in cui il comando crea la cartella "diagnostics" con data e ora e l'archivio compresso. Specificare un percorso di directory, non un percorso di file. |
| --deep-debug | N/D | Booleano | false | Esegue una serie aggiuntiva di script di debug approfondito dopo la raccolta dei dati diagnostici standard. La raccolta standard è sempre attiva e abilita solo il livello di script aggiuntivo. |
| --max-log-lines | -l | Numero intero | 20000 | Numero massimo di righe di log raccolte per container. Impostare su 0 per raccogliere i log completi. |
| --log-collection-days | — | Numero intero | 7 | Numero di giorni di registrazioni storiche da raccogliere. |
| --node-collector-image | — | Stringa | Risolto in fase di esecuzione | Immagine del container per il nodo-collector DaemonSet. Sovrascrivere questo valore in ambienti con registry isolati o privati. |
| --node-collector-namespace | — | Stringa | Namespace predefinito | Spazio dei nomi in cui il comando crea e rimuove il nodo temporaneo "node-collector" DaemonSet. |
| --external-script | — | Fettina di stringa | Nessuna | Esegue uno o più script di shell forniti dall'utente durante la raccolta. Passare più script come elenco separato da virgole. Ad esempio, (--external-script a.sh,b.sh) oppure ripetendo il flag (--external-script a.sh --external-script b.sh). |
Flag globale ereditato
| Contrassegno | Descrizione |
|---|---|
| --env-file | Percorso di un .env file. Il comando trasmette i valori contenuti in questo file al motore di diagnostica per la risoluzione delle credenziali del datastore. |
Cosa viene raccolto
Il motore di diagnostica esegue in sequenza i seguenti collettori. Ogni collector scrive i propri dati di output in una directory dedicata all'interno del pacchetto di diagnostica.
Per i collettori di datastore ( Kafka, Cassandra, Elasticsearch e BeeInstana ), stanctl le credenziali vengono caricate automaticamente dalla configurazione.
Risorse di tipo " Kubernetes " con ambito di cluster
Il motore raccoglie le risorse Kubernetes a livello di cluster, tra cui:
- Nodi
- Spazio dei nomi
- ClusterRoles
- ClusterRoleBindings
- StorageClasses
- PersistentVolumes
- CustomResourceDefinitions (CRD)
- Altre risorse senza spazio dei nomi
Informazioni sulla rete dei nodi
Il motore raccoglie informazioni relative alla rete dei nodi, tra cui:
- regole di iptables
- Tabelle di instradamento
- Interfacce di rete
- Parametri di rete sysctl
- Informazioni sulla connettività
Envoy diagnostica
Il motore raccoglie i dati diagnostici di Envoy da Instana pod del bilanciatore di carico Core presenti nel
instana-corenamespace, tra cui:- Statistiche sui cluster
- Configurazione dell'ascoltatore
- Instradamenti
- Informazioni sull'integrità
Risorse " Kubernetes " con spazio dei nomi
Il motore raccoglie le risorse Kubernetes con namespace in tutti i namespace Instana, tra cui:
- Pod
- Distribuzioni
- StatefulSets
- Servizi
- ConfigMaps
- Segreti (valori sensibili omessi)
- Eventi
- ReplicaSets
- DaemonSets
- PersistentVolumeClaims
- HorizontalPodAutoscalers
- Risorse personalizzate (Core, Unit, ClickHouseInstallation, Kafka, Elasticsearch e altre)
Diagnostica dei nodi
Il motore utilizza un file temporaneo denominato “ DaemonSet ” per raccogliere dati diagnostici a livello di nodo, tra cui:
- CPU
- Memoria
- Topologia del disco
- Versione del kernel e del sistema operativo
- Informazioni sull'hardware
- Punti di montaggio
- Utilizzo disco
- valori sysctl
- dmesg
log di systemd journal
Il motore raccoglie i log del journal di systemd a livello di host per:
k3s.service- Servizi di sistema correlati
Configurazione e archiviazione di stanctl
Il motore raccoglie stanctl i file di configurazione e i dati relativi all'utilizzo dello spazio di archiviazione.
File di configurazione:
- instana.yaml
- instana-values.yaml
- dependencies.yaml
- File di stato
- Log di stanctl
Utilizzo archiviazione:
- rischi superiori
- dati
- metriche
- oggetti
Instana diagnostica del backend
Il motore raccoglie i dati diagnostici del backend di Instana dai namespace
instana-coreeinstana-unit, tra cui:- Endpoint clinici
- Metriche interne
- Utilizzo delle risorse del pod
Kafka diagnostica
Il motore raccoglie i dati diagnostici dell' Kafka, tra cui:
- Elenco degli argomenti
- Ritardo gruppo di consumatori
- Configurazione del broker
- Kafka Stato CR
Nota:Le credenziali vengono recuperate automaticamente dalla configurazione di stanctl.Cassandra diagnostica
Il motore raccoglie i dati diagnostici dell' Cassandra, tra cui:
- nodetool status
- nodetool info
- Statistiche tabella
- Convalida CQL
Nota:Le credenziali vengono recuperate automaticamente dalla configurazione di stanctl.Elasticsearch diagnostica
Il motore raccoglie i dati diagnostici dell' Elasticsearch, tra cui:
- Integrità del cluster
- Statistiche di indice
- Assegnazione degli shard
- Elasticsearch Stato CR
Nota:Le credenziali vengono recuperate automaticamente dalla configurazione di stanctl.BeeInstana diagnostica
Il motore raccoglie i dati diagnostici dell' BeeInstana, tra cui:
- Log dell'aggregatore
- Log di Ingestor
- Log di Monconfig
- BeeInstana Stato CR
- Metriche interne
Nota:Le credenziali vengono recuperate automaticamente dalla configurazione di stanctl.Helm informazioni sul lancio
Il motore raccoglie le informazioni relative all Helm e in tutti gli spazi dei nomi, tra cui:
- Nomi delle versioni
- Versioni del grafico
- Stato distribuzione
- Valori (campi sensibili oscurati)
Script di debug approfondito
Nota:Il motore attiva questo collettore solo quando lo si specifica --deep-debug.Il motore esegue una serie selezionata di script diagnostici interni al cluster per una risoluzione dei problemi più approfondita, che in genere include diagnostiche avanzate del datastore.
Metadati incorporati nel pacchetto
Ogni pacchetto diagnostico include i seguenti metadati in SUMMARY.log.
| Campo | Descrizione |
|---|---|
| Versione di Stanctl | Esecuzione della versione binaria di stanctl |
| Edizione | Standard ( k3s ) |
| Modalità cluster | Nodo singolo o multiplo (comprende il tipo di installazione e il numero di nodi) |
| Modalità di rete | Air-gapped (indicato solo se applicabile) |
Comportamento multi-nodo
In un ambiente multinodo, il comando distribuisce automaticamente un nodo-collettore temporaneo DaemonSet con tolleranze aggiuntive per raccogliere informazioni da tutti i nodi. Non sono necessari ulteriori flag.
Modifica il livello di log per i componenti di Instana
Per regolare il volume dei componenti dell' Instana, procedere come segue:
Modifica il file di configurazione principale, ad esempio,
$HOME/.stanctl/values/instana-core/custom-values.yaml.Configurare il livello di log di un componente nel Core o nell'Unit CR. Nell'esempio seguente, il livello di log viene modificato in
DEBUGper ilbutlercomponente :componentConfigs: - name: butler env: - name: COMPONENT_LOGLEVEL # Possible values are DEBUG, INFO, WARN, ERROR (not case-sensitive) value: DEBUGApplica i valori personalizzati eseguendo il seguente comando:
stanctl backend applyPer visualizzare i log, eseguire il seguente comando:
kubectl logs <component name> -n instana-core<nome componente> è il nome del componente per cui si desidera eseguire la risoluzione dei problemi.
Certificati Secure Sockets Layer ( SSL )
Comprendere le configurazioni supportate, le limitazioni e le procedure di risoluzione dei problemi relative ai certificati SSL.
Certificati Wildcard SSL
È possibile utilizzare certificati con caratteri jolly SSL con Instana Standard Edition. Alcune configurazioni con caratteri jolly non sono supportate, mentre determinati modelli di implementazione richiedono un’ulteriore valutazione.
Scenario di esempio
Si consideri la seguente struttura ` DNS `:
Certificato con caratteri jolly:
*.company.comInstana backend:
instana.company.comPunto finale dell'accettore dell'agente:
agent-acceptor.instana.company.comInstana Interfaccia utente:
unit-tenant.instana.company.com
Limiti dei caratteri jolly a livello singolo
In questo scenario non è possibile utilizzare un certificato con caratteri jolly, come ad *.company.com esempio
Motivo: per impostazione predefinita, un asterisco (*) può sostituire solo un'etichetta nel nome di un' DNS. Non può estendersi su più livelli di sottodomini.
Regole di corrispondenza dei certificati
Risultati della ricerca per certificato *.company.com :
www.company.comapi.company.commail.company.com
Il certificato *.company.com non corrisponde:
a.b.company.comdev.api.company.comcompany.com
.) separa le etichette " DNS ". Il carattere jolly sostituisce esattamente una sola etichetta.Per supportare l'implementazione di Instana, utilizzare una delle seguenti opzioni:
- Creare un certificato con caratteri jolly per l'intero dominio di base Instana :
*.instana.company.com - Utilizzare un certificato SAN che includa tutti i nomi host richiesti.
DNS: api.example.com DNS: dev.api.example.com DNS: prod.api.example.com - Combina più voci con caratteri jolly all’interno di un certificato SAN:
DNS: *.example.com DNS: *.api.example.com
Ripristina il certificato autofirmato
È possibile ripristinare un certificato autofirmato TLS precedentemente rimosso.
- Elimina il segreto esistente " TLS ":
kubectl delete secret instana-tls -n instana-core - Generare un nuovo certificato autofirmato:
Risultato:stanctl be apply --core-tls-generate-cert- Viene generato e applicato un nuovo certificato autofirmato SSL.
- TLS La crittografia è abilitata per gli endpoint Instana.
- I browser moderni (come Chrome o Firefox ) visualizzano avvisi di sicurezza poiché il certificato non è stato emesso da un'autorità di certificazione attendibile.
Importante:Sebbene i browser contrassegnino la connessione come non attendibile, tutte le comunicazioni rimangono crittografate.
Riepilogo
- I certificati con caratteri jolly a livello singolo (ad esempio,
*.company.com) non supportano i sottodomini a più livelli. - Instana Lo standard richiede solitamente certificati SAN o certificati con caratteri jolly per il dominio di base.
- Se necessario, è possibile rigenerare in tutta sicurezza i certificati autofirmati, tenendo conto degli avvisi che potrebbero comparire nel browser.
Risoluzione dei problemi
Risolvere questi problemi.
Instana L'agente non viene visualizzato nell'interfaccia utente
Dopo aver eliminato l'agente Instana configurato per il monitoraggio remoto e aver installato l'agente Instana per l'automonitoraggio, è possibile che l'agente non venga visualizzato nell'interfaccia utente di Instana.
È possibile che l'agente stia tentando di connettersi al backend remoto Instana anziché a quello locale Instana.
Per risolvere questo problema, installare l'agente e specificare l'host dell'endpoint di backend e una chiave dell'agente:
stanctl agent apply --agent-cluster-name <cluster-name> --agent-endpoint-host acceptor.instana-core --agent-endpoint-port 8600 --agent-zone-name <zone-name> --agent-key <agent-key-of-local-backend>
Instana Il backend smette di funzionare quando il disco dati dell' Elasticsearch e supera l'85% di utilizzo
Elasticsearch imposta automaticamente l'archivio dati in modalità di sola lettura quando lo spazio utilizzato sul disco supera l'85%. Ciò provoca l'interruzione del funzionamento del backend Instana. Liberare spazio sul disco dati dell' Elasticsearch e oppure aumentarne la capacità per ripristinare il normale funzionamento. Nota: altri dischi “ Instana ” non attivano la modalità di sola lettura a livelli di utilizzo simili (anche superiori al 95%), il che può rendere questo problema di difficile comprensione.
- Spazio libero sul disco dati dell' Elasticsearch
- Aumentare lo spazio su disco assegnato a Elasticsearch
Instana L'aggiornamento del backend non va a buon fine a causa di un'installazione non corretta del grafico " Helm "
L'aggiornamento del backend di Instana non va a buon fine dopo l'esecuzione del stanctl backend apply comando. Potrebbe comparire il seguente errore:
Error: another operation (install/upgrade/rollback) is in progress
Nel file console.log potresti trovare informazioni simili alle seguenti voci:
ts=2025-05-26T12:26:09Z level=INFO msg="upgrading Helm chart" name=instana-core release=instana-core version=1.8.1 namespace=instana-core
ts=2025-05-26T12:26:09Z level=DEBUG msg="preparing upgrade for instana-core"
Questo problema indica che l'installazione del grafico " Helm " del grafico principale corrente è danneggiata; è possibile ripristinarla utilizzando il seguente comando:
- Elimina il vecchio segreto del grafico " Helm " dallo
instana-corespazio dei nomi.kubectl delete secret -n instana-core -l owner=helm - Aggiornare il backend.
stanctl up
L'agente host non riesce a connettersi al backend Instana sugli host SLES
Dopo aver installato l'agente host sull'host locale su un sistema SUSE Linux Enterprise Server (SLES) 15 SP5 per il monitoraggio automatico, l'agente non si connette automaticamente al backend Instana.
È necessario utilizzare l'agente esterno URL per connettersi al backend come host remoto.
Utilizzare il seguente comando:
stanctl agent apply --agent-endpoint-host agent-acceptor.<base_domain> --agent-endpoint-port 8443
Kafka I pod mostrano lo stato dell' CrashLoopBackOff
Kafka I pod non si riavviano dopo lo spegnimento dell'host backend di Instana. Potresti visualizzare lo CrashLoopBackOff stato dei pod di Kafka.
Per risolvere il problema, riavvia il backend di Instana.
- Chiudere il backend.
stanctl down - Avviare il backend.
stanctl up
Una volta riavviato il backend, controlla lo stato dei pod Kafka .
kubectl get pods --all-namespaces | grep kafka
Lo stato del pod Kafka deve essere visualizzato come Running.
I test sintetici pianificati non vengono eseguiti dopo un'operazione di backup e ripristino di Instana
Dopo il ripristino dei dati del backend e degli agenti di Instana, i test sintetici pianificati non vengono eseguiti.
Per risolvere questo problema, riavvia il pod synthetic-pop-controller sul cluster in cui è installato.
Standard Edition L'installazione su RHEL 9.3 non va a buon fine
Red Hat® Enterprise Linux® 9.3 utilizza iptables 1.8.8.
Se stai installando Standard Edition su RHEL 9.3, l'installazione potrebbe non andare a buon fine a causa di iptables 1.8.8.
Per risolvere il problema, aggiornare l'host a RHEl 9.4, che aggiorna anche iptables alla versione 1.8.10.
L'aggiornamento non va a buon fine su Standard Edition 1.9.x
Quando si esegue l'aggiornamento di Standard Edition 1.9.x a una versione più recente, è possibile che venga visualizzato il seguente errore:
Error: installation failed for prerequisite app coredns: Unable to continue with install: ConfigMap "coredns" in namespace "kube-system" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "coredns"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "kube-system"
Per risolvere il problema, esegui nuovamente il stanctl up comando.
L'aggiornamento non va a buon fine con gli errori "CPU insufficiente" o "Memoria insufficiente"
Durante gli aggiornamenti su distribuzioni di tipo " K3s " a nodo singolo con risorse limitate o in ambienti in cui non è possibile aggiungere capacità temporanea, potresti riscontrare uno dei seguenti problemi:
- Errori come"Insufficient CPU"oppure"Insufficient memory"
- I baccelli che rimangono in unPendingstato
La strategia predefinita " RollingUpdate " richiede una capacità aggiuntiva temporanea per eseguire contemporaneamente sia i pod esistenti che quelli nuovi durante l'aggiornamento. Su sistemi con risorse limitate, questo requisito può superare la capacità disponibile della CPU o della memoria, anche quando il livello di utilizzo complessivo sembra basso.
stanctl up --core-update-strategy=RecreatePer ulteriori informazioni sulla strategia di aggiornamento, consultare la sezione "Configurazione della strategia di aggiornamento per gli aggiornamenti"
Systemd non imposta una directory di lavoro predefinita
Quando stanctl viene avviato da un servizio systemd, systemd non imposta automaticamente una directory di lavoro. Se non si specifica una directory di lavoro, systemd esegue il servizio da /. Questa operazione può comportare stanctl la creazione di file, come i dati dei cluster o le configurazioni di Kubernetes, in una posizione .stanctlerrata (spesso / o /root/), anche se il servizio utilizza un utente non root.
Per risolvere il problema, è necessario aggiungere una WorkingDirectory= riga al servizio systemd per creare i file nella directory home corretta degli utenti. Ad esempio, WorkingDirectory=/home/instana.
Impossibile aggiornare la licenza
Quando si esegue il stanctl license update comando, è possibile che l'operazione non vada a buon fine e venga visualizzato il seguente messaggio di errore:
...
no dependency found: 'instana-core'
...
Esegui i seguenti comandi per aggiornare la licenza:
stanctl license download --sales-key=<your-key>
stanctl backend apply
Instana L'aggiornamento del backend non va a buon fine a causa dell'esaurimento dello spazio su disco del nodo
L'installazione o l'aggiornamento del backend di Instana potrebbe non andare a buon fine se il nodo è sottoposto a un carico eccessivo sul disco.
Sintomi
- L'installazione o l'aggiornamento del backend non va a buon fine.
- I pod sono ancora in sospeso.
- Alcuni carichi di lavoro mostrano
ContainerStatusUnknown.
Causa
Durante l'installazione, l'aggiornamento o l'importazione di pacchetti in modalità air-gapped, l'utilizzo del disco aumenta temporaneamente mentre vengono elaborate le immagini dei container e gli artefatti. Se il nodo esaurisce lo spazio su disco, Kubernetes imposta una condizione di " DiskPressure " e impedisce l'avvio di nuovi pod.
Verifica
- Esegui il seguente comando per verificare lo stato del nodo:
kubectl describe node <node-name>Nella sezione "Condizioni", seleziona l'opzione " DiskPressure ".
- Esegui il seguente comando per verificare l'utilizzo del disco:
df -hVerificare se lo spazio su disco è quasi esaurito o ha raggiunto la capacità massima.
Soluzione
- Elimina le immagini dei container inutilizzate o i file superflui per liberare spazio su disco.
- Aumentare la capacità di archiviazione del nodo.
Ripristino
Se i carichi di lavoro rimangono in quello ContainerStatusUnknown stato dopo aver liberato spazio su disco, riavviare il nodo. Una volta completato il riavvio, riprova a eseguire l'installazione o l'aggiornamento.
La licenza non è valida o manca
Se la licenza non è valida o manca, il backend impedisce agli agenti di connettersi.
Quando ciò accade
- La licenza importata non è valida.
- L'operatore dell' Instana e non può applicare la licenza al backend di Groundskeeper.
Come risolvere i problemi
- Verificare che la chiave di vendita contenuta nel segreto principale corrisponda alle stringhe di licenza presenti nel segreto dell'unità. Se i dati non corrispondono, scarica nuovamente la licenza utilizzando il codice di vendita corretto.
- Controlla i log dell'operatore di Instana per verificare la presenza di errori nell'importazione delle licenze:
kubectl logs -n instana-operator deployment/instana-operator --tail=100 - Controlla il componente backend di Groundskeeper, lo stato del pod e i log:
kubectl get pods -n instana-core | grep groundskeeper - Se la licenza risulta ancora non valida, contatta l'assistenza di IBM.
L'installazione non va a buon fine e viene visualizzato il messaggio “Errore fatale di glibc: la CPU non supporta l' x86‑64‑v3””
Sintomo
stanctl install, generando un errore del tipo:Fatal glibc error: CPU does not support x86-64-v3
Questo errore si verifica in genere prima che tutti i componenti siano stati installati e può impedire l'avvio di servizi quali Cassandra e Kafka.
Causa
Questo errore indica che il sistema operativo non è in grado di rilevare il set di istruzioni " x86‑64‑v3 ". La causa più comune è una configurazione della CPU della macchina virtuale che non rende disponibili i flag della CPU richiesti, spesso a causa di impostazioni di compatibilità con versioni precedenti.
Risoluzione
- Quando si configura la macchina virtuale, evitare di utilizzare i profili di compatibilità CPU legacy.
- Assicurati che la mascheratura della CPU non sia abilitata.
- Se la compatibilità avanzata con l' vMotion (EVC) è abilitata, verificare che sia impostata su un livello che supporti le istruzioni " x86‑64‑v3 ".
- Spegnere la macchina virtuale e aggiornare la configurazione della CPU.
- Se necessario, ricrea la macchina virtuale con le impostazioni della CPU aggiornate.
Contatta il supporto
Se non è possibile risolvere il problema in modo autonomo, rivolgersi al supporto IBM. Fornire il file di archiviazione creato al team di supporto.