Guide de migration de l'agent Ruby 6.x vers 7.x

Résumé

Ce guide couvre les principaux changements entre les séries 6.x et 7.x de l'agent Ruby, les problèmes qui peuvent être rencontrés lors de la mise à niveau et comment migrer avec succès vers la version 7.x.

Les principaux changements incluent :

• Le support de Ruby 2.0 et 2.1 est abandonné
• Le bundle de certificats SSL est supprimé
• Plusieurs API qui étaient obsolètes dans diverses versions 6.x sont désormais supprimées
• l'auto-instrumentation est par défaut préfixée sur la méthode chaîne
• l'auto-instrumentation obtient un attribut configuration cohérent

Consultez le jalon de la sortie cible 7.0 pour plus d'informations.

Le support de Ruby 2.0 et 2.1 est abandonné

Ruby 2.0 et 2.1 ont atteint leur fin de vie en février 2016, et New Relic suit le mouvement en abandonnant le support de ces versions dans la sortie 7.0. Il n’existe aucun changement connu qui empêcherait intrinsèquement ces versions de continuer à fonctionner, mais nous ne garantissons plus que l’agent Ruby continue de fonctionner sans problèmes à l’avenir. Si vous avez besoin Ruby 2.0 ou 2.1, continuez à utiliser la version 6.15.0, qui est la dernière version publiée pour prendre en charge ces versions Ruby .

Préfixer la configuration de l'instrumentation

Demande de tirage pertinente : Préfixer instrumentation #565.

Potential issue: L'agent ne parvient pas à s'initialiser et à démarrer la génération de rapports de données. Un message d'erreur de niveau stack trop profond est signalé dans le log.

Solution: Notre mécanisme de détection de configuration et de dépendance peut désormais être contrôlé via la configuration. Par défaut, toutes les gems/bibliothèque auto-instrumentées sont activées avec la stratégie prepend. Le paramètre configuration par défaut pour ces bibliothèques en l'absence de paramètres apparaissant dans le fichier configuration est auto, ce qui choisira la meilleure stratégie. Dans le cas d'un conflit connu avec des stratégies de préfixation, auto demande à l'agent de revenir à la chaîne de méthodes lorsque de tels conflits sont détectés. Vous trouverez ci-dessous une explication complète de nos modifications apportées à la section de configuration pour l'auto-instrumentation en utilisant sidekiq comme exemple.

instrumentation:
  sidekiq: chain

Pour désactiver complètement l’instrumentation :

instrumentation:
  sidekiq: disable

Dans certains cas, nous pouvons savoir que des gems spécifiques entrent en conflit avec prepend. Pour faciliter, nous proposons par défaut une option de configuration automatique, qui se dégrade automatiquement en chaîne dans de tels cas.

Le paramètre par défaut dans la plupart des cas est donc :

instrumentation:
  sidekiq: auto

Il est possible de forcer l'utilisation de la stratégie prepend en la spécifiant dans le fichier de configuration :

instrumentation:
  sidekiq: prepend

Si vous rencontrez des erreurs au niveau de la pile trop profondes, consultez notre guide de dépannage pour savoir comment résoudre ces problèmes. Après avoir parcouru ce guide de dépannage, vous pouvez nous informer du conflit de préfixe que vous trouvez en commentant ce problème GitHub. Nous apprécions vos commentaires afin que nous puissions détecter et recourir automatiquement à la méthode-chaîne dans de tels scénarios.

Stratégie d'auto-instrumentation modernisée

Ruby a introduit prepend comme un moyen d'insérer des définitions de méthode plus tôt dans la stack de résolution de méthode dans Ruby 2.0 (sortie en 2013) avec l'intention que prepend élimine le besoin de faire une chaîne de méthodes comme moyen de corriger les implémentations originales de la bibliothèque de gems avec la logique trace/observabilité.

Mélanger le préfixe avec la méthode-chaîne (aka method_alias monkey patching) peut conduire à un scénario connu de niveau stack trop profond comme décrit dans notre article de blog sur le sujet.

New Relic a déjà mis à jour de nombreuses bibliothèques auto-instrumentées au fil des ans pour utiliser la stratégie de préfixe. La sortie 7.0 fait de l'ajout d'un préfixe à la stratégie par défaut choisie pour auto-instrumenter plutôt que la méthode-chaîne, sauf lorsque des scénarios connus existent qui conduiraient à déclencher des erreurs trop profondes au niveau de stack . Nous avons fait de notre mieux pour identifier les joyaux externes conflictuels qui pourraient conduire à ce scénario, mais il y en a forcément d’autres dans la nature que nous n’avons pas identifiés.

Dans le passé, nous n'avions qu'une seule façon d'auto-instrumenter la plupart des gems : la méthode-chaîne. Avec la sortie de la version 7.0, nous pouvons instrumenter la plupart des gems en utilisant soit la méthode-chaîne, soit le préfixe et notre configuration de toutes les gems auto-instrumentées a été mise à jour pour refléter cela.

