Débogage et dépannage

Modifier en ligne

Recueillez les informations relatives au cluster et les journaux de débogage afin de résoudre les problèmes liés à l' Standard Edition.

Attention :

Standard Edition en auto-hébergement 1.10.3 and earlier versions :

  • Pour les installations en ligne (sans isolation physique), la plupart des commandes stanctl de gestion du cycle de vie, telles que [...] stanctl up , ne s'exécuteront pas.
  • Pour les installations en mode air-gap, les stanctl commandes continuent de fonctionner.

Action requise : effectuez une mise à niveau stanctl vers la version 1.10.4 ou une version ultérieure avant d'effectuer une opération liée au cycle de vie.

Exemple : dans les déploiements en ligne exécutant stanctl1.10.3 ou une version antérieure, tout workflow qui arrête des services, par exemple une stanctl down commande, avant une sauvegarde, ne peut pas aboutir car la commande stanctl up suivante échoue. Mettez à jour stanctl votre système vers la version 1.10.4 ou une version ultérieure avant de suivre ces étapes.

Recueillir des informations

Modifier en ligne

Créez un fichier archive contenant des informations sur votre cluster. Vous pouvez utiliser les informations du fichier pour identifier et résoudre les problèmes ou partager le fichier avec l'équipe de support.

Le fichier archive collecte les informations suivantes:

  • Journaux de conteneur
  • Manifestes de ressources (au format « YAML »)
  • stanctl journaux
  • Informations système incluant l'utilisation de la mémoire, de l'unité centrale et de l'unité centrale
  • Montages de disque et utilisation
  • Fichiers ouverts (alloués, libres et maximum)
  • Journaux du backend

Utilisez la commande suivante pour créer le fichier archive:

stanctl debug

Une fois que vous avez exécuté la commande, les messages suivants s'affichent. Lorsque vous voyez Done! dans les messages, cela signifie que votre fichier archive est prêt.

./stanctl debug
⠼ Streaming container logs  [26s] ✓
⠸ Gathering resource manifests  [27s] ✓
⠋ Gathering stanctl config files  [0s] ✓
⠋ Gathering system information  [0s] ✓
⠹ Creating tar file  [0s] ✓

----------------------
Done!
Debug package -> debug_20231027111737
Compressed debug package -> debug_20231027111737.tar.gz
----------------------

Régler le niveau de journalisation des composants d' Instana

Modifier en ligne

Pour régler le niveau des composants d' Instana, procédez comme suit :

  1. Modifiez le fichier de configuration principal, par exemple, $HOME/.stanctl/values/instana-core/custom-values.yaml.

  2. Configurer le niveau de journalisation d'un composant dans le CR Core ou Unit. Dans l'exemple suivant, le niveau de journalisation est modifié pour DEBUG le butler composant :

    componentConfigs:
  - name: butler
    env:
      - name: COMPONENT_LOGLEVEL
        # Possible values are DEBUG, INFO, WARN, ERROR (not case-sensitive)
        value: DEBUG

  3. Appliquez les valeurs personnalisées en exécutant la commande suivante :

    stanctl backend apply

  4. Pour consulter les journaux, exécutez la commande suivante :

    kubectl logs <component name> -n instana-core

    <nom du composant> est le nom du composant pour lequel vous souhaitez effectuer un dépannage.

Certificats SSL ( SSL )

Modifier en ligne

Comprendre les configurations prises en charge, les restrictions et les procédures de dépannage relatives aux certificats d' SSL.

Certificats Wildcard d' SSL

Vous pouvez utiliser des certificats génériques ( SSL ) avec Instana Standard Edition. Certaines configurations avec caractères génériques ne sont pas prises en charge, et certains modèles de déploiement nécessitent une attention particulière.

Exemple de scénario

Supposons la structure d' DNS suivante :

  • Certificat générique : *.company.com

  • Instana backend : instana.company.com

  • Point final de l'accepteur d'agent : agent-acceptor.instana.company.com

  • Instana Interface utilisateur : unit-tenant.instana.company.com

Limites des caractères génériques à un seul niveau

Dans ce cas de figure, *.company.com vous ne pouvez pas utiliser de certificat générique.

Raison : par définition, un astérisque (*) ne peut remplacer qu'un seul élément dans un nom d' DNS. Il ne peut pas s'étendre sur plusieurs niveaux de sous-domaines.

Règles de correspondance des certificats

Le certificat *.company.com correspond à :

  • www.company.com
  • api.company.com
  • mail.company.com

Le certificat *.company.com ne correspond pas :

  • a.b.company.com
  • dev.api.company.com
  • company.com
Remarque : chaque point (.) sépare les étiquettes d' DNS. Le caractère générique ne remplace qu'une seule étiquette.

