docs: modernize security and observability guidance

[ReubenBond]

Rewrites Orleans 10 TLS guidance to distinguish server-authenticated TLS from mTLS and adds production certificate, trust, rotation, and threat-model guidance. Rebuilds observability around verified OpenTelemetry configuration, signal interpretation, and incident runbooks, and makes dashboard security and operating costs prominent.

Microsoft Reviewers: Open in CodeFlow

[Copilot]

Pull request overview

This PR modernizes Orleans 10 documentation around transport security and observability by clarifying TLS vs mTLS behavior, adding operational guidance (trust, rotation, threat model), and restructuring observability content around OpenTelemetry configuration plus symptom-based runbooks and dashboard hardening.

Changes:

• Rewrites TLS documentation to distinguish server-authenticated TLS from mTLS and adds production trust/rotation guidance.
• Replaces static error-code tables with guidance to consult generated/runtime sources, plus adds new “signals” and “troubleshooting” operational pages.
• Adds/updates OpenTelemetry and dashboard security snippets and refreshes the observability and dashboard docs structure.

Show a summary per file

File	Description
docs/site/src/content/docs/host/transport-layer-security.md	Reworks TLS guidance, adds explicit server-auth vs mTLS model and production PKI considerations.
docs/site/src/content/docs/host/snippets/transport-layer-security/csharp/SiloExample/Program.cs	Updates TLS silo snippet to focused server-auth and mTLS examples.
docs/site/src/content/docs/host/snippets/transport-layer-security/csharp/ClientExample/Program.cs	Updates TLS client snippet to focused server-auth and mTLS examples.
docs/site/src/content/docs/host/monitoring/troubleshooting.md	Adds incident runbooks for common Orleans operational failures.
docs/site/src/content/docs/host/monitoring/snippets/observability/Program.cs	Adds consolidated OpenTelemetry configuration snippet for Orleans.
docs/site/src/content/docs/host/monitoring/snippets/observability/Observability.csproj	Adds snippet project to support the observability example.
docs/site/src/content/docs/host/monitoring/silo-error-code-monitoring.md	Replaces stale silo error-code table with references to generated/current sources and new workflows.
docs/site/src/content/docs/host/monitoring/signals.md	Adds symptom-first guidance for interpreting logs/metrics/traces and designing alerts.
docs/site/src/content/docs/host/monitoring/index.md	Rebuilds observability landing page around OpenTelemetry and links to new guidance.
docs/site/src/content/docs/host/monitoring/client-error-code-monitoring.md	Replaces stale client error-code table with references to generated/current sources and new workflows.
docs/site/src/content/docs/dashboard/snippets/secure-dashboard/SecureDashboard.csproj	Adds snippet project to support the secure dashboard example.
docs/site/src/content/docs/dashboard/snippets/secure-dashboard/Program.cs	Adds a secured dashboard mapping example using authz policy on the route group.
docs/site/src/content/docs/dashboard/index.md	Refocuses dashboard doc on security boundary, deployment patterns, and operational considerations.

Copilot's findings

Suppressed comments (2)

docs/site/src/content/docs/host/monitoring/snippets/observability/Program.cs:24

