[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69B815FCA7XVZCTFR35XRS7":3,"skill-same:01M69B815FCA7XVZCTFR35XRS7":103},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":28,"publishedAt":40,"linkOnly":41,"markdownContent":42,"markdownBody":43,"frontMatter":44,"refName":45,"commitSha":46,"skillDirectory":47,"forksCount":48,"repositoryHtmlUrl":49,"repositoryHomepageUrl":50,"ownerHtmlUrl":51,"ownerBlogUrl":52,"ownerDescription":53,"updatedAt":54,"install":55,"resources":68},"01M69B815FCA7XVZCTFR35XRS7","agents-sdk-dotnet-otel",null,"Use when adding, configuring, validating, or troubleshooting OpenTelemetry observability for a Microsoft 365 Agents SDK application in C# \u002F .NET. Trigger when the user mentions OpenTelemetry, OTel, telemetry, traces, metrics, logs, OTLP, Aspire Dashboard, Application Insights, Azure Monitor, distributed tracing, custom ActivitySource or Meter instrumentation, or observing Microsoft.Agents.Core signals.","microsoft\u002FAgents","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M69B7CR81D1HSNV69XDT8KAR",1109,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-net\u002Fskills\u002Fagents-sdk-dotnet-otel\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000013","分析与可视化","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000033","数据分析师","PROFESSION","适用职业",[29,30,31,32,33,34,9,35,36,37,38,39],"agents sdk","sdk","dotnet","otel","agents sdk dotnet otel","dashboard","telemetry","aspire","distributed","azure","monitor","2026-11-10 10:12:30",false,"---\nname: agents-sdk-dotnet-otel\ndescription: >\n  Use when adding, configuring, validating, or troubleshooting OpenTelemetry\n  observability for a Microsoft 365 Agents SDK application in C# \u002F .NET.\n  Trigger when the user mentions OpenTelemetry, OTel, telemetry, traces,\n  metrics, logs, OTLP, Aspire Dashboard, Application Insights, Azure Monitor,\n  distributed tracing, custom ActivitySource or Meter instrumentation, or\n  observing Microsoft.Agents.Core signals.\n---\n\n# OpenTelemetry for Agents SDK (.NET)\n\n## Goal\n\nConfigure traces, metrics, and logs for an Agents SDK application, including\nthe SDK's built-in `Microsoft.Agents.Core` signals and a local Aspire Dashboard.\nMake the smallest complete change that fits the existing hosting and telemetry\narchitecture.\n\nUse this skill for both `AgentApplication` and `ActivityHandler` applications.\nThe SDK telemetry source is the same for both.\n\n## Non-negotiable rules\n\n- Inspect the project before editing. Reuse and extend an existing\n  `AddOpenTelemetry()` registration instead of creating competing providers.\n- Register telemetry before `builder.Build()` and before the app processes\n  agent requests.\n- Subscribe to both `AgentsTelemetry.SourceName` and\n  `AgentsTelemetry.Meter`; the SDK has no direct OpenTelemetry dependency and\n  publishes through `System.Diagnostics`.\n- Give the application its own stable `service.name`. Do not use\n  `Microsoft.Agents.Core` as the service name; that is an instrumentation\n  source, not the application's identity.\n- Use OTLP environment variables rather than embedding collector URLs,\n  headers, API keys, or connection strings in source code.\n- Never capture message text, prompts, responses, access tokens,\n  authorization headers, cookies, secrets, attachment contents, user names,\n  user IDs, conversation IDs, activity IDs, or arbitrary HTTP headers by\n  default.\n- Keep metric attributes low-cardinality. Good dimensions include route type,\n  activity type, channel ID, operation, status, and error type. Do not put\n  per-user, per-conversation, per-message, URL, or exception-message values on\n  metrics.\n- Do not add `AlwaysOnSampler` as a production default. Honor the standard\n  `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG` configuration.\n- Aspire Dashboard anonymous mode is local-development only. Bind its ports to\n  loopback and do not deploy that configuration.\n- Telemetry must never swallow application exceptions or turn failures into\n  successful results.\n\n## Workflow\n\nComplete these steps in order.\n\n### 1. Inspect the application\n\nFind:\n\n- The web or generic-host project (`*.csproj`) and target framework.\n- `Program.cs` or the host-builder entry point.\n- Existing calls to `AddOpenTelemetry`, `ConfigureOpenTelemetry`,\n  `UseAzureMonitor`, `AddOtlpExporter`, `AddApplicationInsightsTelemetry`, or\n  custom observability extensions.\n- Existing `ActivitySource`, `Meter`, counters, histograms, and logging setup.\n- Existing OTEL settings in `appsettings*.json`, launch profiles, environment\n  files, container definitions, or deployment manifests.\n- Whether package versions are centrally managed in\n  `Directory.Packages.props`.\n\nIf OpenTelemetry already exists, merge the Agents SDK source and meter into\nthat registration. Do not replace existing exporters or instrumentation\nwithout a reason.\n\n### 2. Add only the required packages\n\nUse the repository's package-management convention. Keep all OpenTelemetry\npackages on a compatible stable version. When versions are not centrally\nmanaged, these commands select the latest stable packages:\n\n```powershell\ndotnet add package OpenTelemetry.Extensions.Hosting\ndotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol\ndotnet add package OpenTelemetry.Instrumentation.AspNetCore\ndotnet add package OpenTelemetry.Instrumentation.Http\ndotnet add package OpenTelemetry.Instrumentation.Runtime\n```\n\nDo not add the console exporter unless the user explicitly wants console\ntelemetry. Do not add Azure Monitor packages unless Azure Monitor export is\nrequested.\n\n### 3. Configure the providers\n\nPrefer a project-local extension such as `AgentOtelExtensions.cs`. Adapt the\nnamespace and service name to the project:\n\n```csharp\nusing Microsoft.Agents.Core.Telemetry;\nusing Microsoft.Extensions.Configuration;\nusing Microsoft.Extensions.DependencyInjection;\nusing Microsoft.Extensions.Hosting;\nusing Microsoft.Extensions.Logging;\nusing OpenTelemetry.Logs;\nusing OpenTelemetry.Metrics;\nusing OpenTelemetry.Resources;\nusing OpenTelemetry.Trace;\n\nnamespace MyAgent;\n\npublic static class AgentOtelExtensions\n{\n    public static TBuilder AddAgentObservability\u003CTBuilder>(\n        this TBuilder builder,\n        string serviceName,\n        string? serviceVersion = null,\n        string? applicationTelemetrySource = null)\n        where TBuilder : IHostApplicationBuilder\n    {\n        string resolvedServiceName =\n            builder.Configuration[\"OTEL_SERVICE_NAME\"] ?? serviceName;\n\n        var openTelemetry = builder.Services\n            .AddOpenTelemetry()\n            .ConfigureResource(resource => resource.AddService(\n                serviceName: resolvedServiceName,\n                serviceVersion: serviceVersion));\n\n        openTelemetry.WithTracing(tracing =>\n        {\n            tracing\n                .AddSource(AgentsTelemetry.SourceName)\n                .AddAspNetCoreInstrumentation(options =>\n                {\n                    options.RecordException = true;\n                    options.Filter = context =>\n                        !context.Request.Path.StartsWithSegments(\"\u002Fhealth\");\n                })\n                .AddHttpClientInstrumentation(options =>\n                {\n                    options.RecordException = true;\n                })\n                .AddOtlpExporter();\n\n            if (!string.IsNullOrWhiteSpace(applicationTelemetrySource))\n            {\n                tracing.AddSource(applicationTelemetrySource);\n            }\n        });\n\n        openTelemetry.WithMetrics(metrics =>\n        {\n            metrics\n                .AddMeter(AgentsTelemetry.SourceName)\n                .AddAspNetCoreInstrumentation()\n                .AddHttpClientInstrumentation()\n                .AddRuntimeInstrumentation()\n                .AddOtlpExporter();\n\n            if (!string.IsNullOrWhiteSpace(applicationTelemetrySource))\n            {\n                metrics.AddMeter(applicationTelemetrySource);\n            }\n        });\n\n        builder.Logging.AddOpenTelemetry(logging =>\n        {\n            logging.IncludeFormattedMessage = true;\n            logging.IncludeScopes = true;\n            logging.AddOtlpExporter();\n        });\n\n        return builder;\n    }\n}\n```\n\nNotes:\n\n- If the project does not expose `\u002Fhealth`, keeping the filter is harmless.\n- If an existing telemetry extension already adds ASP.NET Core, HTTP client,\n  runtime, or OTLP instrumentation, add only the missing\n  `AgentsTelemetry.SourceName` source and meter.\n- Do not manually add `\"Microsoft.AspNetCore\"` or `\"System.Net.Http\"` activity\n  source strings when the corresponding instrumentation packages are already\n  configured.\n- `service.name` should identify the application, for example\n  `contoso-support-agent`. Keep it stable across instances.\n- Use `service.version` for the deployed build\u002Fversion when one is available.\n- Use resource attributes such as `deployment.environment.name` for stable\n  deployment metadata, not request-specific data.\n\nCall the extension before the agent registrations:\n\n```csharp\nWebApplicationBuilder builder = WebApplication.CreateBuilder(args);\n\nbuilder.AddAgentObservability(\n    serviceName: \"contoso-support-agent\",\n    serviceVersion: typeof(Program).Assembly.GetName().Version?.ToString(),\n    applicationTelemetrySource: AgentTelemetry.SourceName);\n\nbuilder.AddAgentDefaults()\n    .AddAgent\u003CMyAgent>()\n    .AddAgentAuthorization(options => options.AddAgentAspNetAuthentication());\n```\n\nIf no custom application telemetry is needed, omit\n`applicationTelemetrySource` and do not create `AgentTelemetry`.\n\n### 4. Configure OTLP without secrets in source\n\nFor a local Aspire Dashboard using OTLP\u002FgRPC:\n\n```powershell\n$env:OTEL_SERVICE_NAME = \"contoso-support-agent\"\n$env:OTEL_EXPORTER_OTLP_ENDPOINT = \"http:\u002F\u002Flocalhost:4317\"\n$env:OTEL_EXPORTER_OTLP_PROTOCOL = \"grpc\"\ndotnet run\n```\n\nStandard environment variables to support:\n\n| Variable | Purpose |\n|---|---|\n| `OTEL_SERVICE_NAME` | Stable application service name |\n| `OTEL_RESOURCE_ATTRIBUTES` | Stable resource metadata |\n| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base OTLP collector endpoint |\n| `OTEL_EXPORTER_OTLP_PROTOCOL` | Usually `grpc` or `http\u002Fprotobuf` |\n| `OTEL_EXPORTER_OTLP_HEADERS` | Collector authentication headers; keep secret |\n| `OTEL_TRACES_SAMPLER` | Trace sampling strategy |\n| `OTEL_TRACES_SAMPLER_ARG` | Sampling strategy argument |\n\nUse user secrets, a secret store, or deployment secrets for\n`OTEL_EXPORTER_OTLP_HEADERS` and Azure Monitor connection strings. Never place\nthem in committed `appsettings.json` or launch profiles.\n\n### 5. Add custom business telemetry only when useful\n\nThe Agents SDK already emits adapter, turn, route, connector, storage,\nauthentication, and authorization signals. Add custom telemetry for\napplication-specific operations, not to duplicate those SDK spans.\n\nUse one shared source name for the application's custom traces and metrics:\n\n```csharp\nusing System.Diagnostics;\nusing System.Diagnostics.Metrics;\n\nnamespace MyAgent;\n\npublic static class AgentTelemetry\n{\n    public const string SourceName = \"Contoso.SupportAgent\";\n\n    public static readonly ActivitySource ActivitySource = new(SourceName);\n    public static readonly Meter Meter = new(SourceName);\n\n    public static readonly Counter\u003Clong> RouteExecutions =\n        Meter.CreateCounter\u003Clong>(\n            \"agent.route.executions\",\n            unit: \"{execution}\",\n            description: \"Number of application route executions.\");\n\n    public static readonly Histogram\u003Cdouble> RouteDuration =\n        Meter.CreateHistogram\u003Cdouble>(\n            \"agent.route.duration\",\n            unit: \"ms\",\n            description: \"Application route execution duration.\");\n}\n```\n\nInstrument a handler with bounded attributes:\n\n```csharp\nusing System.Diagnostics;\n\nusing Activity? activity =\n    AgentTelemetry.ActivitySource.StartActivity(\"agent.route.execute\");\nlong started = Stopwatch.GetTimestamp();\nstring status = \"ok\";\n\ntry\n{\n    await HandleMessageAsync(turnContext, cancellationToken);\n}\ncatch (Exception exception)\n{\n    status = \"error\";\n    activity?.SetStatus(ActivityStatusCode.Error, exception.Message);\n    activity?.AddException(exception);\n    throw;\n}\nfinally\n{\n    TagList tags = new()\n    {\n        { \"route.type\", \"message\" },\n        { \"status\", status }\n    };\n\n    AgentTelemetry.RouteExecutions.Add(1, tags);\n    AgentTelemetry.RouteDuration.Record(\n        Stopwatch.GetElapsedTime(started).TotalMilliseconds,\n        tags);\n}\n```\n\nIf `AddException` is unavailable for the project's package version, add an\n`exception` activity event using the OpenTelemetry semantic attributes. Do not\nlog or tag the prompt, response, or exception message as a metric dimension.\n\n### 6. Set up the Aspire Dashboard\n\nCopy `assets\u002Fstart-aspire-dashboard.ps1` from this skill into a suitable local\ndevelopment or scripts directory. The script pulls\n`mcr.microsoft.com\u002Fdotnet\u002Faspire-dashboard:latest`.\n\nRun:\n\n```powershell\n.\\start-aspire-dashboard.ps1\n```\n\nThen open `http:\u002F\u002Flocalhost:18888`. The script:\n\n- Binds the UI and OTLP ports to `127.0.0.1`.\n- Exposes OTLP\u002FgRPC on `4317` and OTLP\u002FHTTP on `4318`.\n- Enables unsecured access only for local development.\n- Runs the dashboard in a disposable Docker container.\n\nDo not start a second container if `aspire-dashboard` already exists. Inspect\nor reuse the existing container instead. Stop the generated local dashboard\nwith:\n\n```powershell\ndocker stop aspire-dashboard\n```\n\n### 7. Validate end to end\n\n1. Run the smallest applicable `dotnet build`.\n2. Start the Aspire Dashboard and confirm the container remains running.\n3. Start the agent with the OTLP environment variables.\n4. Send at least one message through the Agents Playground or configured\n   channel.\n   Metrics are exported periodically and can take one or more export intervals,\n   plus dashboard processing time, to appear. Wait and refresh the dashboard\n   before diagnosing missing metrics.\n5. In Aspire Dashboard, confirm:\n   - The resource uses the application's `service.name`.\n   - Traces include `agents.adapter.process` or `agents.app.run`.\n   - Metrics include `agents.activities.received`, `agents.turn.count`, or\n     another operation exercised by the test.\n   - Application logs appear and correlate with traces when trace context is\n     present.\n6. Exercise one failure path when practical and confirm the span is marked\n   `Error` while the original exception behavior remains intact.\n\nSee [references\u002Fsdk-signals.md](references\u002Fsdk-signals.md) for the canonical\nAgents SDK source, common spans, metrics, and dashboard checks.\n\n## Exporter choices\n\n### Aspire Dashboard or another OTLP collector\n\nUse `OpenTelemetry.Exporter.OpenTelemetryProtocol` and `AddOtlpExporter()`.\nThis is the default for local development and vendor-neutral deployments.\n\n### Azure Monitor \u002F Application Insights\n\nWhen requested, add the stable\n`Azure.Monitor.OpenTelemetry.AspNetCore` package and configure\n`UseAzureMonitor()` using `APPLICATIONINSIGHTS_CONNECTION_STRING` from a\nsecret source. Preserve OTLP export only when dual export is intentional.\nDo not add both exporters accidentally.\n\n### Console\n\nUse only for short-lived local diagnosis. Console telemetry is noisy, can\nexpose data in terminal logs, and is not a production exporter.\n\n## Troubleshooting\n\n| Symptom | Check |\n|---|---|\n| No SDK spans | `.AddSource(AgentsTelemetry.SourceName)` is present before requests |\n| No SDK metrics | `.AddMeter(AgentsTelemetry.SourceName)` is present |\n| Custom spans missing | The custom `ActivitySource` name exactly matches `.AddSource(...)` |\n| Custom metrics missing | The custom `Meter` name exactly matches `.AddMeter(...)` |\n| Dashboard has no resource | Dashboard is running; endpoint is `http:\u002F\u002Flocalhost:4317`; protocol is `grpc` |\n| Traces appear but metrics do not | Metrics can take one or more `OTEL_METRIC_EXPORT_INTERVAL` periods plus dashboard processing time to appear; wait and refresh before troubleshooting |\n| OTLP `Unimplemented` or protocol errors | Collector port and `OTEL_EXPORTER_OTLP_PROTOCOL` do not match |\n| Duplicate spans or metrics | Multiple providers or repeated instrumentation registrations exist |\n| High memory or telemetry cost | Remove high-cardinality tags and reduce trace sampling |\n| Logs appear but traces do not | Trace source subscription or sampling configuration is wrong |\n| Traces appear but logs do not | `builder.Logging.AddOpenTelemetry(...).AddOtlpExporter()` is missing |\n| Container name conflict | Reuse or stop the existing `aspire-dashboard` container |\n\n## Contributing\n\nIf the SDK signals differ from\n[references\u002Fsdk-signals.md](references\u002Fsdk-signals.md), the sample no longer\nbuilds, or the Aspire setup changes, draft an issue containing the project\ntype, package versions, configuration, expected signal, actual result, and any\nworkaround: https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagents\u002Fissues\u002Fnew\n","# OpenTelemetry for Agents SDK (.NET)\n\n## Goal\n\nConfigure traces, metrics, and logs for an Agents SDK application, including\nthe SDK's built-in `Microsoft.Agents.Core` signals and a local Aspire Dashboard.\nMake the smallest complete change that fits the existing hosting and telemetry\narchitecture.\n\nUse this skill for both `AgentApplication` and `ActivityHandler` applications.\nThe SDK telemetry source is the same for both.\n\n## Non-negotiable rules\n\n- Inspect the project before editing. Reuse and extend an existing\n  `AddOpenTelemetry()` registration instead of creating competing providers.\n- Register telemetry before `builder.Build()` and before the app processes\n  agent requests.\n- Subscribe to both `AgentsTelemetry.SourceName` and\n  `AgentsTelemetry.Meter`; the SDK has no direct OpenTelemetry dependency and\n  publishes through `System.Diagnostics`.\n- Give the application its own stable `service.name`. Do not use\n  `Microsoft.Agents.Core` as the service name; that is an instrumentation\n  source, not the application's identity.\n- Use OTLP environment variables rather than embedding collector URLs,\n  headers, API keys, or connection strings in source code.\n- Never capture message text, prompts, responses, access tokens,\n  authorization headers, cookies, secrets, attachment contents, user names,\n  user IDs, conversation IDs, activity IDs, or arbitrary HTTP headers by\n  default.\n- Keep metric attributes low-cardinality. Good dimensions include route type,\n  activity type, channel ID, operation, status, and error type. Do not put\n  per-user, per-conversation, per-message, URL, or exception-message values on\n  metrics.\n- Do not add `AlwaysOnSampler` as a production default. Honor the standard\n  `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG` configuration.\n- Aspire Dashboard anonymous mode is local-development only. Bind its ports to\n  loopback and do not deploy that configuration.\n- Telemetry must never swallow application exceptions or turn failures into\n  successful results.\n\n## Workflow\n\nComplete these steps in order.\n\n### 1. Inspect the application\n\nFind:\n\n- The web or generic-host project (`*.csproj`) and target framework.\n- `Program.cs` or the host-builder entry point.\n- Existing calls to `AddOpenTelemetry`, `ConfigureOpenTelemetry`,\n  `UseAzureMonitor`, `AddOtlpExporter`, `AddApplicationInsightsTelemetry`, or\n  custom observability extensions.\n- Existing `ActivitySource`, `Meter`, counters, histograms, and logging setup.\n- Existing OTEL settings in `appsettings*.json`, launch profiles, environment\n  files, container definitions, or deployment manifests.\n- Whether package versions are centrally managed in\n  `Directory.Packages.props`.\n\nIf OpenTelemetry already exists, merge the Agents SDK source and meter into\nthat registration. Do not replace existing exporters or instrumentation\nwithout a reason.\n\n### 2. Add only the required packages\n\nUse the repository's package-management convention. Keep all OpenTelemetry\npackages on a compatible stable version. When versions are not centrally\nmanaged, these commands select the latest stable packages:\n\n```powershell\ndotnet add package OpenTelemetry.Extensions.Hosting\ndotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol\ndotnet add package OpenTelemetry.Instrumentation.AspNetCore\ndotnet add package OpenTelemetry.Instrumentation.Http\ndotnet add package OpenTelemetry.Instrumentation.Runtime\n```\n\nDo not add the console exporter unless the user explicitly wants console\ntelemetry. Do not add Azure Monitor packages unless Azure Monitor export is\nrequested.\n\n### 3. Configure the providers\n\nPrefer a project-local extension such as `AgentOtelExtensions.cs`. Adapt the\nnamespace and service name to the project:\n\n```csharp\nusing Microsoft.Agents.Core.Telemetry;\nusing Microsoft.Extensions.Configuration;\nusing Microsoft.Extensions.DependencyInjection;\nusing Microsoft.Extensions.Hosting;\nusing Microsoft.Extensions.Logging;\nusing OpenTelemetry.Logs;\nusing OpenTelemetry.Metrics;\nusing OpenTelemetry.Resources;\nusing OpenTelemetry.Trace;\n\nnamespace MyAgent;\n\npublic static class AgentOtelExtensions\n{\n    public static TBuilder AddAgentObservability\u003CTBuilder>(\n        this TBuilder builder,\n        string serviceName,\n        string? serviceVersion = null,\n        string? applicationTelemetrySource = null)\n        where TBuilder : IHostApplicationBuilder\n    {\n        string resolvedServiceName =\n            builder.Configuration[\"OTEL_SERVICE_NAME\"] ?? serviceName;\n\n        var openTelemetry = builder.Services\n            .AddOpenTelemetry()\n            .ConfigureResource(resource => resource.AddService(\n                serviceName: resolvedServiceName,\n                serviceVersion: serviceVersion));\n\n        openTelemetry.WithTracing(tracing =>\n        {\n            tracing\n                .AddSource(AgentsTelemetry.SourceName)\n                .AddAspNetCoreInstrumentation(options =>\n                {\n                    options.RecordException = true;\n                    options.Filter = context =>\n                        !context.Request.Path.StartsWithSegments(\"\u002Fhealth\");\n                })\n                .AddHttpClientInstrumentation(options =>\n                {\n                    options.RecordException = true;\n                })\n                .AddOtlpExporter();\n\n            if (!string.IsNullOrWhiteSpace(applicationTelemetrySource))\n            {\n                tracing.AddSource(applicationTelemetrySource);\n            }\n        });\n\n        openTelemetry.WithMetrics(metrics =>\n        {\n            metrics\n                .AddMeter(AgentsTelemetry.SourceName)\n                .AddAspNetCoreInstrumentation()\n                .AddHttpClientInstrumentation()\n                .AddRuntimeInstrumentation()\n                .AddOtlpExporter();\n\n            if (!string.IsNullOrWhiteSpace(applicationTelemetrySource))\n            {\n                metrics.AddMeter(applicationTelemetrySource);\n            }\n        });\n\n        builder.Logging.AddOpenTelemetry(logging =>\n        {\n            logging.IncludeFormattedMessage = true;\n            logging.IncludeScopes = true;\n            logging.AddOtlpExporter();\n        });\n\n        return builder;\n    }\n}\n```\n\nNotes:\n\n- If the project does not expose `\u002Fhealth`, keeping the filter is harmless.\n- If an existing telemetry extension already adds ASP.NET Core, HTTP client,\n  runtime, or OTLP instrumentation, add only the missing\n  `AgentsTelemetry.SourceName` source and meter.\n- Do not manually add `\"Microsoft.AspNetCore\"` or `\"System.Net.Http\"` activity\n  source strings when the corresponding instrumentation packages are already\n  configured.\n- `service.name` should identify the application, for example\n  `contoso-support-agent`. Keep it stable across instances.\n- Use `service.version` for the deployed build\u002Fversion when one is available.\n- Use resource attributes such as `deployment.environment.name` for stable\n  deployment metadata, not request-specific data.\n\nCall the extension before the agent registrations:\n\n```csharp\nWebApplicationBuilder builder = WebApplication.CreateBuilder(args);\n\nbuilder.AddAgentObservability(\n    serviceName: \"contoso-support-agent\",\n    serviceVersion: typeof(Program).Assembly.GetName().Version?.ToString(),\n    applicationTelemetrySource: AgentTelemetry.SourceName);\n\nbuilder.AddAgentDefaults()\n    .AddAgent\u003CMyAgent>()\n    .AddAgentAuthorization(options => options.AddAgentAspNetAuthentication());\n```\n\nIf no custom application telemetry is needed, omit\n`applicationTelemetrySource` and do not create `AgentTelemetry`.\n\n### 4. Configure OTLP without secrets in source\n\nFor a local Aspire Dashboard using OTLP\u002FgRPC:\n\n```powershell\n$env:OTEL_SERVICE_NAME = \"contoso-support-agent\"\n$env:OTEL_EXPORTER_OTLP_ENDPOINT = \"http:\u002F\u002Flocalhost:4317\"\n$env:OTEL_EXPORTER_OTLP_PROTOCOL = \"grpc\"\ndotnet run\n```\n\nStandard environment variables to support:\n\n| Variable | Purpose |\n|---|---|\n| `OTEL_SERVICE_NAME` | Stable application service name |\n| `OTEL_RESOURCE_ATTRIBUTES` | Stable resource metadata |\n| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base OTLP collector endpoint |\n| `OTEL_EXPORTER_OTLP_PROTOCOL` | Usually `grpc` or `http\u002Fprotobuf` |\n| `OTEL_EXPORTER_OTLP_HEADERS` | Collector authentication headers; keep secret |\n| `OTEL_TRACES_SAMPLER` | Trace sampling strategy |\n| `OTEL_TRACES_SAMPLER_ARG` | Sampling strategy argument |\n\nUse user secrets, a secret store, or deployment secrets for\n`OTEL_EXPORTER_OTLP_HEADERS` and Azure Monitor connection strings. Never place\nthem in committed `appsettings.json` or launch profiles.\n\n### 5. Add custom business telemetry only when useful\n\nThe Agents SDK already emits adapter, turn, route, connector, storage,\nauthentication, and authorization signals. Add custom telemetry for\napplication-specific operations, not to duplicate those SDK spans.\n\nUse one shared source name for the application's custom traces and metrics:\n\n```csharp\nusing System.Diagnostics;\nusing System.Diagnostics.Metrics;\n\nnamespace MyAgent;\n\npublic static class AgentTelemetry\n{\n    public const string SourceName = \"Contoso.SupportAgent\";\n\n    public static readonly ActivitySource ActivitySource = new(SourceName);\n    public static readonly Meter Meter = new(SourceName);\n\n    public static readonly Counter\u003Clong> RouteExecutions =\n        Meter.CreateCounter\u003Clong>(\n            \"agent.route.executions\",\n            unit: \"{execution}\",\n            description: \"Number of application route executions.\");\n\n    public static readonly Histogram\u003Cdouble> RouteDuration =\n        Meter.CreateHistogram\u003Cdouble>(\n            \"agent.route.duration\",\n            unit: \"ms\",\n            description: \"Application route execution duration.\");\n}\n```\n\nInstrument a handler with bounded attributes:\n\n```csharp\nusing System.Diagnostics;\n\nusing Activity? activity =\n    AgentTelemetry.ActivitySource.StartActivity(\"agent.route.execute\");\nlong started = Stopwatch.GetTimestamp();\nstring status = \"ok\";\n\ntry\n{\n    await HandleMessageAsync(turnContext, cancellationToken);\n}\ncatch (Exception exception)\n{\n    status = \"error\";\n    activity?.SetStatus(ActivityStatusCode.Error, exception.Message);\n    activity?.AddException(exception);\n    throw;\n}\nfinally\n{\n    TagList tags = new()\n    {\n        { \"route.type\", \"message\" },\n        { \"status\", status }\n    };\n\n    AgentTelemetry.RouteExecutions.Add(1, tags);\n    AgentTelemetry.RouteDuration.Record(\n        Stopwatch.GetElapsedTime(started).TotalMilliseconds,\n        tags);\n}\n```\n\nIf `AddException` is unavailable for the project's package version, add an\n`exception` activity event using the OpenTelemetry semantic attributes. Do not\nlog or tag the prompt, response, or exception message as a metric dimension.\n\n### 6. Set up the Aspire Dashboard\n\nCopy `assets\u002Fstart-aspire-dashboard.ps1` from this skill into a suitable local\ndevelopment or scripts directory. The script pulls\n`mcr.microsoft.com\u002Fdotnet\u002Faspire-dashboard:latest`.\n\nRun:\n\n```powershell\n.\\start-aspire-dashboard.ps1\n```\n\nThen open `http:\u002F\u002Flocalhost:18888`. The script:\n\n- Binds the UI and OTLP ports to `127.0.0.1`.\n- Exposes OTLP\u002FgRPC on `4317` and OTLP\u002FHTTP on `4318`.\n- Enables unsecured access only for local development.\n- Runs the dashboard in a disposable Docker container.\n\nDo not start a second container if `aspire-dashboard` already exists. Inspect\nor reuse the existing container instead. Stop the generated local dashboard\nwith:\n\n```powershell\ndocker stop aspire-dashboard\n```\n\n### 7. Validate end to end\n\n1. Run the smallest applicable `dotnet build`.\n2. Start the Aspire Dashboard and confirm the container remains running.\n3. Start the agent with the OTLP environment variables.\n4. Send at least one message through the Agents Playground or configured\n   channel.\n   Metrics are exported periodically and can take one or more export intervals,\n   plus dashboard processing time, to appear. Wait and refresh the dashboard\n   before diagnosing missing metrics.\n5. In Aspire Dashboard, confirm:\n   - The resource uses the application's `service.name`.\n   - Traces include `agents.adapter.process` or `agents.app.run`.\n   - Metrics include `agents.activities.received`, `agents.turn.count`, or\n     another operation exercised by the test.\n   - Application logs appear and correlate with traces when trace context is\n     present.\n6. Exercise one failure path when practical and confirm the span is marked\n   `Error` while the original exception behavior remains intact.\n\nSee [references\u002Fsdk-signals.md](references\u002Fsdk-signals.md) for the canonical\nAgents SDK source, common spans, metrics, and dashboard checks.\n\n## Exporter choices\n\n### Aspire Dashboard or another OTLP collector\n\nUse `OpenTelemetry.Exporter.OpenTelemetryProtocol` and `AddOtlpExporter()`.\nThis is the default for local development and vendor-neutral deployments.\n\n### Azure Monitor \u002F Application Insights\n\nWhen requested, add the stable\n`Azure.Monitor.OpenTelemetry.AspNetCore` package and configure\n`UseAzureMonitor()` using `APPLICATIONINSIGHTS_CONNECTION_STRING` from a\nsecret source. Preserve OTLP export only when dual export is intentional.\nDo not add both exporters accidentally.\n\n### Console\n\nUse only for short-lived local diagnosis. Console telemetry is noisy, can\nexpose data in terminal logs, and is not a production exporter.\n\n## Troubleshooting\n\n| Symptom | Check |\n|---|---|\n| No SDK spans | `.AddSource(AgentsTelemetry.SourceName)` is present before requests |\n| No SDK metrics | `.AddMeter(AgentsTelemetry.SourceName)` is present |\n| Custom spans missing | The custom `ActivitySource` name exactly matches `.AddSource(...)` |\n| Custom metrics missing | The custom `Meter` name exactly matches `.AddMeter(...)` |\n| Dashboard has no resource | Dashboard is running; endpoint is `http:\u002F\u002Flocalhost:4317`; protocol is `grpc` |\n| Traces appear but metrics do not | Metrics can take one or more `OTEL_METRIC_EXPORT_INTERVAL` periods plus dashboard processing time to appear; wait and refresh before troubleshooting |\n| OTLP `Unimplemented` or protocol errors | Collector port and `OTEL_EXPORTER_OTLP_PROTOCOL` do not match |\n| Duplicate spans or metrics | Multiple providers or repeated instrumentation registrations exist |\n| High memory or telemetry cost | Remove high-cardinality tags and reduce trace sampling |\n| Logs appear but traces do not | Trace source subscription or sampling configuration is wrong |\n| Traces appear but logs do not | `builder.Logging.AddOpenTelemetry(...).AddOtlpExporter()` is missing |\n| Container name conflict | Reuse or stop the existing `aspire-dashboard` container |\n\n## Contributing\n\nIf the SDK signals differ from\n[references\u002Fsdk-signals.md](references\u002Fsdk-signals.md), the sample no longer\nbuilds, or the Aspire setup changes, draft an issue containing the project\ntype, package versions, configuration, expected signal, actual result, and any\nworkaround: https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fagents\u002Fissues\u002Fnew\n",{"name":5,"description":7},"main","8171bc7e0ca3b8defd578a6bb317367c2901983f","agent-plugins\u002Fagents-for-net\u002Fskills\u002Fagents-sdk-dotnet-otel",346,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents","https:\u002F\u002Faka.ms\u002Fagentsdkdocs","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-14 08:54:12",{"source":8,"skillName":5,"commands":56,"prompt":66,"zipAvailable":67},[57,60,63],{"tool":58,"command":59},"npx","npx skills add microsoft\u002FAgents --skill agents-sdk-dotnet-otel",{"tool":61,"command":62},"bunx","bunx skills add microsoft\u002FAgents --skill agents-sdk-dotnet-otel",{"tool":64,"command":65},"pnpm","pnpm dlx skills add microsoft\u002FAgents --skill agents-sdk-dotnet-otel","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-net\u002Fskills\u002Fagents-sdk-dotnet-otel\u002FSKILL.md",true,[69,75,81,85,89,93,99],{"path":70,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":73,"sourceHtmlUrl":74},"assets\u002Fstart-aspire-dashboard.ps1","SCRIPT","脚本",976,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-net\u002Fskills\u002Fagents-sdk-dotnet-otel\u002Fassets\u002Fstart-aspire-dashboard.ps1",{"path":76,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":79,"sourceHtmlUrl":80},"examples\u002F3p-updates.md","REFERENCE","参考文档",3274,"https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002F_collections\u002Ftravisvn-awesome-claude-skills\u002Fanthropics-skills\u002Fskills\u002Finternal-comms\u002Fexamples\u002F3p-updates.md",{"path":82,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":83,"sourceHtmlUrl":84},"examples\u002Fcompany-newsletter.md",3295,"https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002F_collections\u002Ftravisvn-awesome-claude-skills\u002Fanthropics-skills\u002Fskills\u002Finternal-comms\u002Fexamples\u002Fcompany-newsletter.md",{"path":86,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":87,"sourceHtmlUrl":88},"examples\u002Ffaq-answers.md",2366,"https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002F_collections\u002Ftravisvn-awesome-claude-skills\u002Fanthropics-skills\u002Fskills\u002Finternal-comms\u002Fexamples\u002Ffaq-answers.md",{"path":90,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":91,"sourceHtmlUrl":92},"examples\u002Fgeneral-comms.md",602,"https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002F_collections\u002Ftravisvn-awesome-claude-skills\u002Fanthropics-skills\u002Fskills\u002Finternal-comms\u002Fexamples\u002Fgeneral-comms.md",{"path":94,"resourceType":95,"resourceTypeDesc":96,"sizeBytes":97,"sourceHtmlUrl":98},"LICENSE.txt","LICENSE","许可证",11357,"https:\u002F\u002Fgithub.com\u002Fshengdabai\u002FTony-Claude-Code-Skills\u002Fblob\u002Fmain\u002Fskills\u002F_collections\u002Ftravisvn-awesome-claude-skills\u002Fanthropics-skills\u002Fskills\u002Finternal-comms\u002FLICENSE.txt",{"path":100,"resourceType":77,"resourceTypeDesc":78,"sizeBytes":101,"sourceHtmlUrl":102},"references\u002Fsdk-signals.md",4386,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-net\u002Fskills\u002Fagents-sdk-dotnet-otel\u002Freferences\u002Fsdk-signals.md",[104,122,142,154,166,175],{"skillNo":105,"name":106,"nameZh":6,"description":107,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":40},"01M6PJCYCYJQDX318SQN3EBF0E","sync-teams-samples-to-agents-sdk","CI instructions for a bounded Teams SDK to Agents SDK sample synchronization using the selected language profile.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fautomation\u002Fteams-sample-sync\u002Fskills\u002Fsync-teams-samples-to-agents-sdk\u002FSKILL.md",[],[29,30,111,112,113,114,115,116,117,118,119,120,121],"sync","teams","sync teams samples to agents sdk","ci","synchronization","instructions","profile","language","sample","for","bounded",{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":126,"categories":127,"keywords":128,"publishedAt":40},"01M6PJCFNGCX555YERYQ459JFE","teams-sdk-to-agents-sdk-typescript-migration","Migrate a JavaScript or TypeScript application using the Microsoft Teams SDK App runtime to Microsoft 365 Agents SDK while preserving its Teams behaviors. Use for Teams SDK migrations, including automated sample synchronization; use the separate Bot Framework migration skill for botbuilder applications.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-js\u002Fskills\u002Fteams-sdk-to-agents-sdk-typescript-migration\u002FSKILL.md",[],[112,129,29,30,130,131,132,133,134,135,136,119,137,138,115,139,120,140,141,9],"typescript","agents sdk typescript","migration","teams sdk to agents sdk typescript migration","microsoft teams","applications","app","runtime","migrations","use","migrate","bot","javascript",{"skillNo":143,"name":144,"nameZh":6,"description":145,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":146,"categories":147,"keywords":151,"publishedAt":40},"01M69B8QV24JVPXH25EH77X0SZ","teams-app-manifest","Create or audit a Microsoft Teams app manifest for an existing Microsoft 365 Agents SDK application by mapping declared intent and source-code evidence to released manifest capabilities. Use when manifest.json is missing, incomplete, or must be checked against implemented Teams features. Does not configure Microsoft Entra, Azure Bot, Developer Portal, or deployment unless separately requested.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-sdk-common\u002Fskills\u002Fteams-app-manifest\u002FSKILL.md",[148],{"categoryNo":149,"categoryName":150,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000030","开发工程师",[112,152,30,140,29,9,38,153],"teams app manifest","deployment",{"skillNo":155,"name":156,"nameZh":6,"description":157,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":158,"categories":159,"keywords":160,"publishedAt":40},"01M69B8MN62NBY93YTJAQG2Y81","agents-sdk-provision","Use when provisioning Azure resources for a Microsoft Agents SDK application — including creating an Azure Bot Service resource, setting up Entra app registrations, configuring identity credentials (UserManagedIdentity, FederatedCredentials, or ClientSecret), adding a Teams channel, running Bicep deployments for SSO, or setting up OAuth user sign-in connections via az CLI. Trigger even if the user doesn't say \"provision\" — use on requests like \"set up my bot on Azure\", \"deploy my bot\", \"configure Azure for my bot\", or \"get Teams SSO working.\" Applies to all languages (dotnet, Node.js, Python).","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-sdk-common\u002Fskills\u002Fagents-sdk-provision\u002FSKILL.md",[],[29,30,161,140,162,163,9,31,164,165,38,112],"agents sdk provision","cli","python","identity","deploy",{"skillNo":167,"name":168,"nameZh":6,"description":169,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":170,"categories":171,"keywords":172,"publishedAt":40},"01M69B8HFZ45NQGWQQD483TWPB","agents-sdk-to-prod","Assess, create, harden, deploy, or review production readiness of Python Microsoft 365 Agents SDK agents and their direct hosting\u002Foperations files. Use only for Agents SDK scenarios, not unrelated application hardening.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-python\u002Fskills\u002Fagents-sdk-to-prod\u002FSKILL.md",[],[173,30,29,9,163,174,165],"agents sdk to prod","review",{"skillNo":176,"name":177,"nameZh":6,"description":178,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":179,"categories":180,"keywords":183,"publishedAt":40},"01M69B8ENJGC9NPQBZAYAN4706","agents-sdk-python-otel","Use when adding, configuring, validating, or troubleshooting OpenTelemetry observability for a Microsoft 365 Agents SDK application in Python. Trigger when the user mentions OpenTelemetry, OTel, telemetry, traces, metrics, logs, OTLP, Aspire Dashboard, Application Insights, Azure Monitor, distributed tracing, custom tracers or meters, span sampling, or observing microsoft_agents SDK signals.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FAgents\u002Fblob\u002Fmain\u002Fagent-plugins\u002Fagents-for-python\u002Fskills\u002Fagents-sdk-python-otel\u002FSKILL.md",[181,182],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},[29,163,32,30,184,36,38,35,9,34,37,185,39],"agents sdk python otel","aspire dashboard"]