v11 update: Native OpenTelemetry tracing for ASP.NET Core

aspnetcore/metrics/overview.md の既存の ASP.NET Core 11 セクションで、AddAspNetCoreInstrumentation の段落の後を更新します。まず周辺の tracing に関するガイダンスを読み、その後 AppContext xref、moniker の動作、レンダリング、OpenPublishing.Build の警告を確認します。opt-out スイッチがその場所で見つけられ、breaking-change の記事を重複させていなければ完了です。

Target repository: dotnet/AspNetCore.Docs
Analyzed at commit: 4986136881f2bbf1879f10106467769df5a49932
Product source verified at: dotnet/aspnetcore @ 1fcd7ef305697a1888f3ede076010350ae9f4f8d
Source release note: Native OpenTelemetry tracing for ASP.NET Core

---

🎯 Goal

Record that native OpenTelemetry HTTP-server tracing is already substantially documented in evergreen docs, then close the one discoverability gap: the Metrics/OpenTelemetry article tells readers how to collect the built-in request activity without OpenTelemetry.Instrumentation.AspNetCore, but only the breaking-change article tells them how to opt out with the Microsoft.AspNetCore.Hosting.SuppressActivityOpenTelemetryData switch.

Gaps this report closes:

1. Add the opt-out switch to the OpenTelemetry tracing guidance where a reader configuring tracing will find it.
2. Keep the breaking-change article as the full behavior-change record and avoid duplicating its route/status-description details.

---

✅ Coverage status summary

Legend: ✅ already documented · ✏️ update needed · 🟣 could not determine

#	Feature element from What's New	Status	Where
1	ASP.NET Core's HTTP server activity source is named Microsoft.AspNetCore and should be registered with AddSource("Microsoft.AspNetCore")	✅	metrics/overview.md L199–L214
2	ASP.NET Core 11 emits required OpenTelemetry HTTP server semantic-convention attributes by default	✅	metrics/overview.md L188–L197 and breaking-changes/11/http-activity-otel-semconv.md L23–L30
3	No additional OpenTelemetry.Instrumentation.AspNetCore package is needed for HTTP server metrics and traces, although it can still add other telemetry	✅	metrics/overview.md L190–L197 and L217
4	Attribute examples include http.request.method, url.path, http.response.status_code, and server.address	✅	breaking-changes/11/http-activity-otel-semconv.md L27
5	Opt out by setting Microsoft.AspNetCore.Hosting.SuppressActivityOpenTelemetryData to true	✏️	1. Update — add a short note to metrics/overview.md L211–L219. The switch is documented only in the breaking-change article today (L50–L57).

---

🔢 Version applicability

Applies to: CURRENT-ONLY
Target moniker: >= aspnetcore-11.0
Earlier versions affected: None — default OpenTelemetry semantic-convention tags on the built-in hosting activity are new in ASP.NET Core 11.

Article	monikerRange	Moniker state
metrics/overview.md	'>= aspnetcore-8.0'	State C — the target insertion point is already inside the >= aspnetcore-11.0 zone (L188–L219), so insert directly before the zone closes at L219.
breaking-changes/11/http-activity-otel-semconv.md	no front-matter monikerRange; breaking-change article scoped by path/title	Context only — already documents the opt-out switch and broader behavior-change details. No edit proposed.

No tab groups appear in the target section of metrics/overview.md.

---

📋 Coverage gap summary

The docset already documents the core tracing path: register AddSource("Microsoft.AspNetCore"), rely on the built-in HTTP server activity source, and omit OpenTelemetry.Instrumentation.AspNetCore when only HTTP server metrics and traces are needed. The gap is discoverability for opting out. A developer reading metrics/overview.md to configure OpenTelemetry tracing won't learn about the AppContext switch unless they also find the dedicated breaking-change article.

Feature announced in What's New:

To collect the built-in tracing data, subscribe to the Microsoft.AspNetCore activity source in your OpenTelemetry configuration:
...
No additional instrumentation library (such as OpenTelemetry.Instrumentation.AspNetCore) is needed. The framework now directly populates semantic convention attributes on the request activity, such as http.request.method, url.path, http.response.status_code, and server.address.
If you don't want OpenTelemetry attributes added to the activity, you can turn it off by setting the Microsoft.AspNetCore.Hosting.SuppressActivityOpenTelemetryData AppContext switch to true.

Product source confirms the switch name and default: GetSuppressActivityOpenTelemetryData() returns false when the switch isn't set, and request activities are initialized/end-tagged only when SuppressActivityOpenTelemetryData is false.