Pour prendre en charge le déploiement d' Instana, utilisez l'une des options suivantes :

  • Créer un certificat générique pour le domaine de base complet Instana :
    *.instana.company.com
  • Utilisez un certificat SAN qui répertorie tous les noms d'hôte requis.
    DNS: api.example.com
DNS: dev.api.example.com
DNS: prod.api.example.com
  • Combiner plusieurs entrées avec caractères génériques dans un certificat SAN :
    DNS: *.example.com
DNS: *.api.example.com

Restaurer le certificat auto-signé

Vous pouvez restaurer un certificat d' TLS e auto-signé qui a été supprimé précédemment.

  1. Supprimez le secret existant « TLS » :
    kubectl delete secret instana-tls -n instana-core
  2. Générer un nouveau certificat auto-signé :
    stanctl be apply --core-tls-generate-cert
    Résultat :
    • Un nouveau certificat auto-signé SSL est généré et appliqué.
    • TLS Le chiffrement est activé pour les terminaux d' Instana.
    • Les navigateurs modernes (tels que Chrome ou Firefox ) affichent des avertissements de sécurité car le certificat n'est pas délivré par une autorité de certification de confiance.
    Important : bien que les navigateurs signalent que la connexion n'est pas sécurisée, toutes les communications restent cryptées.

Récapitulatif

  • Les certificats génériques à un seul niveau (par exemple, *.company.com) ne prennent pas en charge les sous-domaines à plusieurs niveaux.
  • Instana La norme exige généralement des certificats SAN ou des certificats génériques de domaine de base.
  • Vous pouvez régénérer en toute sécurité des certificats auto-signés lorsque cela s'avère nécessaire, en tenant compte des avertissements habituels des navigateurs.

Traitement des incidents

Modifier en ligne

Résolvez ces problèmes.

Instana l'agent n'apparaît pas dans l'interface utilisateur

Modifier en ligne

Une fois que vous avez supprimé l'agent Instana configuré pour la surveillance à distance et installé l'agent Instana pour l'autosurveillance, il se peut que l'agent n'apparaisse pas dans l'interface utilisateur de Instana.

Il se peut que l'agent tente de se connecter au serveur distant Instana au lieu du serveur local Instana.

Pour résoudre ce problème, installez l'agent et spécifiez l'hôte du noeud final dorsal et une clé d'agent:

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 Le backend cesse de fonctionner lorsque le disque de données de l' Elasticsearch ation dépasse 85 % de son espace disponible

Modifier en ligne

Elasticsearch passe automatiquement son magasin de données en mode lecture seule lorsque le disque qu'il utilise atteint un taux d'utilisation supérieur à 85 %. Cela entraîne l'arrêt du fonctionnement du backend Instana. Libérez de l'espace sur le disque de données de l' Elasticsearch, ou augmentez sa capacité afin de rétablir un fonctionnement normal. Remarque : les autres disques « Instana » ne passent pas en mode lecture seule à des taux d'utilisation similaires (même supérieurs à 95 %), ce qui peut rendre ce problème difficile à comprendre.

Pour résoudre ce problème, procédez de l'une des manières suivantes :
  • Libérer de l'espace sur le disque de données de l' Elasticsearch
  • Augmenter l'espace disque alloué à Elasticsearch
Lorsque l'espace disponible est suffisant, Elasticsearch reprend ses opérations d'écriture normales et le backend redevient opérationnel.
Remarque : les autres disques de type « Instana » ne passent pas en mode lecture seule à des niveaux d'utilisation similaires (même supérieurs à 95 %), ce qui peut prêter à confusion lors du dépannage.

Instana La mise à jour du backend échoue en raison d'une installation défectueuse du graphique « Helm »

Modifier en ligne

La mise à niveau du backend d' Instana échoue après l'exécution de la stanctl backend apply commande. L'erreur suivante peut s'afficher :

Error: another operation (install/upgrade/rollback) is in progress

Dans le console.log fichier, vous pourriez voir des informations similaires aux entrées suivantes :

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"

Ce problème indique une installation corrompue du graphique « Helm » du graphique principal actuel; vous pouvez la réinitialiser à l'aide de la commande suivante :

  1. Supprimez l'ancienne clé secrète « Helm » de l'espace instana-core de noms.
    kubectl delete secret -n instana-core -l owner=helm
  2. Mettre à jour le backend.
stanctl up

L'agent hôte ne parvient pas à se connecter au backend Instana sur les hôtes SLES

Modifier en ligne

Une fois l'agent hôte installé sur l'hôte local d'un système SLES ( SUSE Linux Enterprise Server ) 15 SP5 à des fins d'autosurveillance, l'agent ne se connecte pas automatiquement au backend Instana.

