Adding docs for Application metadata and application enricher

docs/core/enrichment/application-enricher.md

@@ -0,0 +1,133 @@
+---
+title: Application enricher
+description: Learn how to use the application log enricher to add application-specific information to your telemetry in .NET.
+ms.date: 10/14/2025
+---
+
+# Application enricher
+
+The application log enricher augments telemetry logs with application-specific information such as service host details and application metadata. This enricher provides essential context about your application's deployment environment, version information, and service identity that helps with monitoring, debugging, and operational visibility.
+
+You can register the enrichers in an IoC container, and all registered enrichers are automatically picked up by respective telemetry logs, where they enrich the telemetry information.
+
+## Prerequisites
+
+To function properly, this enricher requires that [application metadata](xref:application-metadata) is configured and available. The application metadata provides the foundational information that the enricher uses to populate telemetry dimensions.
+
+## Install the package
+
+To get started, install the [📦 Microsoft.Extensions.Telemetry](https://www.nuget.org/packages/Microsoft.Extensions.Telemetry) NuGet package:
+
+### [.NET CLI](#tab/dotnet-cli)
+
+```dotnetcli
+dotnet add package Microsoft.Extensions.Telemetry
+```
+
+Or, if you're using .NET 10+ SDK:
+
+```dotnetcli
+dotnet package add Microsoft.Extensions.Telemetry
+```
+
+## Application log enricher
+
+The application log enricher provides application-specific enrichment. The log enricher specifically targets log telemetry and adds standardized dimensions that help identify and categorize log entries by service characteristics.
+
+### Step-by-step configuration
+
+Follow these steps to configure the application log enricher in your application:
+
+#### 1. Configure Application Metadata
+
+First, configure the [Application Metadata](xref:application-metadata) by calling the <xref:Microsoft.Extensions.Hosting.ApplicationMetadataHostBuilderExtensions.UseApplicationMetadata> method:
+
+```csharp
+var builder = Host.CreateDefaultBuilder();
+builder.UseApplicationMetadata()
+```
+
+This method automatically picks up values from the <xref:Microsoft.Extensions.Hosting.IHostEnvironment> and saves them to the default configuration section `ambientmetadata:application`.
+
+Alternatively, you can use this method <xref:Microsoft.Extensions.Configuration.ApplicationMetadataConfigurationBuilderExtensions.AddApplicationMetadata(Microsoft.Extensions.Configuration.IConfigurationBuilder,Microsoft.Extensions.Hosting.IHostEnvironment,System.String)>, which registers a configuration provider for application metadata by picking up the values from the <xref:Microsoft.Extensions.Hosting.IHostEnvironment> and adds it to the given configuration section name. Then you use <xref:Microsoft.Extensions.DependencyInjection.ApplicationMetadataServiceCollectionExtensions.AddApplicationMetadata(Microsoft.Extensions.DependencyInjection.IServiceCollection,Microsoft.Extensions.Configuration.IConfigurationSection)> method to register the metadata in the dependency injection container, which allow you to pass <xref:Microsoft.Extensions.Configuration.IConfigurationSection> separately:
+
+```csharp
+var hostBuilder = Host.CreateDefaultBuilder()
+    .ConfigureAppConfiguration((context, builder) =>
+        builder.AddApplicationMetadata(context.HostingEnvironment))
+    .ConfigureServices((context, services) =>
+        services.AddApplicationMetadata(context.Configuration.GetSection("ambientmetadata:application")));
+```
+
+#### 2. Provide additional configuration (optional)
+
+You can provide additional configuration via `appsettings.json`. There are two properties in the [Application Metadata](xref:application-metadata) that don't get values automatically: `BuildVersion` and `DeploymentRing`. If you want to use them, provide values manually:
+
+:::code language="json" source="snippets/servicelogenricher/appsettings.json" range="2-7":::
+
+#### 3. Register the service log enricher
+
+Register the log enricher into the dependency injection container using <xref:Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddServiceLogEnricher>:
+
+```csharp
+serviceCollection.AddServiceLogEnricher();
+```
+
+You can enable or disable individual options of the enricher using <xref:Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddServiceLogEnricher(Microsoft.Extensions.DependencyInjection.IServiceCollection,System.Action(Microsoft.Extensions.Diagnostics.Enrichment.ApplicationLogEnricherOptions))>:
+
+```csharp
+serviceCollection.AddServiceLogEnricher(options =>
+{
+    options.BuildVersion = true;
+    options.DeploymentRing = true;
+});
+```
+
+Alternatively, configure options using `appsettings.json`:
+
+:::code language="json" source="snippets/servicelogenricher/appsettings.json" range="9-12":::
+
+And apply the configuration using <xref:Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddServiceLogEnricher(Microsoft.Extensions.DependencyInjection.IServiceCollection,Microsoft.Extensions.Configuration.IConfigurationSection)>:
+
+```csharp
+var builder = Host.CreateDefaultBuilder(args);
+builder.ConfigureServices((context, services) =>
+{
+    services.AddServiceLogEnricher(context.Configuration.GetSection("applicationlogenricheroptions"));
+});
+```
+
+### `ApplicationLogEnricherOptions` Configuration options
+
+The service log enricher supports several configuration options through the <xref:Microsoft.Extensions.Diagnostics.Enrichment.ApplicationLogEnricherOptions> class:
+
+| Property | Default Value | Dimension Name | Description |
+|----------|---------------|----------------|-------------|
+| `EnvironmentName` | true | `deployment.environment` | Environment name from hosting environment or configuration |
+| `ApplicationName` | true | `service.name` | Application name from hosting environment or configuration |
+| `BuildVersion` | false | `service.version` | Build version from configuration |
+| `DeploymentRing` | false | `DeploymentRing` | Deployment ring from configuration |
+
+By default, the enricher includes `EnvironmentName` and `ApplicationName` in log entries. The `BuildVersion` and `DeploymentRing` properties are disabled by default and must be explicitly enabled if needed.
+
+### Complete example
+
+Here's a complete example showing how to set up the service log enricher:
+
+**appsettings.json:**
+
+:::code language="json" source="snippets/servicelogenricher/appsettings.json":::
+
+**Program.cs:**
+
+:::code language="csharp" source="snippets/servicelogenricher/Program.cs" :::
+
+### Enriched log output
+
+With the service log enricher configured, your log output will include service-specific dimensions:
+
+:::code language="csharp" source="snippets/servicelogenricher/output-full.json" highlight="9-11" :::
+
+## Next steps
+
+- Learn about [application metadata configuration](xref:application-metadata)

docs/core/enrichment/application-metadata.md

@@ -0,0 +1,94 @@
+---
+title: Application metada
+description: Learn how to use the application metadata to add service-specific information to your service in .NET.
+ms.date: 10/14/2025
+---
+
+# Application metadata
+
+The [Application metadata provider](xref:Microsoft.Extensions.Configuration.ApplicationMetadataConfigurationBuilderExtensions.AddApplicationMetadata*) supplies service runtime information for application-level ambient metadata such as the version, deployment ring, environment, and name. This information can be useful to enrich any telemetry your service is emitting.
+
+## Install the package
+
+To get started, install the [📦 Microsoft.Extensions.AmbientMetadata.Application](https://www.nuget.org/packages/Microsoft.Extensions.AmbientMetadata.Application) NuGet package:
+
+### [.NET CLI](#tab/dotnet-cli)
+
+```dotnetcli
+dotnet add package Microsoft.Extensions.AmbientMetadata.Application
+```
+
+Or, if you're using .NET 10+ SDK:
+
+```dotnetcli
+dotnet package add Microsoft.Extensions.AmbientMetadata.Application
+```
+
+### [PackageReference](#tab/package-reference)
+
+```xml
+<PackageReference Include="Microsoft.Extensions.AmbientMetadata.Application"
+                  Version="*" /> <!-- Adjust version -->
+```
+
+The following shows the information made available by the provider via <xref:Microsoft.Extensions.Configuration.IConfiguration>:
+
+| Key | Required? | Where the value comes from| Value Example | Description
+|-|-|-|-|
+| `ambientmetadata:application:applicationname` | yes | automatically from `IHostEnvironment` |`myApp` | The application name.
+| `ambientmetadata:application:environmentname` | yes | automatically from `IHostEnvironment` | `Production`, `Staging`, `Development` | The environment the application is deployed to.
+| `ambientmetadata:application:buildversion` | no | configure it in `IConfiguration` | `1.0.0-rc1` | The application's build version.
+| `ambientmetadata:application:deploymentring` | no | configure it in `IConfiguration` | `r0`, `public` | The deployment ring from where the application is running.
+
+## Example
+
+To use this provider, you need to use the <xref:Microsoft.Extensions.Hosting.ApplicationMetadataHostBuilderExtensions.UseApplicationMetadata> method,
+which populates `ApplicationName` and `EnvironmentName` values automatically from `IHostEnvironment`.
+Optionally, you can provide values for `BuildVersion` and `DeploymentRing` via the `appsettings.json` file.
+The complete example is as follows:
+
+`appsettings.json`:
+
+```json
+{
+  "ambientmetadata": {
+    "application": {
+      "buildversion": "1.0.0.0", // provide a build version.
+      "deploymentring": "deploymentRing" // provide a deployment ring value.
+    }
+  }
+}
+```
+
+```cs
+using var host = await new HostBuilder()
+    // ApplicationName and EnvironmentName will be imported from `IHostEnvironment` after calling the method below:
+    .UseApplicationMetadata()
+    .ConfigureAppConfiguration(builder =>
+    {
+      // BuildVersion and DeploymentRing will be imported from the "appsettings.json" file.
+        _ = builder.AddJsonFile("appsettings.json");
+    })
+    .Build()
+    .StartAsync();
+
+// work with metadata options
+var metadataOptions = host.Services.GetRequiredService<IOptions<ApplicationMetadata>>();
+var buildVersion = metadataOptions.Value.BuildVersion;
+```
+
+Alternatively, you can achieve the same result as above by doing this:
+
+```cs
+using var hostBuilder = new HostBuilder()
+    .ConfigureAppConfiguration((hostBuilderContext, configurationBuilder) => configurationBuilder
+      .AddApplicationMetadata(hostBuilderContext.HostingEnvironment)
+      .AddJsonFile("appsettings.json"))
+    .ConfigureServices((hostBuilderContext, serviceCollection) => serviceCollection
+      .AddApplicationMetadata(hostBuilderContext.Configuration.GetSection("ambientmetadata:application")))
+    .Build();
+
+// work with metadata options
+var metadataOptions = host.Services.GetRequiredService<IOptions<ApplicationMetadata>>();
+var buildVersion = metadataOptions.Value.BuildVersion;
+```

docs/core/enrichment/snippets/servicelogenricher/output-full.json

@@ -0,0 +1,14 @@
+{
+  "EventId": 0,
+  "LogLevel": "Information",
+  "Category": "Program",
+  "Message": "This is a sample log message",
+  "State": {
+    "Message": "This is a sample log message",
+    "service.name": "servicelogenricher",
+    "deployment.environment": "Production",
+    "DeploymentRing": "testring",
+    "service.version": "1.2.3",
+    "{OriginalFormat}": "This is a sample log message"
+  }
+}

docs/core/enrichment/snippets/servicelogenricher/servicelogenricher/Program.cs

@@ -0,0 +1,31 @@
+using System.Text.Json;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+
+var builder = Host.CreateDefaultBuilder(args);
+builder.UseApplicationMetadata();
+builder.ConfigureLogging(builder =>
+{
+    builder.EnableEnrichment();
+    builder.AddJsonConsole(op =>
+    {
+        op.JsonWriterOptions = new JsonWriterOptions
+        {
+            Indented = true
+        };
+    });
+});
+builder.ConfigureServices((context, services) =>
+{
+    services.AddServiceLogEnricher(context.Configuration.GetSection("applicationlogenricheroptions"));
+});
+
+var host = builder.Build();
+var logger = host.Services.GetRequiredService<ILogger<Program>>();
+
+logger.LogInformation("This is a sample log message");
+
+await host.RunAsync();
+
+

docs/core/enrichment/snippets/servicelogenricher/servicelogenricher/appsettings.json

@@ -0,0 +1,12 @@
+{
+    "AmbientMetadata": {
+        "Application": {
+            "DeploymentRing": "testring",
+            "BuildVersion": "1.2.3"
+        }
+    },
+    "ApplicationLogEnricherOptions": {
+        "BuildVersion": true,
+        "DeploymentRing": true
+    }
+}

docs/core/enrichment/snippets/servicelogenricher/servicelogenricher/servicelogenricher.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.9" />
+    <PackageReference Include="Microsoft.Extensions.Telemetry" Version="9.9.0" />
+    <PackageReference Include="Microsoft.Extensions.AmbientMetadata.Application" Version="9.9.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Update="appsettings.json">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>