Configuration de l'outil de traçage ACE ( IBM App Connect Enterprise )

La sortie utilisateur ACE Tracing de l' Instana e ne prend en charge que les types de nœuds suivants :

• demande HTTP
• IBM MQ demande
• Kafka demande

Si vous souhaitez activer la prise en charge des requêtes CICS dans l'environnement IBM Cloud Pak for Integration, effectuez les étapes suivantes :

1. Créez une image personnalisée d' docker, avec la sortie utilisateur ACE Tracing activée.
2. Déployez l'application ACE à partir de cette image docker.

• L'exit utilisateur ACE Tracing de l' Instana prend en charge les messages de type « IBM MQ » qui ne contiennent qu'un en-tête « MQRFH2 », car les informations de traçage sont écrites dans l'en-tête « MQRFH2 » du message « IBM MQ » afin de propager le contexte de traçage. Dans certains clients de consommation d' IBM MQ, la présence de données d'en-tête supplémentaires dans les messages d' IBM MQ peut entraîner des erreurs de traitement et le rejet des messages.

• Testez les clients « consumer » d' IBM MQ s dans un environnement hors production avant de l'activer dans un environnement de production.

• Si vous activez la prise en charge de la corrélation des traces et que cela provoque des erreurs dans les applications clientes d' IBM MQ, procédez de l'une des manières suivantes :

  • Si le client utilisateur d' IBM MQ s est une application modifiable, mettez-la à jour afin qu'elle ignore les données supplémentaires de l'en-tête « IBM MQ » ajoutées par Instana. Si vous avez besoin d'aide pour modifier les paramètres d'un client d' IBM MQ, veuillez contacter le service d'assistance d' IBM MQ.
  • Si le client consommateur d' IBM MQ s est une application qui ne peut pas être modifiée, n'activez pas la prise en charge de la corrélation des traces d' IBM ACE.

L'exit utilisateur ACE Tracing de l' Instana ne prend en charge que les flux de messages dont le nœud d'entrée sert de point d'entrée.

Avant d'installer et de configurer l'exit utilisateur « ACE Tracing » d' Instana, installez et configurez IBM ACE.

Pour télécharger l'extension utilisateur « IBM ACE Tracing », procédez comme suit :

1. Téléchargez le fichier « Tracing .tgz user exit » d' IBM ACE sur Artifactory. Pour télécharger le fichier, utilisez _ comme nom d'utilisateur et une clé d'agent valide comme mot de passe.

2. Extraire le fichier téléchargé .tgz dans un emplacement temporaire.

3. Après l'extraction, vous trouverez dans le répertoire cinq paquets de sortie pour différentes plates-formes.

4. Transférez le package d'exits utilisateur spécifique à une plate-forme sur votre hôte IBM ACE.

5. Extrayez le paquet user exit dans le répertoire suivant sur votre hôte ACE.

   • Linux et AIX : /var/mqsi/shared-classes
   • Windows: C:\ProgramData\IBM\MQSI\shared-classes

   Placez les fichiers suivants dans votre répertoire shared classes :

   • ACEOpenTracingUserExit.lel: Ce fichier contient l'exit utilisateur ACE « Instana », qui intercepte les requêtes « HTTP », « IBM MQ » et « Kafka », puis lance la bibliothèque cliente encapsulée « OpenTelemetry C++ » afin de créer des spans.
   • tracelibrary.so: Ce fichier définit le client encapsulé OpenTelemetry C++, qui fournit des fonctions permettant de gérer le cycle de vie des spans et d'envoyer ces derniers au système de traçage cible.
   • acetracingexit.conf : Ce fichier de configuration spécifie le niveau de journalisation et les informations relatives à la connexion à l'agent hôte.

   Si le serveur ACE n'a pas été installé via une installation globale, le répertoire /var/mqsi/shared-classesC:\ProgramData\IBM\MQSI\shared-classes ou n'existe pas sur votre serveur IBM ACE. Créez le répertoire /opt/acetracingexit ou C:\acetracingexit manuellement sur votre serveur d' IBM ACE, puis décompressez le .tar fichier dans ce répertoire.

Pour activer le traçage pour IBM ACE, procédez comme suit :

1. Arrêtez le noeud d'intégration.

   mqsistop <integrationNodeName>
    