• AddOpenTelemetry() is called twice (once for configuring resource/metrics/traces and again to attach UseOtlpExporter). Keeping a single OpenTelemetryBuilder instance makes the intent clearer and avoids accidental duplication if the builder behavior changes.

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource
        .AddService(
            serviceName: "orders-silo",
            serviceVersion: typeof(Program).Assembly.GetName().Version?.ToString(),

docs/site/src/content/docs/host/monitoring/snippets/observability/Program.cs:49

• This conditional exporter setup calls AddOpenTelemetry() again, which can be confusing and may register exporter configuration separately from the earlier resource/metrics/tracing setup. If you keep the OpenTelemetryBuilder in a variable, apply UseOtlpExporter() to that same instance here.

if (!string.IsNullOrWhiteSpace(
    builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"]))
{
    builder.Services.AddOpenTelemetry().UseOtlpExporter();
}

• Files reviewed: 13/13 changed files
• Comments generated: 2

[Copilot]

Copilot's findings

Suppressed comments (2)

docs/site/src/content/docs/dashboard/snippets/secure-dashboard/SecureDashboard.csproj:14

• OpenTelemetry.Api is referenced but not used by this snippet project. Removing it avoids an unnecessary dependency and potential version drift in doc builds.

    <PackageReference Include="Microsoft.Orleans.Dashboard" Version="10.0.0" />
    <PackageReference Include="Microsoft.Orleans.Server" Version="10.0.0" />
    <PackageReference Include="OpenTelemetry.Api" Version="1.16.0" />
  </ItemGroup>

docs/site/src/content/docs/host/monitoring/signals.md:29

• The command shown here should be dotnet-counters (hyphenated). dotnet counters isn't a valid CLI command, so readers following this runbook will fail to run it.

dotnet counters monitor -n <ProcessName> --counters Microsoft.Orleans

• Files reviewed: 13/13 changed files
• Comments generated: 0 new

[Copilot]

Copilot's findings

Suppressed comments (4)

docs/site/src/content/docs/host/snippets/transport-layer-security/csharp/SiloExample/Program.cs:45

• ClientCertificateMode controls whether the local endpoint (acting as the TLS client) must have a local certificate configured; it doesn't make the silo require client certificates on inbound connections. To show mutual TLS, the setting to highlight on the silo is RemoteCertificateMode = RequireCertificate (which is what the server middleware uses to require a client certificate).

                    options.ClientCertificateMode =
                        RemoteCertificateMode.RequireCertificate;

docs/site/src/content/docs/host/transport-layer-security.md:87

• The production checklist recommends setting ClientCertificateMode = RequireCertificate to enforce mTLS, but requiring peer/client certificates on inbound connections is controlled by TlsOptions.RemoteCertificateMode on the silo. ClientCertificateMode is used by clients (and silo outbound connections) to fail fast when no local certificate is configured.

- Validate SANs, EKUs, chain trust, validity, and revocation behavior.
- Set `ClientCertificateMode` to `RequireCertificate` everywhere mTLS is required.
- Protect gateway and silo ports with network policy even when TLS is enabled.

docs/site/src/content/docs/host/snippets/transport-layer-security/csharp/SiloExample/Program.cs:23

• This "server-authenticated TLS" silo example doesn't set TlsOptions.RemoteCertificateMode. Since RemoteCertificateMode defaults to RequireCertificate, the silo will require client certificates on inbound connections, which contradicts the article text and will prevent the accompanying client example (no local certificate) from connecting.

This issue also appears on line 44 of the same file.

                .UseTls(serverCertificate, options =>
                {
                    options.OnAuthenticateAsClient = (_, sslOptions) =>
                    {
                        sslOptions.TargetHost = "orleans.example.net";

docs/site/src/content/docs/host/monitoring/signals.md:29

• The diagnostic tool command should be dotnet-counters ... (hyphenated), not dotnet counters .... As written, this command won't work with the standard dotnet-counters global tool.

dotnet counters monitor -n <ProcessName> --counters Microsoft.Orleans

• Files reviewed: 13/13 changed files
• Comments generated: 1

[Copilot]

Copilot's findings

Suppressed comments (3)

docs/site/src/content/docs/host/monitoring/silo-error-code-monitoring.md:12

• This sentence says the linked file is "for the Orleans version you deploy", but the URL points to blob/main, which can differ from a deployed release. Either link to a tag/branch which matches the deployed version, or adjust the wording so it doesn't imply version specificity.

For current definitions, use the generated <xref:Orleans.ErrorCode> API reference or the [error-code source for the Orleans version you deploy](https://github.com/dotnet/orleans/blob/main/src/Orleans.Core.Abstractions/Logging/ErrorCodes.cs). Alert on sustained service symptoms and use event IDs to narrow an investigation.

docs/site/src/content/docs/host/monitoring/client-error-code-monitoring.md:12

• This sentence says the linked file is "for the Orleans version you deploy", but the URL points to blob/main, which can differ from a deployed release. Either link to a tag/branch which matches the deployed version, or adjust the wording so it doesn't imply version specificity.

For current definitions, use the generated <xref:Orleans.ErrorCode> API reference or the [error-code source for the Orleans version you deploy](https://github.com/dotnet/orleans/blob/main/src/Orleans.Core.Abstractions/Logging/ErrorCodes.cs). Preserve structured `EventId`, category, exception, trace ID, and span ID fields in your log backend.

docs/site/src/content/docs/host/monitoring/signals.md:29

• The command uses dotnet counters, but the .NET diagnostics tool is typically invoked as dotnet-counters. Using the wrong command name will cause copy/paste failures for readers.

dotnet counters monitor -n <ProcessName> --counters Microsoft.Orleans

• Files reviewed: 13/13 changed files
• Comments generated: 0 new

[Copilot]

Copilot's findings

Suppressed comments (3)

docs/site/src/content/docs/host/monitoring/snippets/observability/Observability.csproj:1

• This project hosts an ASP.NET Core WebApplication (see Program.cs and the Microsoft.AspNetCore.App framework reference). Using Microsoft.NET.Sdk.Web is the standard SDK for web hosts and better aligns defaults/tooling with the app type. Consider switching the SDK to Microsoft.NET.Sdk.Web (and then re-evaluate whether the explicit FrameworkReference is still needed).

<Project Sdk="Microsoft.NET.Sdk">

docs/site/src/content/docs/dashboard/snippets/secure-dashboard/SecureDashboard.csproj:1

• This snippet project is an ASP.NET Core host (WebApplication + Microsoft.AspNetCore.App). Consider using Microsoft.NET.Sdk.Web to align with web-host defaults/tooling and simplify the project (for example, it may make the explicit framework reference unnecessary).

<Project Sdk="Microsoft.NET.Sdk">

docs/site/src/content/docs/dashboard/index.md:49

• In the 'Install and map the dashboard' section, this sample uses the DashboardOperators policy without defining it in the surrounding snippet/context. To keep the example self-contained, either show the corresponding AddAuthorization policy definition in this section or change the example to .RequireAuthorization() and reference the earlier 'Secure the dashboard' sample for policy-based authorization.

app.MapOrleansDashboard("/dashboard")
    .RequireAuthorization("DashboardOperators");

• Files reviewed: 13/13 changed files
• Comments generated: 4

[ReubenBond]

Addressed the latest review summary in 164370b: corrected the dotnet-counters command, clarified that �lob/main is active-development source rather than deployed-version source, switched both ASP.NET Core snippet projects to Microsoft.NET.Sdk.Web, and made the basic dashboard mapping use default authorization while pointing to the complete role-policy example. The four ClientCertificateMode inline findings are false positives: the property type is RemoteCertificateMode, and both TLS snippet projects compile. The failed CodeQL and samples jobs ended before checkout because GitHub returned Service Unavailable while resolving actions; this push will rerun CI.

[Copilot]

Copilot's findings

• Files reviewed: 13/13 changed files
• Comments generated: 0 new

[ReubenBond]

Final CI/review refresh at 164370b: Documentation is green (samples, site, snippets), CodeQL is green (actions, C#, JavaScript/TypeScript, upload), and all 57 .NET CI jobs pass. The initial Functional failures were unrelated flaky GrainDirectory/Placement tests and passed on rerun. All 7 review threads are resolved, no review drafts remain pending, and the latest Copilot review reports 0 new comments.