Update install documentation to clarify use of NEWRELIC_INSTALL_PATH vs. NEWRELIC_HOME/CORECLR_NEWRELIC_HOME

[nr-ahemsath]

Our support team pointed out some apparent inconsistencies in our configuration documentation, regarding the use of these environment variables:

NEWRELIC_INSTALL_PATH NEWRELIC_HOME CORECLR_NEWRELIC_HOME

Here's the document in question: https://docs.newrelic.com/docs/apm/agents/net-agent/configuration/net-agent-configuration

Specifically these sections: https://docs.newrelic.com/docs/apm/agents/net-agent/configuration/net-agent-configuration#net-framework-env-variables https://docs.newrelic.com/docs/apm/agents/net-agent/configuration/net-agent-configuration#net-core-env-variables

Issues with current document:

1. We say that NEWRELIC_INSTALL_PATH is required for .NET Framework, but we don't say that NEWRELIC_HOME is.
2. For .NET Core on Windows, we say that both NEWRELIC_INSTALL_PATH and CORECLR_NEWRELIC_HOME are required, but the example shown has them both set to the same value.
3. We only say that COR_PROFILER_PATH/CORECLR_PROFILER_PATH is required for one of the three cases. Technically, this is true if the agent is installed with the MSI, which adds registry keys that the .NET CLR can search for by the CLSID (the GUID value for COR_PROFILER or CORECLR_PROFILER.

This agent code is a good start for seeing how NEWRELIC_INSTALL_PATH is used vs. how NEWRELIC_HOME or CORECLR_NEWRELIC_HOME is used: https://github.com/newrelic/newrelic-dotnet-agent/blob/5e0836c13feffee73a8101cc1dd4e1890a78ec22/src/Agent/NewRelic/Agent/Core/AgentInstallConfiguration.cs#L175-L186 The td;dr is that the agent falls back on the home dir value is the install dir path is not set. The "even more tl;dr" is that NEWRELIC_INSTALL_PATH is only necessary when the agent assets are located in two different places - as is the case when the agent is installed with the MSI (the MSI places binaries in C:\Program Files\New Relic\.NET Agent and text files (e.g. newrelic.config and the instrumentation XMLs in extensions) in C:\ProgramData\New Relic\.NET Agent.)

So, the documented values for "required environment variables" in the configuration documentation seem accurate as long as the agent was installed with the MSI...but if the agent was installed with the MSI, customers generally don't have to think about the environment variables as they are set automatically. If the agent was not installed with the MSI, these documented values are incorrect. This, at least, should be fixed.

Useful links: https://docs.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ee471451(v=vs.100)?redirectedfrom=MSDN#startup-load-profilers https://discuss.newrelic.com/t/relic-solution-net-framework-agent-required-environment-variables/68971 https://discuss.newrelic.com/t/relic-solution-net-core-agent-required-environment-variables/68972

[nr-ahemsath]

The problems with the documentation will be partially solved with this PR: https://github.com/newrelic/docs-website/pull/7234

I want to leave this issue open to drive further improvements to our documentation around the env vars required to make the agent work.

[github-actions[bot]]

This Issue has been marked stale after 90 days with no activity. It will be closed in 30 days if there is no activity.

[workato-integration[bot]]

https://issues.newrelic.com/browse/NEWRELIC-5582

[workato-integration[bot]]

Jira CommentId: 176595 Commented by ahemsath:

Work in progress document to explain a lot of the inconsistencies described above: https://github.com/nr-ahemsath/docs-website/blob/dotnet-agent-required-environment-variables-update/src/content/docs/apm/agents/net-agent/other-installation/understanding-net-agent-environment-variables.mdx

[workato-integration[bot]]

Jira CommentId: 177253 Commented by ahemsath:

Work remaining:

Add some more examples of correct env var settings for known install scenarios

Solicit feedback from team

Link to this new document from relevant places around the agent documentation

[workato-integration[bot]]

Jira CommentId: 178406 Commented by ahemsath:

PR (draft): [https://github.com/newrelic/docs-website/pull/12474]

 

[workato-integration[bot]]

Work has been completed on this issue.