Notre agent .NET est un profileur .NET CLR et s'appuie sur les variables d'environnement de votre application pour connecter votre application .NET à New Relic. Pour en savoir plus sur les variables d’environnement utilisées par l’agent .NET, consultez les sections ci-dessous.
Aperçu des conditions
Voici quelques conseils pour comprendre les termes utilisés sur cette page :
- « .NET Core» fait référence aux versions .NET (et aux applications créées avec et pour les versions .NET) 5.0 et supérieures (uniquement « .NET ») ainsi qu'à .NET Core 2.0 à 3.1.
- « profileur » fait référence au composant de l'agent qui implémente l'API de profilage .NET. Lorsque les éléments sont configurés correctement, le CLR attache le profileur à votre application .NET. Le profileur charge ensuite le reste de l'agent dans l'application.
Comment les variables d'environnement sont utilisées par l'agent .NET
Notre agent .NET est un profileur .NET CLR et implémente un sous-ensemble de l'API de profilage .NET. Certaines variables d’environnement doivent être présentes dans l’environnement d’un processus .NET pour indiquer au runtime .NET que le processus doit être profilé et par quel profileur. Des variables d'environnement supplémentaires sont utilisées par l'agent .NET lui-même pour lui permettre de savoir où et comment il est installé.
Pour utiliser l'agent .NET, nous avons besoin de variables d'environnement pour :
- Activation du profilage et identification du profileur approprié
- Indiquer au profileur où se trouve le reste de l'agent
Variables permettant de réaliser le profilage et d'identifier le bon profileur
Il existe un ensemble de trois variables d'environnement utilisées pour indiquer à l'environnement d'exécution .NET s'il faut ou non activer le profilage et quel profileur utiliser : COR_ENABLE_PROFILING, COR_PROFILER et COR_PROFILER_PATH. Les noms de ces variables et la valeur correcte pour chacune d'elles dépendent du fait que votre application est conçue pour .NET Framework ou .NET Core.
Pour les applications .NET Framework :
COR_ENABLE_PROFILING indique au moteur d'exécution s'il faut ou non activer le profilage pour une application. Réglez sur 1 pour activer le profilage, réglez sur 0 pour le désactiver.
COR_PROFILER indique au runtime quel profileur utiliser. La valeur est un GUID unique à un profileur donné. Pour le profileur du .NET Framework de New Relic, la valeur correcte est {71DA0A04-7777-4EC6-9643-7D28B46A8A41}.
COR_PROFILER_PATH indique au runtime où trouver le profileur sur le système, et dépend du type d'installation et de la plateforme. Notez que cela peut ne pas être nécessaire si l'agent a été installé avec le programme d'installation MSI, qui enregistre la DLL du profileur auprès du système en fonction du GUID défini dans COR_PROFILER. Cependant, il est prudent de le définir de toute façon tant que la valeur est définie sur le chemin correct.
Valeurs typiques :
COR_ENABLE_PROFILING=1COR_PROFILER={71DA0A04-7777-4EC6-9643-7D28B46A8A41}COR_PROFILER_PATH="C:\Program Files\New Relic\.NET Agent\netframework\NewRelic.Profiler.dll"Pour l'application .NET Core :
CORECLR_ENABLE_PROFILING indique au moteur d'exécution s'il faut ou non activer le profilage pour une application. Réglez sur 1 pour activer le profilage, réglez sur 0 pour le désactiver.
CORECLR_PROFILER indique au runtime quel profileur utiliser. La valeur est un GUID unique à un profileur donné. Pour le profileur pour .NET Core de New Relic, la valeur correcte est {36032161-FFC0-4B61-B559-F6C5D41BAE5A}.
CORECLR_PROFILER_PATH indique au moteur d'exécution où trouver le profileur sur le système.
Valeurs typiques :
CORECLR_ENABLE_PROFILING=1CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}CORECLR_PROFILER_PATH="C:\Program Files\New Relic\.NET Agent\netcore\NewRelic.Profiler.dll"Remarque : le comportement du profileur agent .NET diffère légèrement entre .NET Framework et .NET Core. Pour .NET Framework, même lorsque le profilage est activé dans l'environnement d'un processus .NET Framework, il ne sera instrumenté par l'agent que si l'une des conditions suivantes est remplie :
- L'application est hébergée dans IIS (a) les pools application sont configurés pour être instrumentés par défaut, ou (b) le pool application hébergeant l'application est configuré pour être instrumenté explicitement.
- L'application est explicitement configurée pour être instrumentée dans le fichier
newrelic.configà l'échelle du système AgentEnabled="true"est défini dans un fichiernewrelic.configlocal à l'application
Cependant, pour l'agent .NET, tout processus où CORECLR_ENABLE_PROFILING est défini sur 1 dans son environnement sera instrumenté par l'agent. Par conséquent, nous ne recommandons pas de définir cette variable d'environnement sur 1 à l'échelle du système, car cela peut entraîner une consommation excessive de ressources système et/ou l'envoi de plus de données à New Relic que prévu. Au lieu de cela, définissez uniquement cette variable sur 1 dans l'environnement des processus que vous souhaitez instrumenter.
Variables pour indiquer au profileur où se trouve le reste de l'agent .NET
Maintenant que l'environnement d'exécution .NET sait comment trouver le profileur et l'attacher à votre application, d'autres variables d'environnement sont nécessaires pour trouver le reste des ressources de l'agent, qui incluent à la fois des composants binaires (DLL) et de configuration (XML). Ces variables sont également utilisées par certaines parties du reste de l'agent.
Remarque : selon votre scénario d’installation, seules certaines de ces variables sont requises.
NEWRELIC_HOME
Cette variable :
- est uniquement utilisé dans la version .NET framework de l'agent
- est utilisé pour rechercher les ressources de configuration de l'agent (
newrelic.configet les fichiers XML d'instrumentation dans le sous-dossierextensions) - peut être utilisé pour trouver les actifs binaires de l'agent, s'ils sont installés au même endroit que les actifs de configuration
Remarque : lorsque l'agent est installé avec le programme d'installation MSI, il n'est peut-être pas nécessaire de définir cette variable, car le MSI définit également une clé de registre (HKEY_LOCAL_MACHINE\Software\New Relic\.NET Agent\NewRelicHome) avec la valeur correcte. La variable d'environnement a la priorité si elle est définie.
CORECLR_NEWRELIC_HOME
Cette variable est :
- Utilisé uniquement dans la version .NET Core de l'agent
- Utilisé pour rechercher les ressources de configuration de l'agent (
newrelic.configet les fichiers XML d'instrumentation dans le sous-dossierextensions) - Peut être utilisé pour rechercher les ressources binaires de l'agent, s'ils sont installés au même endroit que les ressources de configuration
Remarque : cette variable doit toujours être définie pour la version .NET Core de l’agent.
NEWRELIC_INSTALL_PATH
Cette variable est principalement utilisée :
- Lorsque les versions .NET et .NET Core de l'agent sont installées côte à côte sur le système
- Lorsque les composants binaires de l'agent sont installés dans un emplacement différent sur le système que les ressources de configuration
- Lorsque l'agent est installé avec le programme d'installation MSI sous Windows (qui effectue les deux opérations ci-dessus)
Cette variable est définie sur un répertoire/dossier et est utilisée par le profileur pour trouver l'agent Core.dll. Si le chemin spécifié dans cette variable contient le fichier NewRelic.Agent.Core.dll , il est utilisé. Si le Core.dll n'est pas trouvé, le profileur ajoute netframework ou netcore au chemin spécifié et recherche le Core.dll à cet emplacement. Si le Core.dll n'est toujours pas trouvé, le profileur revient à la recherche dans NEWRELIC_HOME (.NET framework) ou CORECLR_NEWRELIC_HOME (.NET Core).
Cette variable est également utilisée par l'agent pour charger les binaires d'extension d'instrumentation à partir du sous-dossier extensions . L'agent ajoute toujours netframework ou netcore à la valeur de cette variable lorsqu'elle est définie. Si ce n'est pas défini, l'agent revient à la recherche dans NEWRELIC_HOME\extensions (.NET framework) ou CORECLR_NEWRELIC_HOME\extensions (.NET Core).
Valeurs pour des scénarios d'installation typiques
Programme d'installation MSI (Windows)
Le MSI est facile à utiliser car il fait presque tout pour vous automatiquement, mais ce qu'il fait en coulisses est compliqué. Le programme d'installation MSI place différentes parties de l'agent à différents endroits du système. Par défaut, il place les ressources de l'agent binaire dans C:\Program Files\New Relic\.NET Agent et il place les ressources de configuration dans C:\ProgramData\New Relic\.NET Agent. Ceci permet de prendre en charge les scénarios dans lesquels un utilisateur non privilégié peut accéder/modifier des fichiers dans ProgramData mais pas dans Program Files. Le programme d'installation MSI installe côte à côte les versions framework et Core de l'agent . Le programme d'installation MSI définit également un certain nombre de clés de registre qui rendent inutile la définition explicite de certaines des variables d'environnement requises, comme expliqué ci-dessus.
En supposant que vous ne spécifiez pas de chemin installation personnalisé lorsque vous utilisez le programme d'installation MSI, voici les valeurs correctes des variables d'environnement :
Pour les applications .NET Framework :
COR_ENABLE_PROFILING=1COR_PROFILER={71DA0A04-7777-4EC6-9643-7D28B46A8A41}COR_PROFILER_PATH="C:\Program Files\New Relic\.NET Agent\netframework\NewRelic.Profiler.dll" # may not be necessary due to profiler being registered with the systemNEWRELIC_INSTALL_PATH="C:\Program Files\New Relic\.NET Agent"NEWRELIC_HOME="C:\ProgramData\New Relic\.NET Agent" # may not be necessary due to registry key being setPour l'application .NET Core :
CORECLR_ENABLE_PROFILING=1CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}CORECLR_PROFILER_PATH="C:\Program Files\New Relic\.NET Agent\netcore\NewRelic.Profiler.dll"NEWRELIC_INSTALL_PATH="C:\Program Files\New Relic\.NET Agent"CORECLR_NEWRELIC_HOME="C:\ProgramData\New Relic\.NET Agent"Archive ZIP (Windows)
L'archive ZIP de l'agent pour Windows contient à la fois les versions Framework et Core de l'agent dans des répertoires côte à côte. Remplacez CUSTOM_AGENT_PATH par le chemin où vous décompressez l'archive sur votre système.
Pour les applications .NET Framework :
COR_ENABLE_PROFILING=1COR_PROFILER={71DA0A04-7777-4EC6-9643-7D28B46A8A41}COR_PROFILER_PATH="CUSTOM_AGENT_PATH\netframework\NewRelic.Profiler.dll"NEWRELIC_HOME="CUSTOM_AGENT_PATH\netframework"Pour l'application .NET Core :
CORECLR_ENABLE_PROFILING=1CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}CORECLR_PROFILER_PATH="CUSTOM_AGENT_PATH\netcore\NewRelic.Profiler.dll"CORECLR_NEWRELIC_HOME="CUSTOM_AGENT_PATH\netcore"Paquet Linux
Le package d'installation Linux (.deb ou .rpm, (selon votre distribution Linux) installe l'agent .NET pour .NET Core. Par défaut, il installe tout dans /usr/local/newrelic-dotnet-agent.
CORECLR_ENABLE_PROFILING=1CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}CORECLR_PROFILER_PATH="/usr/local/newrelic-dotnet-agent/libNewRelicProfiler.so"CORECLR_NEWRELIC_HOME="/usr/local/newrelic-dotnet-agent"Il existe également une archive .tar.gz de l'agent pour l'installation manuelle sous Linux. Dans ce cas, remplacez /usr/local/newrelic-dotnet-agent par l'endroit où vous décompressez l'archive sur votre système dans les variables ci-dessus.
Paquet NewRelic.Agent NuGet
Lorsqu'il est ajouté au projet de votre application, le package NewRelic.Agent NuGet ajoute l'agent à un sous-répertoire newrelic de votre application. La version correcte de l'agent est ajoutée pour .NET Framework ou .NET Core selon le type de votre application. Les profileurs pour Windows et Linux ont été ajoutés, y compris les versions 64 et 32 bits du profileur Windows et les versions x64 et arm64 du profileur Linux. En utilisant <YOUR_APPLICATION_PATH> comme espace réservé partout où votre application est déployée sur le système, ce sont les valeurs correctes des variables d'environnement.
Pour l'application .NET Framework (64 bits) :
COR_ENABLE_PROFILING=1COR_PROFILER={71DA0A04-7777-4EC6-9643-7D28B46A8A41}COR_PROFILER_PATH="<YOUR_APPLICATION_PATH>\newrelic\NewRelic.Profiler.dll"NEWRELIC_HOME="<YOUR_APPLICATION_PATH>\newrelic"Pour l'application .NET Framework (32 bits) :
COR_ENABLE_PROFILING=1COR_PROFILER={71DA0A04-7777-4EC6-9643-7D28B46A8A41}COR_PROFILER_PATH="<YOUR_APPLICATION_PATH>\newrelic\x86\NewRelic.Profiler.dll"NEWRELIC_HOME="<YOUR_APPLICATION_PATH>\newrelic"Pour l'application .NET Core (Windows) :
CORECLR_ENABLE_PROFILING=1CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}CORECLR_PROFILER_PATH="<YOUR_APPLICATION_PATH>\newrelic\NewRelic.Profiler.dll"CORECLR_NEWRELIC_HOME="<YOUR_APPLICATION_PATH>\newrelic"Pour les applications .NET Core (Linux, x64) :
CORECLR_ENABLE_PROFILING=1CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}CORECLR_PROFILER_PATH="<YOUR_APPLICATION_PATH>/newrelic/libNewRelicProfiler.so"CORECLR_NEWRELIC_HOME="<YOUR_APPLICATION_PATH>/newrelic"Pour les applications .NET Core (Linux, arm64) :
CORECLR_ENABLE_PROFILING=1CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}CORECLR_PROFILER_PATH="<YOUR_APPLICATION_PATH>/newrelic/linux-arm64/libNewRelicProfiler.so"CORECLR_NEWRELIC_HOME="<YOUR_APPLICATION_PATH>/newrelic"