Documentation very unfriendly for beginning .NET folks

[fsiler]

Feature Request

Is your feature request related to a problem? Please describe.
I'm an experienced programmer building observability stacks. Figuring out the Java agent approach wasn't too bad. I don't think this is conceptually that difficult, but I need more information about how the injection of this library works, both conceptually and practically.

I have an OpenTelemetry collector agent running on my network. I would expect to be able to set OTEL_EXPORTER_OTLP_ENDPOINT=http://hostname:4317 and generally, have things work once I've appropriately set up the project to inject the agent. However, I can't for the life of me figure out how to install and initialize the agent in my code.

I cannot get any of the canned examples to run, getting messages like /opt/homebrew/Cellar/dotnet/6.0.110/libexec/sdk/6.0.110/Sdks/Microsoft.NET.Sdk/targets/Microsoft.NET.TargetFrameworkInference.targets(144,5): error NETSDK1045: The current .NET SDK does not support targeting .NET 7.0. Either target .NET 6.0 or lower, or use a version of the .NET SDK that supports .NET 7.0. [/Users/DT235813/build/opentelemetry-dotnet-instrumentation/examples/AspNetCoreMvc/Examples.AspNetCoreMvc.csproj] even though I selected net6.0 in the environment I gave to run-example.sh. It would be very useful to have a script with documented flags about what the acceptable parameters are, and I don't understand why there is one run-example.sh for the entire repo instead of one per example.

I followed this example to get a simple .NET web app up and running. It works well. My question: what do I need to do to instrument the resultant code with this agent? I get the idea of adding something to a manifest file, and possibly doing some kind of initialization in code. Fine. Where does that stuff go? Conceptually, how does it work?

Describe the solution you'd like
I'd like someone to not assume a lot of prior CLR/.NET knowledge, and explain both conceptually and in practical terms how to set this up.

Describe alternatives you've considered
As I mentioned above, I have attempted both to instrument my own example by adding

  <ItemGroup>
    <PackageReference Include="OpenTelemetry" Version="1.4.0-beta.3" />
    <PackageReference Include="System.Runtime.InteropServices.RuntimeInformation" Version="4.3.0" />
  </ItemGroup>

to the project.csproj file, which appeared to have no effect. I also attempted many permutations of invoking instrument.sh, which appears to have no effect at all.

Finally, I attempted to run the run-example.sh code with no success.

Additional context
n/a.

[pellared]

I cannot get any of the canned examples to run,

I am currently reworking the example as I also find them unfriendly😉 PTAL #1708 . Feel free to add comments 👍

what do I need to do to instrument the resultant code with this agent?

https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/v0.5.0/docs/README.md#get-started

Conceptually, how does it work?

https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/docs/design.md

I have attempted both to instrument my own example by adding

This packages are needed when doing manual instrumentation: https://opentelemetry.io/docs/instrumentation/net/manual/

The auto-instrumentation requires deploying the auto-instrumentation binaries and setting appropriate env vars when starting the application (so that it gets instrumented).

Feel free to ask for more questions if anything is unclear. Feedback is welcome 😉

[Kielek]

@fsiler, the issue you have mentioned
/opt/homebrew/Cellar/dotnet/6.0.110/libexec/sdk/6.0.110/Sdks/Microsoft.NET.Sdk/targets/Microsoft.NET.TargetFrameworkInference.targets(144,5): error NETSDK1045: The current .NET SDK does not support targeting .NET 7.0. Either target .NET 6.0 or lower, or use a version of the .NET SDK that supports .NET 7.0. [/Users/DT235813/build/opentelemetry-dotnet-instrumentation/examples/AspNetCoreMvc/Examples.AspNetCoreMvc.csproj].

It looks like you have installed .NET SDK 6 on your dev machine. Examples are also targeting .NET 7.
You can either install also newer version https://dotnet.microsoft.com/en-us/download or remove net7 target from the csproj files.

[pjanotti]

SIG: closing next week if no new actionable information.

[fsiler]

This can probably be closed. I may make a PR with a quickstart explaining what I learned.

[pellared]

I may make a PR with a quickstart explaining what I learned.

This would be awesome. Or even pointing out what docs could be improved.