Refine scripts docs

[pellared]

Why

Attempt to address #1354 (comment) and #1354 (comment)

Part of #1373

What

• Make the docs clearer. Preview: https://github.com/pellared/opentelemetry-dotnet-instrumentation/blob/clear-docs/docs/README.md
• Opportunistic fix: make the scripts work in Shell (so it should work on Alpine)

Next PRs

• Test the "shell script" in the Alpine container.
• Change default $INSTALL_DIR to $HOME/.otel-dotnet-auto (based on dotnet-install.sh)
• Try guessing the value for $OS_TYPE if not provided
• Add instrument.sh to the release zip archive
• (After release) Update the README.md and ci.yml to use instrument.sh included in the zip

[pellared]

What do you think of including the instrument.sh and instrument.ps1 to the zip file (so that they do not have to be additionally downloaded)?

Then we could change these 2 lines to

. ./otel-dotnet-auto/instrument.sh

I would rather address it in a separate PR.

[RassK]

After considering loads of different install options, I think instrument.sh is definitely needed and should be in the package.
(since in linux you probably need to configure some service watch, so you can easily add instrument.sh before the real applications wake up call)

Leaves only question about service discovery if custom path was used. Although I don't have currently any real clues for Linux, why you should have custom path.

[pellared]

1. If one uses a custom path then he/she can use $INSTALL_DIR
2. I think it would be better if the parameter name would be $OTEL_DOTNET_AUTO_HOME -> then one could set it globally. It will be also "unique".

instrument.sh is definitely needed and should be in the package

After we do it and make a release, we update the script in README.md to take advantage of it. But no sooner than that (we need the package to be published.

[Kielek]

It is not fully true.
CORECLR_PROFILER_PATH is also working on Windows. See

opentelemetry-dotnet-instrumentation/src/OpenTelemetry.AutoInstrumentation.Native/cor_profiler.cpp

Lines 901 to 922 in d05630f

	WSTRING CorProfiler::GetCoreCLRProfilerPath()
	{
	WSTRING native_profiler_file;
	#ifdef BIT64
	native_profiler_file = GetEnvironmentValue(WStr("CORECLR_PROFILER_PATH_64"));
	Logger::Debug("GetProfilerFilePath: CORECLR_PROFILER_PATH_64 defined as: ", native_profiler_file);
	if (native_profiler_file == EmptyWStr)
	{
	native_profiler_file = GetEnvironmentValue(WStr("CORECLR_PROFILER_PATH"));
	Logger::Debug("GetProfilerFilePath: CORECLR_PROFILER_PATH defined as: ", native_profiler_file);
	}
	#else // BIT64
	native_profiler_file = GetEnvironmentValue(WStr("CORECLR_PROFILER_PATH_32"));
	Logger::Debug("GetProfilerFilePath: CORECLR_PROFILER_PATH_32 defined as: ", native_profiler_file);
	if (native_profiler_file == EmptyWStr)
	{
	native_profiler_file = GetEnvironmentValue(WStr("CORECLR_PROFILER_PATH"));
	Logger::Debug("GetProfilerFilePath: CORECLR_PROFILER_PATH defined as: ", native_profiler_file);
	}
	#endif // BIT64
	return native_profiler_file;
	}

[pellared]

It is but we are recommending using both CORECLR_PROFILER_PATH_32 and CORECLR_PROFILER_PATH_64 instead. The same recommendation is currently on main and the same behavior can be found in envvars.sh

[pellared]

We even do not encourage setting it on Windows in config.md.

[Kielek]

What's about COR_PROFILER_PATH? It is also supported.

[pellared]

Same as below.