Merge main into live

docs/core/diagnostics/observability-with-otel.md

@@ -9,7 +9,7 @@ ms.topic: conceptual
 
 When you run an application, you want to know how well the app is performing and to detect potential problems before they become larger. You can do this by emitting telemetry data such as logs or metrics from your app, then monitoring and analyzing that data.
 
-## What is observability
+## What is observability?
 
 Observability in the context of a distributed system is the ability to monitor and analyze telemetry about the state of each component, to be able to observe changes in performance, and to diagnose why those changes occur. Unlike debugging, which is invasive and can affect the operation of the application, observability is intended to be transparent to the primary operation and have a small enough performance impact that it can be used continuously.
 
@@ -35,7 +35,7 @@ There are a few different ways to achieve observability in .NET applications:
 - Out-of-process using [EventPipe](./eventpipe.md). Tools such as [dotnet-monitor](./dotnet-monitor.md) can listen to logs and metrics and then process them without affecting any code.
 - [Using a startup hook](https://github.com/dotnet/runtime/blob/main/docs/design/features/host-startup-hook.md), assemblies can be injected into the process that can then collect instrumentation. An example of this approach is [OpenTelemetry .NET Automatic Instrumentation](https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/main/docs/README.md).
 
-## What is OpenTelemetry
+## What is OpenTelemetry?
 
 [OpenTelemetry](https://opentelemetry.io/) (OTel) is a cross-platform, open standard for collecting and emitting telemetry data. OpenTelemetry includes:
 
@@ -73,18 +73,18 @@ OpenTelemetry in .NET is implemented as a series of NuGet packages that form a c
 The following table describes the main packages.
 
 | Package Name | Description |
-| --- |  ---|
+|--------------|-------------|
 | [OpenTelemetry](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry/README.md) | Main library that provides the core OTEL functionality |
-| [OpenTelemetry.Instrumentation.AspNetCore](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore/README.md) | Instrumentation for ASP.NET Core and Kestrel |
-| [OpenTelemetry.Instrumentation.GrpcNetClient](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Instrumentation.GrpcNetClient/README.md) | Instrumentation for gRPC Client for tracking outbound gRPC calls  |
-| [OpenTelemetry.Instrumentation.Http](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Instrumentation.Http/README.md) | Instrumentation for `HttpClient` and `HttpWebRequest` to track outbound HTTP calls |
-| [OpenTelemetry.Instrumentation.SqlClient](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Instrumentation.SqlClient/README.md) | Instrumentation for `SqlClient` used to trace database operations |
+| [OpenTelemetry.Instrumentation.AspNetCore](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore/README.md) | Instrumentation for ASP.NET Core and Kestrel |
+| [OpenTelemetry.Instrumentation.GrpcNetClient](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.GrpcNetClient/README.md) | Instrumentation for gRPC Client for tracking outbound gRPC calls  |
+| [OpenTelemetry.Instrumentation.Http](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.Http/README.md) | Instrumentation for `HttpClient` and `HttpWebRequest` to track outbound HTTP calls |
+| [OpenTelemetry.Instrumentation.SqlClient](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.SqlClient/README.md) | Instrumentation for `SqlClient` used to trace database operations |
 | [OpenTelemetry.Exporter.Console](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.Console/README.md) |  Exporter for the console, commonly used to diagnose what telemetry is being exported |
 | [OpenTelemetry.Exporter.OpenTelemetryProtocol](https://github.com/open-telemetry/opentelemetry-dotnet/tree/main/src/OpenTelemetry.Exporter.OpenTelemetryProtocol/README.md) |  Exporter using the OTLP protocol |
 | [OpenTelemetry.Exporter.Prometheus.AspNetCore](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Exporter.Prometheus.AspNetCore/README.md) |  Exporter for Prometheus implemented using an ASP.NET Core endpoint |
 | [OpenTelemetry.Exporter.Zipkin](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Exporter.Zipkin/README.md) |  Exporter for Zipkin tracing |
 
-## Example: Use Prometheus, Grafana and Jaeger
+## Example: Use Prometheus, Grafana, and Jaeger
 
 This example uses Prometheus for metrics collection, Grafana for creating a dashboard, and Jaeger to show distributed tracing.
 
@@ -318,12 +318,12 @@ With Grafana, you can design sophisticated dashboards that will track any number
 
 Each metric in .NET can have additional dimensions, which are key-value pairs that can be used to partition the data. The ASP.NET metrics all feature a number of dimensions applicable to the counter. For example, the `current-requests` counter from `Microsoft.AspNetCore.Hosting` has the following dimensions:
 
-| Attribute | Type | Description | Examples | Presence |
-| --- | --- | --- | --- | --- |
-| `method` | `string` | HTTP request method. | `GET`; `POST`; `HEAD` | Always |
-| `scheme` | `string` | The URI scheme identifying the used protocol. | `http`; `https` | Always |
-| `host`| `string` | Name of the local HTTP server that received the request. | `localhost` | Always |
-| `port` | `int` | Port of the local HTTP server that received the request. | `8080` | Added if not default (80 for http or 443 for https) |
+| Attribute | Type     | Description                                              | Examples              | Presence |
+|-----------|----------|----------------------------------------------------------|-----------------------|----------|
+| `method`  | `string` | HTTP request method.                                     | `GET`; `POST`; `HEAD` | Always   |
+| `scheme`  | `string` | The URI scheme identifying the used protocol.            | `http`; `https`       | Always   |
+| `host`    | `string` | Name of the local HTTP server that received the request. | `localhost`           | Always   |
+| `port`    | `int`    | Port of the local HTTP server that received the request. | `8080`                | Added if not default (80 for http or 443 for https) |
 
 The graphs in Grafana are usually partitioned based on each unique combination of dimensions. The dimensions can be used in the Grafana queries to filter or aggregate the data. For example, if you graph `current_requests`, you'll see values partitioned based on each combination of dimensions. To filter based only on the host, add an operation of `Sum` and use `host` as the label value.
 

docs/core/diagnostics/specialized-diagnostics-overview.md

@@ -41,7 +41,7 @@ The .NET runtime exposes a service endpoint that allows other processes to send
 
 ## DiagnosticSource & DiagnosticListener
 
-[DiagnosticSource](./diagnosticsource-diagnosticlistener.md) is a module that allows code to be instrumented for production-time logging of rich data payloads for consumption within the process that was instrumented. At run time, consumers can dynamically discover data sources and subscribe to the ones of interest. <xref:System.Diagnostics.DiagnosticSource?displayProperty=nameWithType> was designed to allow in-process tools to access rich data, such as by [OpenTelemetry instrumentation libraries](https://github.com/open-telemetry/opentelemetry-dotnet/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore/README.md). DiagnosticSource data can also be egressed via EventPipe, which enables rich diagnostic data to be collected by dedicated tools. |
+[DiagnosticSource](./diagnosticsource-diagnosticlistener.md) is a module that allows code to be instrumented for production-time logging of rich data payloads for consumption within the process that was instrumented. At run time, consumers can dynamically discover data sources and subscribe to the ones of interest. <xref:System.Diagnostics.DiagnosticSource?displayProperty=nameWithType> was designed to allow in-process tools to access rich data, such as by [OpenTelemetry instrumentation libraries](https://github.com/open-telemetry/opentelemetry-dotnet-contrib/blob/main/src/OpenTelemetry.Instrumentation.AspNetCore/README.md). DiagnosticSource data can also be egressed via EventPipe, which enables rich diagnostic data to be collected by dedicated tools. |
 
 ## See also
 

docs/core/install/includes/supported-versions.md

@@ -0,0 +1,15 @@
+---
+author: adegeo
+ms.author: adegeo
+ms.date: 05/22/2024
+ms.topic: include
+---
+
+Microsoft publishes .NET under two different support policies, Long Term Support (LTS) and Standard Term Support (STS). The quality of all releases is the same. The only difference is the length of support. LTS releases get free support and patches for three years. STS releases get free support and patches for 18 months. For more information, see [.NET Support Policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core).
+
+The versions of .NET that are currently supported by Microsoft are:
+
+- 8.0 (LTS)—Support ends **November 10, 2026**.
+- 6.0 (LTS)—Support ends **November 12, 2024**.
+
+Other entities that build and release .NET might introduce different support policies. Be sure to check with them to understand how .NET is supported.

docs/core/install/linux-snap-runtime.md

@@ -0,0 +1,115 @@
+---
+title: Install .NET Runtime on Linux with Snap
+description: Learn about how to install the .NET Runtime snap package. Canonical maintains and supports .NET-related snap packages.
+author: adegeo
+ms.author: adegeo
+ms.date: 05/22/2024
+ms.topic: install-set-up-deploy
+ms.custom: linux-related-content
+#customer intent: As a Linux user, I want to install .NET Runtime through Snap.
+---
+
+# Install .NET Runtime with Snap
+
+This article describes how to install the .NET Runtime snap package. .NET Runtime snap packages are provided by and maintained by Canonical. Snaps are a great alternative to the package manager built into your Linux distribution.
+
+A snap is a bundle of an app and its dependencies that works across many different Linux distributions. Snaps are discoverable and installable from the Snap Store. For more information about Snap, see [Getting started with Snap](https://snapcraft.io/docs/getting-started).
+
+> [!CAUTION]
+> Snap installations of .NET may have problems running [.NET tools](../tools/global-tools.md). If you wish to use .NET tools, we recommend that you install .NET using the [`dotnet-install` script](linux-scripted-manual.md#scripted-install) or the package manager for the particular Linux distribution.
+
+## Prerequisites
+
+- Linux distribution that supports snap.
+- `snapd` the snap daemon.
+
+Your Linux distribution might already include snap. Try running `snap` from a terminal to see if the command works. For a list of supported Linux distributions, and instructions on how to install snap, see [Installing `snapd`](https://snapcraft.io/docs/installing-snapd).
+
+## .NET releases
+
+[!INCLUDE [supported-versions](includes/supported-versions.md)]
+
+## 1. Install the runtime
+
+The following steps install the .NET 8 runtime snap package:
+
+01. Open a terminal.
+01. Use `snap install` to install the .NET Runtime snap package. For example, the following command installs the .NET 8 runtime.
+
+    ```bash
+    sudo snap install dotnet-runtime-80
+    ```
+
+Each .NET Runtime is published as an individual snap package. The following table lists the packages:
+
+| .NET version                                      | Snap package        | .NET version supported by Microsoft |
+|---------------------------------------------------|---------------------|-----|
+| [8 (STS)](https://snapcraft.io/dotnet-runtime-80) | `dotnet-runtime-80` | Yes |
+| [7 (STS)](https://snapcraft.io/dotnet-runtime-70) | `dotnet-runtime-70` | No  |
+| [6 (LTS)](https://snapcraft.io/dotnet-runtime-60) | `dotnet-runtime-60` | Yes |
+| [5](https://snapcraft.io/dotnet-runtime-50)       | `dotnet-runtime-50` | No  |
+| [3.1](https://snapcraft.io/dotnet-runtime-31)     | `dotnet-runtime-31` | No  |
+| [3.0](https://snapcraft.io/dotnet-runtime-30)     | `dotnet-runtime-30` | No  |
+| [2.2](https://snapcraft.io/dotnet-runtime-22)     | `dotnet-runtime-22` | No  |
+| [2.1](https://snapcraft.io/dotnet-runtime-21)     | `dotnet-runtime-21` | No  |
+
+## 2. Enable the dotnet command
+
+When the .NET runtime snap package is installed, the `dotnet` command isn't automatically configured. Use the `snap alias` command to use the `dotnet` command from the terminal. The command is formatted as: `sudo snap alias {package}.{command} {alias}`. The following example maps the `dotnet` command:
+
+```bash
+sudo snap alias dotnet-runtime-80.dotnet dotnet
+```
+
+## 3. Export the install location
+
+The `DOTNET_ROOT` environment variable is often used by tools to determine where .NET is installed. When .NET is installed through Snap, this environment variable isn't configured. You should configure the *DOTNET_ROOT* environment variable in your profile. The path to the snap uses the following format: `/snap/{package}/current`. For example, if you installed the `dotnet-runtime-80` snap, use the following command to set the environment variable to where .NET is located:
+
+```bash
+export DOTNET_ROOT=/snap/dotnet-runtime-80/current
+```
+
+### Export the environment variable permanently
+
+The preceding `export` command only sets the environment variable for the terminal session in which it was run.
+
+You can edit your shell profile to permanently add the commands. There are a number of different shells available for Linux and each has a different profile. For example:
+
+- **Bash Shell**: *~/.bash_profile*, *~/.bashrc*
+- **Korn Shell**: *~/.kshrc* or *.profile*
+- **Z Shell**: *~/.zshrc* or *.zprofile*
+
+Edit the appropriate source file for your shell and add `export DOTNET_ROOT=/snap/dotnet-runtime-80/current`.
+
+## Troubleshooting
+
+- [The dotnet terminal command doesn't work](#the-dotnet-terminal-command-doesnt-work)
+- [Can't install Snap on WSL2](#cant-install-snap-on-wsl2)
+
+### The dotnet terminal command doesn't work
+
+Snap packages can map an alias to a command provided by the package. The .NET Runtime snap packages don't automatically lias the `dotnet` command. To alias the `dotnet` command to the snap package, use the following command:
+
+```bash
+sudo snap alias dotnet-runtime-80.dotnet dotnet
+```
+
+Substitute `dotnet-runtime-80` with the name of your runtime package.
+
+### Can't install Snap on WSL2
+
+`systemd` must be enabled on the WSL2 instance before Snap can be installed.
+
+1. Open `/etc/wsl.conf` in a text editor of your choice.
+1. Paste in the following configuration:
+
+   ```ini
+   [boot]
+   systemd=true
+   ```
+
+1. Save the file and restart the WSL2 instance through PowerShell. Use the `wsl.exe --shutdown` command.
+
+## Related content
+
+- [How to enable TAB completion for the .NET CLI.](../tools/enable-tab-autocomplete.md)