Dépannage du suivi d'.NET s sur z/OS

Modifier en ligne

Si le traçage ne fonctionne pas comme prévu, commencez par suivre les étapes générales de dépannage avant de passer à des cas particuliers.

identification et résolution des problèmes généraux

Modifier en ligne

Procédez comme suit :

  1. Vérifier les conditions préalables :

    • Vérifiez la compatibilité de la version d'.NET : assurez-vous que votre application fonctionne sur .NET Core Runtime 5.0 ou une version ultérieure.
    • Vérifiez que l'agent d' Instana s est en cours d'exécution sur le système z/OS.
    • Vérifiez l'état de l'agent dans l'interface utilisateur d' Instana.

  2. Vérifiez les variables d'environnement : si le traçage ne fonctionne pas, vérifiez que les variables d'environnement sont bien les suivantes :

    • Réglé correctement.
    • Écrit correctement.
    • Configuré pour l'environnement de l' z/OS.
    • Valide, accessible par le processus ou l'application, et correct.

  3. Vérifiez que le point de terminaison de l'agent d' Instana s est accessible depuis l'environnement z/OS :

    • Utilisez telnet agent_host agent_port (par exemple, telnet localhost 42699) pour tester la connexion.

  4. Vérifier l'intégration du SDK :

    • Pour le SDK d' Instana :

      • Assurez-vous que le Instana.Tracing.Core.Sdk paquet est correctement installé.
      • Assurez-vous que des intervalles personnalisés sont créés dans votre code à l'aide de CustomSpan.Create().

    • Pour le SDK d' OpenTelemetry :

      • Assurez-vous que tous les paquets requis pour l' OpenTelemetry ation sont installés (OpenTelemetry.Extensions.Hosting, OpenTelemetry.Exporter.OpenTelemetryProtocol).
      • Vérifiez que AddOpenTelemetry() est bien appelé dans la configuration de votre service.
      • Assurez-vous que l'exportateur OTLP est correctement configuré pour pointer vers l'agent Instana (par défaut : http://localhost:4317 pour gRPC ou http://localhost:4318 pour HTTP ).
      • Vérifiez que les plug-ins d' OpenTelemetry s sont activés dans le fichier de l'agent configuration.yaml .
      • Assurez-vous que les portées personnalisées sont bien créées à l'aide de ActivitySource.
    Important : n'utilisez pas les deux SDK simultanément dans la même application, car cela pourrait entraîner la duplication des segments, une augmentation de la charge système et d'éventuels conflits lors de la propagation du contexte de trace.

Dépannage spécifique à chaque cas

Modifier en ligne

Si les étapes de dépannage générales ne permettent pas de résoudre votre problème, consultez les scénarios de dépannage suivants :

Scénario 1 : Traces ou portées manquantes

Modifier en ligne

Symptôme : aucune trace n'est générée, ou certains services génèrent des traces, mais pas d'autres.

Procédure de résolution des incidents :

  1. Vérifiez que la version de l'application disponible sur .NET est prise en charge :

    • .NET Core Environnement d'exécution : 5.0 ou version ultérieure
  2. Vérifiez que l'instrumentation manuelle est correctement mise en œuvre à l'aide du SDK Instana ou du SDK OpenTelemetry.

  3. Vérifiez si les paquets SDK sont correctement installés :

    • Pour le SDK d' Instana : Instana.Tracing.Core.Sdk
    • Pour le SDK d' OpenTelemetry : OpenTelemetry.Extensions.Hosting, OpenTelemetry.Exporter.OpenTelemetryProtocol
  4. Vérifiez que des segments personnalisés sont bien créés dans le code de l'application.
  5. Vérifiez les journaux de l'agent d' Instana s pour détecter d'éventuels problèmes de connexion.
  6. Si vous utilisez le SDK d' OpenTelemetry, vérifiez que le point de terminaison de l'exportateur OTLP est correctement configuré (par défaut : http://localhost:4317 gRPC ).
  7. configuration.yamlVérifiez si les plug-ins d' OpenTelemetry (com.instana.plugin.opentelemetry) sont activés dans l'agent d' Instana.
  8. Recueillir les journaux de suivi d' Instana.

  9. Consultez les journaux de traçage d' Instana :

    • Si les journaux sont vides ou ne contiennent aucune trace, cela signifie que les segments ne sont pas créés correctement dans le code de l'application.
    • Si des traces apparaissent dans les journaux et qu'elles contiennent des informations qui ne figuraient pas dans l'interface utilisateur, le problème s'est produit soit au niveau du backend, soit au niveau de l'agent.

Scénario 2 : L'application ne démarre pas

Modifier en ligne

Symptôme : l'application plante au démarrage lorsque le SDK « Instana » ou le SDK « OpenTelemetry » est intégré.

Procédure de résolution des incidents :

  1. Vérifiez que la version de l'application disponible sur .NET est prise en charge :

    • .NET Core Environnement d'exécution : 5.0 ou version ultérieure
  2. Vérifiez que les paquets SDK sont compatibles avec la version d'exécution d'.NET.
  3. Vérifiez les journaux d'application pour voir s'il y a des erreurs d'initialisation du SDK.
  4. Vérifiez que le point de terminaison de l'agent d' Instana est accessible depuis l'environnement z/OS en utilisant telnet agent_host agent_port (par exemple, telnet localhost 42699).
  5. Si possible, récupérez un fichier de vidage de mémoire pour l'application en question.

Scénario 3 : L'agent ne détecte pas l'application d'.NET

Modifier en ligne

Symptôme : l'application « .NET » n'est pas surveillée par l'agent « Instana » et n'apparaît pas dans l'interface utilisateur.

Procédure de résolution des incidents :

  1. Vérifiez que l'agent d' Instana ation est en cours d'exécution sur z/OS.
  2. Vérifiez que l'agent d' Instana s dispose des autorisations nécessaires pour accéder à l'application.

  3. Assurez-vous que le suivi d'.NET Core s est activé dans le fichier de configuration de l'agent (*instanaAgentDir*/etc/instana/configuration.yaml):

    com.instana.plugin.netcore:
  tracing:
    enabled: true
    Remarque : vous devez redémarrer l'agent d' Instana ation après avoir modifié le fichier de configuration.

  4. Si vous utilisez le SDK d' OpenTelemetry, vérifiez que les plug-ins d' OpenTelemetry s sont activés :

    com.instana.plugin.opentelemetry:
  grpc:
    enabled: true
  http:
    enabled: true
    Remarque : vous devez redémarrer l'agent d' Instana ation après avoir modifié le fichier de configuration.
  5. Vérifiez que l'application crée bien des segments à l'aide du SDK.
  6. Vérifiez si le nom du service est correctement configuré lors de l'initialisation du SDK.

Scénario 4 : Utilisation élevée du processeur ou de la mémoire après l'activation du traçage basé sur le SDK

Modifier en ligne

Symptôme : l'application affiche une utilisation anormalement élevée du processeur ou de la mémoire après l'activation du traçage basé sur le SDK.

Procédure de résolution des incidents :

  1. Identifier la source :

    • Vérifiez si le problème est lié à l'application en consultant les outils de surveillance du système d' z/OS.

  2. En cas de pic de mémoire ou de charge CPU au niveau d'une application :

    • Vérifiez les journaux d'application pour détecter d'éventuelles exceptions liées à la mémoire ou des problèmes de performances.
    • Vérifiez si le problème est dû à la création d'un nombre excessif de spans dans le code de l'application.
    • Vérifiez que les intervalles sont correctement fermés ou libérés à l'aide using d'instructions ou d'une libération explicite.
    • Vérifiez la fréquence et le volume des portées personnalisées créées.
    • Demandez les journaux d'application et les vidages de mémoire afin de procéder à une analyse plus approfondie.

Scénario 5 : Problèmes de configuration du SDK

Modifier en ligne

Problème : les traces n'apparaissent pas dans l'interface utilisateur d' Instana, bien que le SDK soit intégré.

Procédure de résolution des incidents :

  1. Vérifiez que le SDK est correctement initialisé dans le code de démarrage de l'application.

    • Pour le SDK d' Instana :

      • Vérifiez que les portées sont créées avec les paramètres appropriés SpanType (ENTRY, INTERMEDIATE, et EXIT).
      • Assurez-vous que les intervalles sont correctement définis à l'aide using d'instructions.

    • Pour le SDK d' OpenTelemetry :

      • Vérifiez que AddOpenTelemetry() est bien appelé dans la configuration du service.
      • Vérifiez si le point de terminaison de l'exportateur OTLP est correctement configuré (par défaut : http://localhost:4317).
      • Vérifiez que ActivitySource est correctement enregistré et utilisé.
      • Assurez-vous que le nom du service est bien configuré dans le générateur de ressources.

  2. Vérifiez la connexion réseau entre l'application et l'agent d' Instana :

    • Testez la connectivité à l'aide de telnet agent_host agent_port (par exemple, telnet localhost 42699 pour le SDK d' Instana ou telnet localhost 4317 pour le SDK d' OpenTelemetry avec gRPC ).
    • Vérifiez les journaux de l'agent d' Instana pour détecter d'éventuelles tentatives de connexion ou erreurs.
    • Vérifier la configuration réseau et les politiques de sécurité d' z/OS.

  3. Vérifiez si les règles du pare-feu autorisent la communication sur les ports requis :

    • 42699 : Port par défaut de l'agent d' Instana (pour le SDK d' Instana )
    • 4317 : Point de terminaison gRPC OTLP (pour le SDK d' OpenTelemetry )
    • 4318 : HTTP Point de terminaison OTLP (pour le SDK OpenTelemetry, si vous utilisez HTTP au lieu de gRPC )

Collecte des journaux

Modifier en ligne

z/OS ne prend pas en charge la collecte automatique des journaux. Vous devez donc collecter les journaux manuellement.

Pour récupérer les journaux manuellement, procédez comme suit :

  1. Activez les journaux de débogage :

    Définissez manuellement les variables d'environnement suivantes au niveau du système et assurez-vous que les chemins d'accès sont valides, accessibles par le processus ou l'application, et corrects :

    INSTANA_NET_LOG_PATH=log_path
INSTANA_NET_LOG_LEVEL=DEBUG
  2. Redémarrez l'application.

  3. Pour collecter les journaux de l'agent d' Instana, procédez comme suit :

    1. Arrêtez l'agent :

      instana_install_dir/bin/stop.sh

    2. Supprimer les journaux : effacez tous les fichiers du répertoire « logs » pour repartir de zéro :

      rm -rf instana_install_dir/data/logs/*
    3. Définissez le niveau de journalisation sur « Debug » : modifiez le niveau de gravité de la journalisation dans le fichier de configuration. Pour plus d'informations, consultez la section « Configuration du fichier de configuration de l'agent ».

    4. Démarrez l'agent :

      instana_install_dir/bin/start.sh
    5. Reproduire le problème : laissez le problème se produire et laissez l'agent fonctionner pendant environ 15 minutes.

    6. Récupérez les fichiers journaux : compressez le répertoire des fichiers journaux avant de les envoyer :

      cd instana_install_dir/data/logs/
zip -r instana_agent_debug_logs.zip *

  4. Pour collecter les journaux de trace d' Instana, procédez comme suit :

    1. Accédez à agent_dir/etc/instana/com.instana.agent.main.sender.File.cfg.

    2. Ajoutez les lignes suivantes dans le fichier :

      prefix=instanaTraces
type=traces

      instanaTracesCette configuration génère un fichier journal contenant toutes les traces dans agent_dir/data/log avec le préfixe.

    3. Redémarrez l'agent d' Instana.
    4. Redémarrez l'application.
    5. Laissez-le fonctionner pendant environ 15 minutes.

    6. Vérifiez que les traces sont bien enregistrées :

      • Accédez à l'interface utilisateur d' Instana en allant dans Applications > Services, puis recherchez le nom de votre service.
      • Vérifiez que les traces et les segments apparaissent avec les noms de service et de point de terminaison attendus.

    7. Récupérez les fichiers journaux aux emplacements suivants :

      • Chemin indiqué par la variable INSTANA_NET_LOG_PATH
      • instana-agent-installation-folder/data/log

Ouverture d'un ticket de demande de service

Modifier en ligne

Si le problème persiste après avoir suivi ces étapes de dépannage, veuillez recueillir les données d' MustGather s avant d'ouvrir un ticket d'assistance. MustGather Ces données permettent au service d'assistance d' IBM de diagnostiquer votre problème plus efficacement.

Pour plus d'informations, consultez les sites suivants : MustGather:, Instana, .NET et Tracer - z/OS.