Document Azure Functions span parenting issue (APMSVLS-58)

Added detailed documentation of the span parenting issue that occurs
with isolated Azure Functions using ASP.NET Core integration.

The issue: Worker process spans are incorrectly parented to the root
host span instead of the HTTP client span that makes the host-to-worker
call.

Documentation includes:
- Visual comparison of current vs expected span hierarchy
- Root cause analysis of context propagation flow
- Technical details about HTTP proxying and gRPC integration
- Step-by-step reproduction instructions
- Example code and API queries for verification
- Files that need to be modified for the fix

Author: lucaspimentel

docs/development/AzureFunctions.md

@@ -95,6 +95,82 @@ Whether a Functions app uses this new mode is subtle:
 
 and the project will have a reference to [Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore/) package.
 
+## Known Issues and Fixes
+
+### Span Parenting Issue with ASP.NET Core Integration (APMSVLS-58)
+
+**Problem:**
+When using isolated Azure Functions with ASP.NET Core Integration, spans created in the worker process are incorrectly parented to the root host span instead of the HTTP client span that makes the host→worker call.
+
+**Current (Incorrect) Behavior:**
+```
+ROOT: azure_functions.invoke: GET /api/httptest [PID 27 - HOST]
+  ├─ http.request: GET localhost:40521/api/HttpTest [HOST → WORKER HTTP call]
+  └─ azure_functions.invoke: Http HttpTest [PID 56 - WORKER] ❌ WRONG PARENT
+      ├─ test_span [WORKER]
+      └─ http.request: GET jsonplaceholder... [WORKER]
+```
+
+**Expected (Correct) Behavior:**
+```
+ROOT: azure_functions.invoke: GET /api/httptest [PID 27 - HOST]
+  └─ http.request: GET localhost:40521/api/HttpTest [HOST → WORKER HTTP call]
+      └─ azure_functions.invoke: Http HttpTest [PID 56 - WORKER] ✓ CORRECT PARENT
+          ├─ test_span [WORKER]
+          └─ http.request: GET jsonplaceholder... [WORKER]
+```
+
+**Root Cause:**
+In `GrpcMessageConversionExtensionsToRpcHttpIntegration.cs`, the code injects the Azure Functions host span context into the gRPC message (line 87-88). However, when HTTP proxying is enabled with ASP.NET Core integration:
+
+1. The host process creates an HTTP client call to the worker process (`GET localhost:40521/api/HttpTest`)
+2. The HTTP client instrumentation automatically creates a span for this call
+3. The HTTP client automatically propagates its trace context in the HTTP headers
+4. However, the gRPC integration has already injected the *parent* span's context (the Azure Functions host span) into the gRPC message
+5. The worker process extracts context from both sources, but prefers the gRPC context
+6. This causes worker spans to be parented to the wrong span (the host root instead of the HTTP call)
+
+**Technical Details:**
+- When `isHttpProxying` is true, `func.exe` makes an actual HTTP call to the worker instead of only using gRPC
+- The HTTP client span (e.g., `GET localhost:40521`) is created *after* `ToRpcHttp()` runs
+- Currently, `ToRpcHttp()` injects the Azure Functions span context regardless of proxying mode
+- The HTTP client instrumentation then injects its own context into HTTP headers
+- The worker receives both contexts and needs to choose the correct one
+
+**Solution:**
+When HTTP proxying is enabled (`isHttpProxying && !requiresRouteParameters`), we should not inject trace context into the gRPC message. Instead, let the HTTP client instrumentation handle context propagation naturally through HTTP headers. This ensures worker spans are properly parented to the HTTP call span.
+
+**How to Reproduce:**
+1. Deploy an isolated Azure Functions app with ASP.NET Core integration
+2. Create a function that makes an outbound HTTP call with a custom span:
+   ```csharp
+   [Function(nameof(HttpTest))]
+   public async Task<IActionResult> HttpTest([HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest request)
+   {
+       using (var scope = Tracer.Instance.StartActive("test_span"))
+       {
+           using var httpClient = new HttpClient();
+           await httpClient.GetStringAsync("https://jsonplaceholder.typicode.com/users/1");
+           return new OkObjectResult(new { message = "success" });
+       }
+   }
+   ```
+3. Trigger the function via HTTP: `curl https://<function-app>.azurewebsites.net/api/HttpTest`
+4. Query traces via Datadog API:
+   ```bash
+   curl -G "https://api.datadoghq.com/api/v2/spans/events" \
+     --data-urlencode "filter[query]=service:<function-app> resource_name:*HttpTest*" \
+     --data-urlencode "filter[from]=now-10m" \
+     --data-urlencode "page[limit]=10" \
+     -H "DD-API-KEY: <key>" \
+     -H "DD-APPLICATION-KEY: <app-key>"
+   ```
+5. Examine the `parent_id` of worker spans - they will incorrectly point to the root host span
+
+**Files Involved:**
+- `tracer/src/Datadog.Trace/ClrProfiler/AutoInstrumentation/Azure/Functions/Isolated/GrpcMessageConversionExtensionsToRpcHttpIntegration.cs`
+- `tracer/src/Datadog.Trace/ClrProfiler/AutoInstrumentation/Azure/Functions/AzureFunctionsCommon.cs`
+
 ## Debugging
 
 To debug Azure Functions locally ensure that you have the following: