Merge branch 'master' into kr-igor/apms-17551

Author: kr-igor

.azure-pipelines/ultimate-pipeline.yml

@@ -947,7 +947,7 @@ stages:
     timeoutInMinutes: 60 #default value
     dependsOn: [ ]
     pool:
-      vmImage: macos-13
+      vmImage: macos-14
     steps:
     - template: steps/clone-repo.yml
       parameters:
@@ -967,7 +967,7 @@ stages:
     timeoutInMinutes: 60 #default value
     dependsOn: [ ]
     pool:
-      vmImage: macos-13
+      vmImage: macos-14
     steps:
     - template: steps/clone-repo.yml
       parameters:
@@ -992,7 +992,7 @@ stages:
     timeoutInMinutes: 60 #default value
     dependsOn: [native_tracer, native_loader_and_managed ]
     pool:
-      vmImage: macos-13
+      vmImage: macos-14
     steps:
     - checkout: none
 
@@ -1288,7 +1288,7 @@ stages:
     timeoutInMinutes: 60 #default value
     dependsOn: [ ]
     pool:
-      vmImage: macos-13
+      vmImage: macos-14
     steps:
       - template: steps/clone-repo.yml
         parameters:
@@ -1363,7 +1363,7 @@ stages:
         $[stageDependencies.generate_variables.generate_variables_job.outputs['generate_variables_step.unit_tests_macos_matrix'] ]
     timeoutInMinutes: 90
     pool:
-      vmImage: macos-13
+      vmImage: macos-14
     steps:
       - template: steps/clone-repo.yml
         parameters:
@@ -1619,7 +1619,7 @@ stages:
     - job: macos
       timeoutInMinutes: 60 #default value
       pool:
-        vmImage: macos-13
+        vmImage: macos-14
       steps:
         - template: steps/clone-repo.yml
           parameters:
@@ -1979,7 +1979,7 @@ stages:
     timeoutInMinutes: 60 #default value
     dependsOn: [ ]
     pool:
-      vmImage: macos-13
+      vmImage: macos-14
     steps:
     - template: steps/clone-repo.yml
       parameters:
@@ -2302,7 +2302,6 @@ stages:
     variables:
       TestAllPackageVersions: true
       IncludeMinorPackageVersions:  $[eq(variables.perform_comprehensive_testing, 'true')]
-      IntegrationTestFilter: DockerGroup=$(dockerGroup)
 
     pool:
       name: $(linuxX64Pool)
@@ -2319,6 +2318,14 @@ stages:
     - template: steps/download-samples.yml
       parameters:
         framework: $(publishTargetFramework)
+    - bash: |
+        if [ -z "$(IntegrationTestFilter)" ]; then
+          newFilter="DockerGroup=$(dockerGroup)"
+        else
+          newFilter="$(IntegrationTestFilter)&(DockerGroup=$(dockerGroup))"
+        fi
+        echo "##vso[task.setvariable variable=IntegrationTestFilter]$newFilter"
+      displayName: "Calculate IntegrationTestFilter"
 
     # when we build samples separately, we could run this step and the docker-compose one below in //
     # (currently the docker-compose step relies on serverless samples)

AGENTS.md

@@ -19,6 +19,25 @@
 - Loader/home: Build outputs publish a "monitoring home"; the native loader boots the tracer from there.
 - Build system: Nuke coordinates .NET builds and CMake/vcpkg for native components.
 
+## NuGet Package Architecture
+
+### Datadog.Trace Package
+The `Datadog.Trace` NuGet package provides the **manual instrumentation API** for customers:
+- **Contains**: `Datadog.Trace.Manual.dll` - Public API for manual instrumentation
+- **Does NOT contain**: Auto-instrumentation code or native profiler binaries
+- **Usage**: Reference in application code for manual tracing (e.g., `Tracer.Instance.StartActive()`)
+
+Auto-instrumentation comes from the tracer "monitoring home" deployed separately (via installers, MSI, container images, or specialized packages like `Datadog.AzureFunctions`).
+
+### Datadog.Trace.dll vs Datadog.Trace.Manual.dll
+- `Datadog.Trace.dll` - The full managed tracer with all auto-instrumentation code, loaded by the native profiler into instrumented processes
+- `Datadog.Trace.Manual.dll` - Lightweight manual instrumentation API packaged in the `Datadog.Trace` NuGet package for customer reference
+
+### Specialized Packages
+- **Datadog.AzureFunctions**: Bundles `Datadog.Trace.dll` and native profiler for Azure Functions (see `docs/development/AzureFunctions.md`)
+- **Datadog.Monitoring.Distribution**: MSI installer for Windows (IIS, Windows Services)
+- Other serverless/platform-specific packages may bundle the full tracer similarly
+
 ## Tracer Structure
 
 - `tracer/src/Datadog.Trace` — Core managed tracer library
@@ -199,10 +218,14 @@ tracer/src/Datadog.Trace
 - **Setup**: Use Azure App Services Site Extension on Windows Premium/Elastic Premium/Dedicated plans; use `Datadog.AzureFunctions` NuGet package for Linux Consumption/Container Apps
 - **Tests**: `BuildAndRunWindowsAzureFunctionsTests` Nuke target; samples under `tracer/test/test-applications/azure-functions/`
 - **Dependencies**: `Datadog.AzureFunctions` → `Datadog.Serverless.Compat` ([datadog-serverless-compat-dotnet](https://github.com/DataDog/datadog-serverless-compat-dotnet)) contains agent executable
+- **External Repos**: [Azure Functions Host](https://github.com/Azure/azure-functions-host) and [.NET Worker](https://github.com/Azure/azure-functions-dotnet-worker)
 
 📖 **Load when**: Working on Azure Functions instrumentation or debugging serverless issues
 - **`docs/development/AzureFunctions.md`** — In-process vs isolated worker models, instrumentation specifics, ASP.NET Core integration, GRPC context propagation, and debugging guide
 
+📖 **Load when**: Need detailed architectural understanding of Azure Functions internals
+- **`docs/development/AzureFunctions-Architecture.md`** — Deep dive into Azure Functions Host and .NET Worker architecture, gRPC protocol, middleware model, distributed tracing integration, environment variables, and instrumentation hook points
+
 📖 **Load when**: Working on AWS Lambda or general serverless instrumentation
 - **`docs/development/Serverless.md`** — Serverless instrumentation patterns across cloud providers
 
@@ -292,8 +315,10 @@ The tracer runs in-process with customer applications and must have minimal perf
 - `docs/development/AutomaticInstrumentation.md` — Creating integrations
 - `docs/development/DuckTyping.md` — Duck typing guide
 - `docs/development/AzureFunctions.md` — Azure Functions integration
+- `docs/development/AzureFunctions-Architecture.md` — Azure Functions architecture deep dive
 - `docs/development/Serverless.md` — Serverless instrumentation
 - `docs/development/UpdatingTheSdk.md` — SDK updates
+- `docs/development/QueryingDatadogAPIs.md` — Querying Datadog APIs for debugging (spans, logs)
 
 **CI & Testing:**
 - `docs/development/CI/TroubleshootingCIFailures.md` — Investigating build/test failures in Azure DevOps