Vous devez utiliser l'agent externe URL pour vous connecter au serveur en tant qu'hôte distant.

Utilisez la commande suivante :

stanctl agent apply --agent-endpoint-host agent-acceptor.<base_domain> --agent-endpoint-port 8443

Kafka Les pods affichent l'état de l' CrashLoopBackOff

Modifier en ligne

Kafka Les pods ne redémarrent pas après l'arrêt de l'hôte backend d' Instana. Vous pouvez consulter CrashLoopBackOff l'état des pods de l' Kafka.

Pour résoudre le problème, redémarrez le backend d' Instana.

  1. Arrêtez le système de back end.
    stanctl down
  2. Démarrez le système de back end.
    stanctl up

Une fois le système dorsal redémarré, vérifiez le statut des pods Kafka .

kubectl get pods --all-namespaces | grep kafka

Le statut du pod Kafka doit être Running.

Les tests synthétiques planifiés ne s'exécutent pas après une sauvegarde et une restauration d' Instana

Modifier en ligne

Une fois les données du backend et des agents d' Instana s restaurées, les tests synthétiques planifiés ne s'exécutent pas.

Pour résoudre ce problème, redémarrez le pod synthetic-pop-controller sur le cluster où il est installé.

Standard Edition L'installation sur RHEL 9.3 échoue

Modifier en ligne

Red Hat® Enterprise Linux® 9.3 utilise l' 1.8.8 iptables.

Si vous installez Standard Edition sur RHEL 9.3, l'installation risque d'échouer en raison d'un problème avec iptables 1.8.8.

Pour contourner le problème, mettez à niveau votre hôte vers RHEl 9.4, qui met également à niveau iptables vers la version 1.8.10.

Échec de la mise à niveau sur Standard Edition 1.9.x

Modifier en ligne

Lorsque vous mettez à niveau Standard Edition 1.9.x vers une version plus récente, vous pouvez rencontrer l'erreur suivante :

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"

Pour résoudre ce problème, relancez la stanctl up commande.

La mise à niveau échoue avec les messages d'erreur « CPU insuffisant » ou « Mémoire insuffisante »

Modifier en ligne

Vous pourriez rencontrer l'un des problèmes suivants lors de mises à niveau sur des déploiements à nœud unique d' K3s, dans des environnements aux ressources limitées ou où l'ajout de capacité temporaire n'est pas envisageable :

  • Des erreurs telles que"Insufficient CPU"ou"Insufficient memory"
  • Les cosses qui restent dans unPendingétat

La stratégie de mise à niveau par défaut « RollingUpdate » nécessite une capacité supplémentaire temporaire pour exécuter simultanément les anciens et les nouveaux pods pendant la mise à niveau. Sur les systèmes aux ressources limitées, cette exigence peut dépasser la capacité disponible du processeur ou de la mémoire, même lorsque le taux d'utilisation global semble faible.

Pour résoudre ce problème, utilisez la stratégie de mise à jour « Recreate », qui ne nécessite pas de capacité supplémentaire pendant les mises à niveau :
stanctl up --core-update-strategy=Recreate

Pour plus d'informations sur la stratégie de mise à jour, consultez la section « Configuration de la stratégie de mise à jour pour les mises à niveau ».

Remarque :

La stratégie « Recreate » entraîne une brève interruption de service (de quelques minutes) pendant le processus de mise à niveau. Ce compromis est généralement acceptable pour les environnements hors production ou les systèmes dans lesquels il n'est pas possible d'augmenter la capacité matérielle.

Systemd ne définit pas de répertoire de travail par défaut

Modifier en ligne

Lorsqu'il stanctl est lancé par un service systemd, systemd ne définit pas de répertoire de travail de lui-même. Si vous n'indiquez pas de répertoire de travail, systemd exécute le service à partir de /. Cette opération peut entraîner stanctl la création de fichiers, tels que des données de cluster, .stanctl ou des fichiers de configuration de l' Kubernetes, à un emplacement incorrect (souvent / ou /root/), même si le service utilise un utilisateur autre que root.

Pour remédier à ce problème, vous devez ajouter une WorkingDirectory= ligne au service systemd afin de créer les fichiers dans le répertoire personnel approprié de chaque utilisateur. Par exemple, WorkingDirectory=/home/instana.

Impossible de mettre à jour la licence

Modifier en ligne

Lorsque vous exécutez la stanctl license update commande, celle-ci peut échouer et afficher le message d'erreur suivant :

...
no dependency found: 'instana-core'
...

Exécutez les commandes suivantes pour mettre à jour la licence :

stanctl license download --sales-key=<your-key>
stanctl backend apply