Avec la modernisation de notre auto-instrumentation, nous avons également introduit de nouvelles fonctionnalités dans notre mécanisme de détection de dépendance pour identifier les gems externes en conflit et passer automatiquement de la stratégie de préfixe à la chaîne de méthodes. Cela signifie que vous n'avez plus besoin de dépendre des mainteneurs d'autres gems pour apporter des modifications à leur bibliothèque de gems afin de faciliter l'utilisation de l'agent Ruby en conjonction avec ces gems. Cependant, nous ne sommes pas conscients de tels conflits jusqu'à ce que notre utilisateur nous les signale, donc seules quelques-unes de nos bibliothèques auto-instrumentées peuvent détecter automatiquement ces conflits et basculer automatiquement vers des stratégies de chaîne de méthodes. Nous avons besoin de votre aide pour entendre parler de ces scénarios et pour ajouter la détection automatique aux futures sorties de l'agent Ruby .

Le bundle de certificats SSL est supprimé

Aux premiers jours de Ruby (1.8, 1.9, etc.), l'intégration avec OpenSSL et l'établissement de connexions HTTPS n'étaient pas bien gérés. Pour garantir que les clients puissent établir systématiquement des connexions HTTPS aux serveurs Collector de New Relic, une sélection de certificats SSL CA a été regroupée et distribuée avec l'agent Ruby. Au fil du temps, l'écosystème Ruby s'est stabilisé et prend désormais en charge les certificats d'autorité de certification installés par le système de manière standard, ce qui rend largement obsolète la nécessité de regrouper et de distribuer le bundle de certificats. La grande majorité des certificats regroupés ont expiré ou sont sur le point d’expirer, nous avons donc décidé de supprimer cette dépendance de l’agent. Si vous déployez une application et un agent Ruby vers un conteneur ou un serveur sur lequel aucun certificat CA n'est installé, vous devrez vous assurer qu'ils sont désormais installés pour la sortie 7.0+ de l'agent pour établir des connexions HTTPS réussies aux serveurs New Relic.

Pour plus d'informations, voir Supprimer le bundle de certificats #478.

Potential issue: Si vous vous rendez sur un hôte qui n'a pas de certificats OpenSSL et système CA installés, vous risquez de rencontrer des problèmes de connexion aux serveurs New Relic et de subir une perte de données APM.

Solution: Les serveurs New Relic nécessitent HTTPS, qui utilise des certificats CA pour initier des connexions réussies. Ceux-ci peuvent être installés, et selon votre hôte, de différentes manières. Voici des liens utiles pour tester l’état de préparation de votre hôte et installer des certificats CA :

• Erreurs SSL du certificat de dépannage
• Vérification SSL automatisée
• Installation des certificats CA
• Comment gérer les certificats dans Docker

Si nécessaire, l'agent peut être configuré pour utiliser n'importe quel bundle CA en indiquant le chemin d'accès au fichier bundle CA via la configuration : :ca_bundle_path. Veuillez consulter le certificat SSL personnalisé pour Ruby pour plus d'informations.

API obsolètes et attributs de configuration

Toutes les API obsolètes disposent d’API de remplacement qui étendent la portée et/ou améliorent la robustesse de l’API obsolète.

Les demandes de tirage pertinentes sont :

• Supprimer les références à whitelist et blacklist dans la base de code #479
• Supprimer les options de configuration obsolètes ActiveRecord #480
• Supprimer l'attribut httpResponseCode #481
• Supprimer l'option obsolète de l'API notice_error #597
• Supprimer traceobsolètes distribuées par les méthodes API #598

Listes refusées et autorisées activées

Potential issue: Les attributs de la liste noire/blanche ne fonctionnent plus.

Solution : Remplacez black par denied et white par allowed dans vos paramètres de configuration ou de variable d’environnement.

https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/#autostart-denylized_constants

• :autostart.blacklisted_constants => :autostart.denylisted_constants
• :autostart.blacklisted_executables => :autostart.denylisted_executables
• :autostart.blacklisted_rake_tasks => :autostart.denylisted_rake_tasks
• :strip_exception_messages.whitelist => :strip_exception_messages.allowed_classes

Enregistrement actif

Potential issue: La désactivation des anciennes versions d'Active Record ne fonctionne plus.

Solution: Modifiez les paramètres de configuration suivants :

• :disable_active_record_4 => :disable_active_record_notifications
• :disable_active_record_5 => :disable_active_record_notifications

httpResponseCode

Potential issue: L'attribut httpResponseCode n'apparaît plus dans UI dans la trace signalée.

Solution: httpResponseCode a été remplacé par http.statusCode.

Avis d'erreur (trace_only)

Potential issue: Passer l'option :trace_only à NewRelic::Agent.notice_error ne fonctionne plus.

Solution: Remplacez :trace_only par l'attribut :expected .

API de tracing distribué

Potential issue: Des erreurs sont générées dans le code de l'application lors de l'appel des méthodes API create_distributed_trace_payload et accept_distributed_trace_payload.

Solution: Veuillez plutôt consulter respectivement insert_distributed_trace_headers et accept_distributed_trace_headers.