Breaking change: Yes — behavioral change. The dedicated breaking-change article already covers previous behavior, new behavior, and mitigation.

---

📁 Affected files

Item	Path	Lines	Section
1.	metrics/overview.md	after 217	"View metrics in Grafana with OpenTelemetry and Prometheus"

Target article uids: metrics/overview

---

📝 Proposed changes

✏️ 1. Update — metrics/overview.md, add the opt-out switch inside the .NET 11 OpenTelemetry tracing note

Applies to: >= aspnetcore-11.0
Location: Line 217, immediately after the paragraph beginning "Alternatively, call AddAspNetCoreInstrumentation()".

Before (lines 211–219):

In the preceding example:

* `AddSource("Microsoft.AspNetCore")` registers ASP.NET Core's HTTP server activity source so the request activity is recorded.
* `AddSource("MyApp")` registers the app's own <xref:System.Diagnostics.ActivitySource>. Replace `MyApp` with the name your app uses.
* An exporter isn't shown. This example assumes an exporter is already configured in your tracing pipeline.

Alternatively, call `AddAspNetCoreInstrumentation()` from the [`OpenTelemetry.Instrumentation.AspNetCore`](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNetCore) package, which registers the source for you.

:::moniker-end

After:

In the preceding example:

* `AddSource("Microsoft.AspNetCore")` registers ASP.NET Core's HTTP server activity source so the request activity is recorded.
* `AddSource("MyApp")` registers the app's own <xref:System.Diagnostics.ActivitySource>. Replace `MyApp` with the name your app uses.
* An exporter isn't shown. This example assumes an exporter is already configured in your tracing pipeline.

Alternatively, call `AddAspNetCoreInstrumentation()` from the [`OpenTelemetry.Instrumentation.AspNetCore`](https://www.nuget.org/packages/OpenTelemetry.Instrumentation.AspNetCore) package, which registers the source for you.

To prevent ASP.NET Core from adding OpenTelemetry HTTP semantic-convention attributes to the built-in request activity, set the `Microsoft.AspNetCore.Hosting.SuppressActivityOpenTelemetryData` <xref:System.AppContext> switch to `true` early in app startup:

```csharp
AppContext.SetSwitch(
    "Microsoft.AspNetCore.Hosting.SuppressActivityOpenTelemetryData", true);
```

The switch only suppresses the OpenTelemetry attributes that ASP.NET Core adds to the activity. It doesn't disable activity creation, tracing propagation, or metrics collection.

:::moniker-end

Rationale: The breaking-change article is the right complete record for behavior changes, but this one-line mitigation belongs in metrics/overview.md because it's where developers configure OpenTelemetry tracing and decide whether to use the built-in instrumentation or the package.

---

✅ 2. Update — TOC

No TOC change required. The edit adds a paragraph to an existing article already present in the Metrics node.

---

✅ Action plan

1. Confirm the ✅ rows are already covered and don't need redundant edits.
2. Apply change 1 directly inside the existing >= aspnetcore-11.0 zone (State C); no moniker split is required.
3. Verify <xref:System.AppContext> resolves.
4. Build and confirm the switch note renders only under the .NET 11 selector.
5. Resolve any OpenPublishing.Build warnings.

---

⚠️ Review considerations

• Avoid duplicating the breaking-change article. metrics/overview.md should carry the opt-out switch for discoverability, but details about http.route substitution, Activity.StatusDescription, and error.type cardinality should remain in breaking-changes/11/http-activity-otel-semconv.md.
• Package wording is already nuanced. The metrics article correctly says the instrumentation package is optional for HTTP server metrics/traces but can still add other sources/meters. Keep that nuance if the note is edited.

---

🔗 References

• What's New section: Native OpenTelemetry tracing for ASP.NET Core
• Existing docset coverage: metrics/overview.md L188–L219
• Existing breaking-change coverage: breaking-changes/11/http-activity-otel-semconv.md L15–L57
• Product source: src/Hosting/Hosting/src/GenericHost/GenericWebHostBuilder.cs L74–L76 — registers ActivitySource("Microsoft.AspNetCore").
• Product source: src/Hosting/Hosting/src/Internal/HostingApplicationDiagnostics.cs L63–L70, L428–L458, and L539–L558 — default switch value and conditional tag population.
• Product source: src/Hosting/Hosting/src/Internal/HostingTelemetryHelpers.cs L14–L34 and HostingApplicationDiagnostics.cs L475–L532 — semantic-convention attribute names and request-start tags.