Instana La mise à niveau du backend échoue en raison d'une surcharge du disque du nœud

Modifier en ligne

L'installation ou la mise à niveau du backend d' Instana peut échouer si le nœud est soumis à une forte charge de lecture/écriture sur le disque.

Symptômes

Vous pourriez constater l'un ou plusieurs des symptômes suivants :
  • L'installation ou la mise à jour du backend échoue.
  • Les pods sont toujours en attente.
  • Certaines charges de travail présentent ContainerStatusUnknown.

Cause

Lors de l'installation, de la mise à niveau ou de l'importation de paquets en mode air-gapped, l'utilisation du disque augmente temporairement pendant le traitement des images de conteneurs et des artefacts. Si le nœud manque d'espace disque, Kubernetes déclenche une condition d' DiskPressure e et empêche le démarrage de nouveaux pods.

Vérification

  1. Exécutez la commande suivante pour vérifier l'état du nœud :
    kubectl describe node <node-name>

    Dans la section « Conditions », consultez la rubrique « DiskPressure ».

  2. Exécutez la commande suivante pour vérifier l'utilisation du disque :
    df -h

    Vérifiez si l'espace disque disponible est proche de la limite maximale ou s'il a déjà atteint cette limite.

La solution

Effectuez l'une des opérations suivantes pour résoudre le problème :
  • Supprimez les images de conteneurs inutilisées ou les fichiers superflus pour libérer de l'espace disque.
  • Augmenter la capacité de stockage du nœud.

Récupération

Si les charges de travail restent dans cet ContainerStatusUnknown état après avoir libéré de l'espace disque, redémarrez le nœud. Une fois le redémarrage terminé, réessayez l'installation ou la mise à jour.

La licence n'est pas valide ou est manquante

Modifier en ligne

Si la licence n'est pas valide ou fait défaut, le serveur empêche les agents de se connecter.

Lorsque cela se produit

  • La licence importée n'est pas valide.
  • L'opérateur « Instana » ne peut pas appliquer la licence au backend de Groundskeeper.

Comment résoudre les problèmes

  1. Vérifiez que la clé de vente figurant dans le secret principal correspond aux chaînes de licence contenues dans le secret de l'unité. Si elles ne correspondent pas, téléchargez à nouveau la licence en utilisant la clé de vente appropriée.
  2. Vérifiez les journaux de l'opérateur « Instana » pour détecter d'éventuelles erreurs d'importation de licence :
    kubectl logs -n instana-operator deployment/instana-operator --tail=100
  3. Vérifiez le composant backend de Groundskeeper, l'état du pod et les journaux :
    kubectl get pods -n instana-core | grep groundskeeper
  4. Si la licence apparaît toujours comme non valide, contactez le service d'assistance d' IBM.

L'installation échoue avec le message « Erreur fatale glibc : le processeur ne prend pas en charge l' x86‑64‑v2”

Modifier en ligne

Symptôme

L'installation échoue dès le début lorsque vous exécutez stanctl install, avec une erreur du type :
Fatal glibc error: CPU does not support x86-64-v2

Cette erreur survient généralement avant l'installation de tous les composants et peut empêcher le démarrage de certains services, tels que Cassandra et Kafka.

Cause

Cette erreur indique que le système d'exploitation ne parvient pas à détecter le jeu d'instructions d' x86‑64‑v2. La cause la plus fréquente est une configuration du processeur de la machine virtuelle qui ne met pas à disposition les indicateurs CPU requis, souvent en raison de paramètres de compatibilité avec les versions antérieures.

Résolution

Dans les environnements VMware et vSphere, ce problème est généralement dû au choix d'une architecture de processeur virtuel obsolète ou à l'activation de modes de compatibilité CPU qui limitent les jeux d'instructions. Pour résoudre le problème, procédez comme suit :
  • Évitez d'utiliser les profils de compatibilité CPU hérités lors de la configuration de la machine virtuelle.
  • Assurez-vous que le masquage du processeur n'est pas activé.
  • Si la fonctionnalité EVC (Enhanced vMotion Compatibility) est activée, vérifiez qu'elle est configurée à un niveau prenant en charge les instructions d' x86‑64‑v2.
  • Éteignez la machine virtuelle et mettez à jour la configuration du processeur.
  • Si nécessaire, recréez la machine virtuelle avec les paramètres CPU mis à jour.
Une fois les modifications appliquées, vérifiez que les indicateurs CPU requis sont bien visibles dans le système d'exploitation invité avant de relancer l'installation.

Contacter le support

Modifier en ligne

Si vous ne parvenez pas à résoudre le problème, contactez le service d'assistance d' IBM. Fournissez le fichier archive que vous avez créé à l'équipe de support.