2. Installez l'exit utilisateur sur un nœud d'intégration en définissant la UserExitPath propriété qui utilise la mqsichangeflowuserexits commande.

   mqsichangeflowuserexits <integrationNodeName> -o -x /var/mqsi/shared-classes
    

   Si vous extrayez les .tar fichiers de trace d' IBM ACE dans /opt/acetracingexit le répertoire, remplacez /var/mqsi/shared-classes par /opt/acetracingexit.

3. Activez l'exit utilisateur.

   Les exits utilisateur peuvent être actifs ou inactifs et inactifs par défaut. Vous pouvez activer l'exit utilisateur pour un nœud d'intégration, un serveur d'intégration ou un flux de messages spécifique.

   1. Activer l'exit utilisateur pour un nœud d'intégration.

      1. Activer l'exit utilisateur :

         mqsichangeflowuserexits <integrationNodeName> -o -a ACEOpenTracingUserExit
          

      2. Vérifier la sortie de l'utilisateur :

         mqsireportflowuserexits <integrationNodeName> -o
          

         Voir la sortie exemple suivante :

         # mqsireportflowuserexits BK3 -o
         BIP8854I: User Exits active for integration server 'BK3': ACEOpenTracingUserExit.
         BIP8855I: User Exits inactive for integration server 'BK3': .
         BIP8741I: User Exit path for integration server 'BK3': /var/mqsi/shared-classes.
         BIP8071I: Successful command completion.
          

      3. Démarrer le nœud d'intégration :

         mqsistart <integrationNodeName>
          

   2. Activez l'exit utilisateur pour un serveur d'intégration.

      1. Démarrer le nœud d'intégration :

         mqsistart <integrationNodeName>
          

      2. Activer l'exit utilisateur :

         mqsichangeflowuserexits <integrationNodeName> -e <integrationServerName> -a ACEOpenTracingUserExit
          

   3. Activez l'exit utilisateur pour un flux de messages.

      1. Démarrer le nœud d'intégration :

         mqsistart <integrationNodeName>
          

      2. Activer l'exit utilisateur pour un flux de messages :

         mqsichangeflowuserexits <integrationNodeName> -e <integrationServerName> -k <applicationName> -f <messageFlow> -a ACEOpenTracingUserExit
          

   4. Répétez les étapes pour les autres nœuds d'intégration, serveurs d'intégration ou flux de messages pour lesquels vous souhaitez activer l'exit utilisateur.

Pour plus d'informations, voir les liens suivants :

• IBM ACE : Déploiement d'une sortie utilisateur
• IBM ACE : commande mqsichangeflowuserexits - Systèmes Windows, Linux et AIX

1. Accédez au répertoire /var/mqsi/shared-classes.

