open-telemetry
/
opentelemetry-dotnet-instrumentation
mirror of https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
opentelemetry-dotnet-instru.../docs/internal/using-the-nuget-packages.md

3.1 KiB
Raw Blame History

Using the OpenTelemetry.AutoInstrumentation NuGet packages

Warning Currently, NuGet packages are only available as CI artifacts. When following these instructions, ensure that the packages are downloaded and that the target project is either using a nuget.config file configured to use the downloaded packages, for example the nuget.config used by the NuGet packages test applications, or the packages are added to the project by specifying the --source parameter when running dotnet add package command.

When to use the NuGet packages

Use the NuGet packages in the following scenarios:

  1. Simplify deployment. For example, a container running a single application.
  2. Support instrumentation of self-contained applications.
  3. Facilitate developer experimentation with automatic instrumentation through NuGet packages.

Limitations

While NuGet packages are a convenient way to deploy automatic instrumentation, they can't be used in all cases. The most common reasons for not using NuGet packages include the following:

  1. You can't add the package to the application project. For example, the application is from a third party that can't add the package.
  2. Reduce disk usage, or the size of a virtual machine, when multiple applications to be instrumented are installed in a single machine. In this case you can use a single deployment for all .NET applications running on the machine.
  3. A legacy application that can't be migrated to the SDK-style project.

Using the NuGet packages

To automatically instrument your application with OpenTelemetry .NET add the OpenTelemetry.AutoInstrumentation package to your project:

dotnet add [<PROJECT>] package OpenTelemetry.AutoInstrumentation --source <PATH_TO_AUTO_INSTRUMENTATION_PACKAGES> --prerelease

To distribute the appropriate native runtime components with your .NET application, specify a Runtime Identifier (RID) to build the application using dotnet build or dotnet publish. This might require choosing between distributing a self-contained or a framework-dependent application. Both types are compatible with automatic instrumentation.

Use the script in the output folder of the build to launch the application with automatic instrumentation activated.

  • On Windows, use instrument.cmd <application_executable>
  • On Linux or Unix, use instrument.sh <application_executable>

If you launch the application using the dotnet CLI, add dotnet after the script.

  • On Windows, use instrument.cmd dotnet <application>
  • On Linux and Unix, use instrument.sh dotnet <application>

The script passes to the application all the command-line parameters you provide.