Guide on Managing OpenTelemetry SDK/Instrumentation with Auto-Instrum…

…entation (#3472)

* Handling OpenTelemetry SDK/Instrumentation References in Applications with Auto-Instrumentation

* pr feedback

* pr feedback from pauljwil

docs/handling-opentelemetry-references.md

@@ -0,0 +1,55 @@
+# Handle adding automatic instrumentation to application with existing OpenTelemetry SDK and instrumentation references
+
+This document explains how OpenTelemetry automatic instrumentation interacts with
+applications that already include references to the OpenTelemetry SDK or instrumentation
+libraries. It covers the role and impact of the `OTEL_DOTNET_AUTO_SETUP_SDK`
+environment variable and provides troubleshooting guidance for conflicts between automatic
+instrumentation and existing references. The objective is to help users understand and
+effectively integrate OpenTelemetry automatic instrumentation into their applications.
+
+## Interaction with existing OpenTelemetry SDK and instrumentation references
+
+OpenTelemetry automatic instrumentation enhances .NET applications by
+automatically injecting and configuring the OpenTelemetry .NET SDK and adding
+OpenTelemetry instrumentation to key packages and APIs that the application uses.
+For applications without existing OpenTelemetry references, the process is seamless.
+However, for applications that already include OpenTelemetry SDK or
+instrumentation libraries, the interaction requires careful management to avoid
+conflicts.
+
+### The `OTEL_DOTNET_AUTO_SETUP_SDK` environment variable
+
+The `OTEL_DOTNET_AUTO_SETUP_SDK` environment variable plays a crucial role in
+managing the interaction between OpenTelemetry automatic instrumentation and existing
+OpenTelemetry references within an application. When set to `true`, this
+environment variable instructs the automatic instrumentation to automatically set up
+the OpenTelemetry SDK, ensuring that it is properly configured to work with the
+instrumentation injected by the automatic instrumentation.
+
+This automatic setup is particularly useful in scenarios where the application
+has its own references to OpenTelemetry libraries, as it helps to harmonize the
+configuration and ensure that telemetry data is collected and exported as
+expected.
+
+### Impact on applications
+
+The presence of the `OTEL_DOTNET_AUTO_SETUP_SDK` environment variable and its
+configuration can significantly impact how telemetry data is collected and
+exported in applications with existing OpenTelemetry references. When enabled,
+it ensures that the OpenTelemetry SDK is configured in a way that complements
+the automatic instrumentation, thereby enhancing the telemetry data collected
+without causing conflicts or duplication.
+
+### Troubleshooting
+
+When there are conflicts within an application between the OpenTelemetry
+automatic instrumentation and existing OpenTelemetry references, try
+these troubleshooting steps:
+
+1. Verify that the `OTEL_DOTNET_AUTO_SETUP_SDK` environment variable is set to
+   `true` to allow the automatic instrumentation to manage the SDK setup.
+2. Review the application's dependencies to identify any conflicting versions of
+   OpenTelemetry libraries and resolve them by aligning with the versions used
+   by the automatic instrumentation.
+3. Consult the [troubleshooting guide](troubleshooting.md) for additional advice
+   on resolving specific issues related to OpenTelemetry automatic instrumentation.