commit 7b5c79a0e449094c36acfe8f3d2753ba39aa2d83 Author: Zhongwei Li Date: Sun Nov 30 08:38:16 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..9babfda --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,16 @@ +{ + "name": "dd-trace-dotnet-azure-functions", + "description": "Azure Functions-specific commands for Datadog .NET tracer development. Includes building, testing, debugging, and deploying Azure Functions instrumentation.", + "version": "1.0.0", + "author": { + "name": "Lucas Pimentel", + "github": "lucaspimentel" + }, + "commands": [ + "./commands/azure-functions-nuget.md", + "./commands/create-sample-function.md", + "./commands/debug-azure-functions.md", + "./commands/deploy-azure.md", + "./commands/test-azure-functions.md" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..d223d01 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# dd-trace-dotnet-azure-functions + +Azure Functions-specific commands for Datadog .NET tracer development. Includes building, testing, debugging, and deploying Azure Functions instrumentation. diff --git a/commands/azure-functions-nuget.md b/commands/azure-functions-nuget.md new file mode 100644 index 0000000..6acc3c1 --- /dev/null +++ b/commands/azure-functions-nuget.md @@ -0,0 +1,25 @@ +--- +description: Build Azure Functions NuGet package +--- + +Build the Datadog Azure Functions NuGet package for testing. + +Steps: +1. Run the build script: `tracer/tools/Build-AzureFunctionsNuget.ps1 -CopyTo D:/temp/nuget` +2. The script will: + - Build the Datadog.AzureFunctions project + - Create a NuGet package + - Copy it to the specified directory + +Usage in Azure Functions: +- Add local NuGet source in `nuget.config` pointing to `D:/temp/nuget` +- Reference the package in your function app: `` + +After building: +- Report the package version and location +- Show the output directory contents +- Provide instructions for testing in a function app + +Related commands: +- Test with Azure Functions: Use `BuildAndRunWindowsAzureFunctionsTests` Nuke target +- Sample apps: `tracer/test/test-applications/azure-functions/` diff --git a/commands/create-sample-function.md b/commands/create-sample-function.md new file mode 100644 index 0000000..1cdf38e --- /dev/null +++ b/commands/create-sample-function.md @@ -0,0 +1,206 @@ +--- +description: Create a sample Azure Function for testing +--- + +Create a sample Azure Function application for testing Datadog instrumentation. + +## Choose Function Type + +### 1. In-Process Function (.NET 6+) + +**Create project**: +```bash +func init MyFunctionApp --worker-runtime dotnet +cd MyFunctionApp +func new --template "HTTP trigger" --name HttpTrigger +``` + +**Add Datadog NuGet package**: +```xml + +``` + +**Update Program.cs** (.NET 6+ in-process): +```csharp +using Microsoft.Extensions.Hosting; + +var host = new HostBuilder() + .ConfigureFunctionsWorkerDefaults() + .Build(); + +host.Run(); +``` + +### 2. Isolated Worker Function (.NET 7+) + +**Create project**: +```bash +func init MyFunctionApp --worker-runtime dotnet-isolated +cd MyFunctionApp +func new --template "HTTP trigger" --name HttpTrigger +``` + +**Add Datadog NuGet package**: +```xml + +``` + +**Update Program.cs**: +```csharp +using Microsoft.Extensions.Hosting; + +var host = new HostBuilder() + .ConfigureFunctionsWorkerDefaults() + .Build(); + +host.Run(); +``` + +### 3. In-Process Function (.NET Framework 4.8) + +**Create project** (requires Visual Studio or manual setup): +```xml +net48 +v4 +``` + +For .NET Framework, use the **Site Extension** deployment method instead of NuGet. + +## Configure Settings + +### local.settings.json + +```json +{ + "IsEncrypted": false, + "Values": { + "AzureWebJobsStorage": "UseDevelopmentStorage=true", + "FUNCTIONS_WORKER_RUNTIME": "dotnet", + "DD_API_KEY": "your-api-key-here", + "DD_SITE": "datadoghq.com", + "DD_ENV": "dev", + "DD_SERVICE": "my-function-app", + "DD_VERSION": "1.0.0", + "DD_TRACE_DEBUG": "false" + } +} +``` + +### Add Instrumentation Code (Optional) + +For custom spans: +```csharp +using Datadog.Trace; + +public class HttpTrigger +{ + [FunctionName("HttpTrigger")] + public async Task Run( + [HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequest req, + ILogger log) + { + using var scope = Tracer.Instance.StartActive("custom.operation"); + scope.Span.SetTag("custom.tag", "value"); + + // Your function logic + + return new OkObjectResult("Hello from Datadog!"); + } +} +``` + +## Test Locally + +**Run the function**: +```bash +func start +``` + +**Invoke the function**: +```bash +curl http://localhost:7071/api/HttpTrigger +``` + +**Verify traces**: +- Check Datadog APM for traces +- Review local logs for tracer messages +- Confirm spans are created + +## Deploy to Azure + +### Using Azure CLI: + +**Create function app**: +```bash +az functionapp create \ + --resource-group lucas.pimentel \ + --consumption-plan-location eastus \ + --runtime dotnet \ + --functions-version 4 \ + --name lucasp-test-function \ + --storage-account +``` + +**Deploy**: +```bash +func azure functionapp publish lucasp-test-function +``` + +**Configure Datadog settings**: +```bash +az functionapp config appsettings set \ + --name lucasp-test-function \ + --resource-group lucas.pimentel \ + --settings DD_API_KEY= DD_SITE=datadoghq.com DD_ENV=test +``` + +## Add Different Trigger Types + +### Timer Trigger: +```bash +func new --template "Timer trigger" --name TimerTrigger +``` + +### Queue Trigger: +```bash +func new --template "Queue trigger" --name QueueTrigger +``` + +### Blob Trigger: +```bash +func new --template "Blob trigger" --name BlobTrigger +``` + +## Test Integration Points + +**HTTP calls**: +```csharp +using var httpClient = new HttpClient(); +var response = await httpClient.GetAsync("https://api.example.com"); +``` + +**Database calls**: +```csharp +using var connection = new SqlConnection(connectionString); +await connection.OpenAsync(); +``` + +**Azure SDK calls**: +```csharp +var blobClient = new BlobClient(connectionString, containerName, blobName); +await blobClient.DownloadAsync(); +``` + +## Reference Sample Applications + +For working examples, see: +``` +tracer/test/test-applications/azure-functions/ +``` + +These samples demonstrate: +- Different runtime versions +- In-process vs isolated worker +- Various trigger types +- Custom instrumentation +- Datadog configuration diff --git a/commands/debug-azure-functions.md b/commands/debug-azure-functions.md new file mode 100644 index 0000000..57d02b9 --- /dev/null +++ b/commands/debug-azure-functions.md @@ -0,0 +1,135 @@ +--- +description: Debug Azure Functions instrumentation issues +--- + +Debug Azure Functions instrumentation issues with the Datadog .NET tracer. + +Common debugging scenarios: + +## 1. Tracer Not Loading + +**Check environment variables**: +```bash +az functionapp config appsettings list --name --resource-group lucas.pimentel +``` + +Required settings for **Site Extension** (Windows): +- `DD_DOTNET_TRACER_HOME` - Path to tracer home +- `CORECLR_ENABLE_PROFILING=1` or `COR_ENABLE_PROFILING=1` +- `CORECLR_PROFILER` or `COR_PROFILER` - CLSID +- `DD_API_KEY` - Datadog API key +- `DD_SITE` - Datadog site (datadoghq.com, etc.) + +Required settings for **NuGet Package** (Linux/Container): +- `DD_API_KEY` - Datadog API key +- `DD_SITE` - Datadog site +- Package reference in `.csproj` + +## 2. Check Application Logs + +**Stream logs**: +```bash +az webapp log tail --name --resource-group lucas.pimentel +``` + +**Download logs**: +```bash +az webapp log download --name --resource-group lucas.pimentel --log-file logs.zip +``` + +Look for: +- Tracer initialization messages +- "Datadog.Trace.ClrProfiler.Managed.Loader" startup +- Configuration loading messages +- Integration registration +- Error messages or exceptions + +## 3. Verify Tracer Files + +**For Site Extension** (Windows): +- Check `D:\home\SiteExtensions\Datadog.Trace.AzureAppServices\` +- Verify native profiler DLLs are present +- Confirm managed assemblies exist + +**For NuGet Package** (Linux): +- Check package is restored: `ls bin/Debug/net6.0/` +- Verify `Datadog.AzureFunctions.dll` is present +- Check agent executable is in package dependencies + +## 4. Test Locally + +Run Azure Functions locally with the tracer: + +**In-process**: +```bash +func start +``` + +**Isolated worker**: +```bash +func start +``` + +Set environment variables in `local.settings.json`: +```json +{ + "Values": { + "DD_API_KEY": "your-key", + "DD_SITE": "datadoghq.com", + "DD_ENV": "local", + "DD_SERVICE": "my-function", + "DD_TRACE_DEBUG": "true" + } +} +``` + +## 5. Common Issues + +**Issue: Traces not appearing** +- Check DD_API_KEY is set correctly +- Verify DD_SITE matches your Datadog region +- Check network connectivity to Datadog agent/intake +- Look for errors in application logs + +**Issue: Instrumentation not working** +- Verify profiler environment variables are set +- Check tracer version compatibility +- Ensure runtime version is supported +- Review AGENTS.md for supported runtimes + +**Issue: Performance degradation** +- Check tracer overhead in logs +- Review sampling configuration +- Verify trace volume is reasonable +- Check for excessive custom instrumentation + +**Issue: Isolated worker not instrumented** +- Verify using .NET 5+ for isolated worker +- Check that NuGet package is referenced correctly +- Ensure worker process has environment variables +- Review gRPC context propagation + +## 6. Enable Debug Logging + +Set `DD_TRACE_DEBUG=true` to get verbose tracer logs. + +Check debug logs for: +- Integration discovery +- Method instrumentation +- Span creation and finishing +- Context propagation +- Agent communication + +## 7. Verify Sample Applications + +Test with sample apps first: +``` +tracer/test/test-applications/azure-functions/ +├── InProcess.Net6/ +├── InProcess.NetFramework48/ +├── Isolated.Net5/ +├── Isolated.Net7/ +└── ... +``` + +These are known-working configurations to compare against. diff --git a/commands/deploy-azure.md b/commands/deploy-azure.md new file mode 100644 index 0000000..4e3777f --- /dev/null +++ b/commands/deploy-azure.md @@ -0,0 +1,49 @@ +--- +description: Deploy and test with Azure resources +--- + +Deploy and test the .NET tracer with Azure resources. + +Available Azure resources (resource group: lucas.pimentel): +- Function apps starting with prefix: `lucasp-*` + +Common tasks: + +1. **List Function Apps**: + ```bash + az functionapp list --resource-group lucas.pimentel --output table + ``` + +2. **Get Function App Details**: + ```bash + az functionapp show --name --resource-group lucas.pimentel + ``` + +3. **List Functions in App**: + ```bash + az functionapp function list --name --resource-group lucas.pimentel + ``` + +4. **Check App Settings**: + ```bash + az functionapp config appsettings list --name --resource-group lucas.pimentel + ``` + +5. **Download Logs**: + ```bash + az webapp log download --name --resource-group lucas.pimentel --log-file logs.zip + ``` + +Deployment scenarios: +- **Site Extension** (Windows): Deploy via Azure portal or ARM template +- **NuGet Package** (Linux/Container): Build with `/azure-functions-nuget` and deploy with package reference + +Before deploying: +- Build the tracer or NuGet package +- Verify Azure CLI is authenticated: `az account show` +- Confirm target function app exists + +After deploying: +- Check application logs for tracer initialization +- Verify traces are being sent to Datadog +- Test instrumented functionality diff --git a/commands/test-azure-functions.md b/commands/test-azure-functions.md new file mode 100644 index 0000000..87db7e5 --- /dev/null +++ b/commands/test-azure-functions.md @@ -0,0 +1,49 @@ +--- +description: Run Azure Functions integration tests +--- + +Run Azure Functions integration tests for the Datadog .NET tracer. + +Test options: + +1. **Full Azure Functions test suite**: + ```bash + .\build.cmd BuildAndRunWindowsAzureFunctionsTests + ``` + +2. **Run specific test projects**: + ```bash + dotnet test tracer/test/Datadog.Trace.ClrProfiler.IntegrationTests/Datadog.Trace.ClrProfiler.IntegrationTests.csproj --filter "FullyQualifiedName~AzureFunctions" + ``` + +3. **Test with specific function app samples**: + - Sample apps location: `tracer/test/test-applications/azure-functions/` + - Available samples: + - In-process (.NET Framework, .NET 6+) + - Isolated worker (.NET 5+, .NET 7+) + - HTTP triggers, timer triggers, queue triggers + - Various runtime versions + +Test scenarios covered: +- **In-process model**: Functions running in the same process as the host +- **Isolated worker model**: Functions running in separate worker process +- **Instrumentation**: Auto-instrumentation via site extension or NuGet package +- **Trace propagation**: HTTP headers, queue messages +- **Metrics**: Runtime metrics, custom metrics +- **Logging**: ILogger integration with Datadog + +Before running tests: +1. Ensure Docker is running (some tests require containers) +2. Check Azure Functions Core Tools are installed: `func --version` +3. Verify build is up to date + +Common test filters: +- `--filter "Category=AzureFunctions"` - All Azure Functions tests +- `--filter "Category=Smoke&FullyQualifiedName~AzureFunctions"` - Smoke tests only +- `--framework net6.0` - Specific framework + +After running: +- Review test results (passed/failed/skipped) +- Check test logs for instrumentation verification +- Analyze any failures for patterns +- Verify traces are properly generated diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..ff60f7c --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,61 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:lucaspimentel/claude-code-plugins:plugins/dd-trace-dotnet-azure-functions", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "e99af1d85af81a40cf35994ad4761e0985391fa3", + "treeHash": "575a0ba15c840fa833c546271a2d31baf2f6b65a4c4c54acd1acfd6b79a4d49b", + "generatedAt": "2025-11-28T10:20:22.707602Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "dd-trace-dotnet-azure-functions", + "description": "Azure Functions-specific commands for Datadog .NET tracer development. Includes building, testing, debugging, and deploying Azure Functions instrumentation.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "3bd0913fd45fc3f0126122e49f54e4d9957d3f57ab3bef327138a8687a426ec6" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "11a017975041e2363ee1bf2c30f256df716c925a1f89d86517eacea8897d75a2" + }, + { + "path": "commands/azure-functions-nuget.md", + "sha256": "8bfcfeab679f5315bcf8db420da590f8000e6ca0349c3b2541217f2e6f0c90ff" + }, + { + "path": "commands/test-azure-functions.md", + "sha256": "81bbd7bbfe849c44e59f5da0f86ab0a5cb26c3ead220793b31a67538b7c0c3bb" + }, + { + "path": "commands/deploy-azure.md", + "sha256": "70aa32965890f8a73037b2a3d493d80261025050ef56471b126a85f418fd122e" + }, + { + "path": "commands/create-sample-function.md", + "sha256": "dc5ed0cfdfaaaad3e33df00a5dddbf704f0459a6bcc43d1c7b0fc061f493cce5" + }, + { + "path": "commands/debug-azure-functions.md", + "sha256": "0e0959d693966249a2ce4cc4396a3b87169502bead61fa847bf53cc96f84a319" + } + ], + "dirSha256": "575a0ba15c840fa833c546271a2d31baf2f6b65a4c4c54acd1acfd6b79a4d49b" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file