2. Éditez le fichier acetracingexit.conf :

   # configuration for ace tracing exit
   LOG_LEVEL="info" #Log level: info, warn, error, debug
   SPAN_FORMAT="instana"
   CICS_SUPPORT="off" #Propagate trace context for CICS request: off, on
   MONITOR_LEVEL="verbose" #ACE tracing level: off, normal, verbose
   INSTANA_AGENT_HOST="localhost" #(optional)
   INSTANA_AGENT_PROTO="http" #(optional)
   HOST_ALIAS="<YOUR-HOST-NAME>" #(optional)
   
    

   où :

   • LOG_LEVEL Spécifie le niveau de journalisation, qui peut être l'un des types suivants : info, warn, error, ou debug. Le fichier journal se trouve dans le /tmp/trace répertoire.
   • SPAN_FORMAT indique l'emplacement auquel les données sont envoyées. Affectez instana à cette variable. Instana Par défaut, l'exit utilisateur ACE Tracing envoie http://localhost:42699 les données de span au point de terminaison de l'agent hôte. Modifiez les champs de configuration INSTANA_AGENT_HOST et INSTANA_AGENT_PROTO si vous souhaitez envoyer les données de span à un agent distant utilisant le protocole HTTPS. Vous devez utiliser le même SPAN_FORMAT paramètre pour toutes les instances d' IBM ACE.
   • CICS_SUPPORT Ce paramètre permet de déterminer si la prise en charge du suivi des requêtes d' CICS s est activée. Réglez-le sur on pour activer la prise en charge et off sur pour la désactiver.
   • MONITOR_LEVEL Définit le niveau de traçabilité d' IBM ACE; il peut s'agir de l'un des types suivants : off, normal, ou verbose. Si MONITOR_LEVEL est défini sur off, aucun contexte de traçage n'est ajouté à la requête sortante. Si MONITOR_LEVEL est défini sur normal, le contexte de traçage n'est ajouté qu'à condition que le message IBM MQ comporte l'en-tête RFH2. Si MONITOR_LEVEL est défini sur verbose, le contexte de traçage est ajouté à toutes les requêtes sortantes de type HTTP ou IBM MQ.
   • INSTANA_AGENT_HOST Indique l'hôte de l'agent vers lequel sont envoyées les données de span au format Instana. Par défaut, localhost est utilisé. Si vous indiquez un hôte d'agent distant, vous devez d'abord ajouter une ligne http.listen=* dans *instanaAgentDir*/etc/instana/com.instana.agent.main.config.Agent.cfg pour l'agent de l'hôte distant, car par défaut, l'agent de l'hôte n'est pas accessible depuis les autres hôtes.
   • INSTANA_AGENT_PROTO Spécifie le type de connexion entre l'exit utilisateur de traçage d' IBM ACE et l'agent hôte. Par défaut, http est utilisé. Cependant, https est également pris en charge. Si vous souhaitez le modifier, vous devez httpsd'abord suivre ces Configurer TLS le chiffrement pour le terminal de l'agent étapes pour sécuriser le point de Instana terminaison de l'agent.
   • HOST_ALIAS Spécifie un alias d'hôte pour les données de span collectées par l'exit utilisateur ACE Tracing d' Instana. Ainsi, les appels vers IBM ACE peuvent être associés à l'entité d'infrastructure si le nœud d'intégration ou le serveur d'intégration est également surveillé par le capteur IBM ACE. Le nom de domaine complet (FQDN) de l'hôte IBM ACE est utilisé par défaut. La valeur de l'alias de l'hôte doit correspondre à l'hôte du capteur IBM ACE spécifié dans le fichier YAML de configuration de l'agent hôte. Vous ne devez spécifier un alias d'hôte que si le nom de domaine complet (FQDN) de l'hôte IBM ACE n'est pas utilisé dans la configuration du capteur ACE Instana et si l'agent hôte ne se trouve pas sur l'hôte local IBM ACE. Le capteur « IBM ACE » permet de déterminer le nom de domaine complet (FQDN) des nœuds d'intégration locaux ou des serveurs d'intégration.

3. Enregistrez le fichier et redémarrez le noeud d'intégration ou le serveur d'intégration.

Répétez ces étapes d'installation et de configuration sur d'autres hôtes IBM ACE pour lesquels vous souhaitez activer la fonction de trace.

Vous pouvez consulter les données de traçage ACE d' Instana dans l'interface utilisateur d' Instana.

1. Annuler la configuration de l'exit utilisateur.

   1. Déconfigurer l'exit utilisateur pour un nœud d'intégration :

      1. Arrêter le nœud d'intégration :

         mqsistop <integrationNodeName>
          

      2. Désactive l'exit utilisateur :

         mqsichangeflowuserexits <integrationNodeName> -o -a ""
          

      3. Redémarrez les noeuds d'intégration.

   2. Désactiver l'exit utilisateur pour un serveur d'intégration :

      mqsichangeflowuserexits <integrationNodeName> -e <integrationServerName> -a ""
       

   3. Désactive la sortie utilisateur pour un flux de messages :

      mqsichangeflowuserexits <integrationNodeName> -e <integrationServerName> -k <applicationName> -f <messageFlow> -a ""
       

2. Répétez les étapes sur d'autres noeuds d'intégration.

Pour activer le suivi d' OpenTelemetry pour IBM ACE, procédez comme suit :

1. Configurer l'importation des données d' OpenTelemetry pour Instana. Pour plus d'informations, consultez la section « Configuration de l'importation de données dans OpenTelemetry ».

2. Activer le traçage de l' OpenTelemetry ACE. Pour plus d'informations, consultez la section « Configuration de la trace d' OpenTelemetry s pour un serveur d'intégration ».

3. Configurez le nom d'hôte correct afin de permettre une corrélation adéquate de l'infrastructure entre les entités.

Pour plus d'informations sur les points à prendre en compte et les limitations, consultez la page OpenTelemetry.

La méthode de traçage des exits utilisateur ACE ne prend en charge que les configurations à nœud unique. Les configurations à haute disponibilité (HA) et les environnements en cluster ne sont pas pris en charge. Pour les déploiements HA ou les environnements en cluster, utilisez la prise en charge native du traçage d' OpenTelemetry s plutôt que la méthode des exits utilisateur.