Skip to content

Commit 1107d47

Browse files
mariamgergesmariamgerges
authored
Adding docs for Application metadata and application enricher (#49395)
* adding docs * fixes * fixing warning * fixed reference * fixes * fixes * fixes * missing new line * missing tick * fix * fix * fixing code blokcs * comments * fix sample
1 parent 771a9c9 commit 1107d47

File tree

7 files changed

+457
-0
lines changed

7 files changed

+457
-0
lines changed

‎docs/core/enrichment/application-log-enricher.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
title: Application log enricher
3+
description: Learn how to use the application log enricher to add application-specific information to your telemetry in .NET.
4+
ms.date: 10/14/2025
5+
---
6+
7+
# Application log enricher
8+
9+
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.
10+
11+
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.
12+
13+
## Prerequisites
14+
15+
To function properly, this enricher requires that [application metadata](application-metadata.md) is configured and available. The application metadata provides the foundational information that the enricher uses to populate telemetry dimensions.
16+
17+
## Install the package
18+
19+
To get started, install the [📦 Microsoft.Extensions.Telemetry](https://www.nuget.org/packages/Microsoft.Extensions.Telemetry) NuGet package:
20+
21+
### [.NET CLI](#tab/dotnet-cli)
22+
23+
```dotnetcli
24+
dotnet add package Microsoft.Extensions.Telemetry
25+
```
26+
27+
Or, if you're using .NET 10+ SDK:
28+
29+
```dotnetcli
30+
dotnet package add Microsoft.Extensions.Telemetry
31+
```
32+
33+
### [PackageReference](#tab/package-reference)
34+
35+
```xml
36+
<PackageReference Include="Microsoft.Extensions.Telemetry"
37+
Version="*" /> <!-- Adjust version -->
38+
```
39+
40+
---
41+
42+
## Application log enricher
43+
44+
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.
45+
46+
### Step-by-step configuration
47+
48+
Follow these steps to configure the application log enricher in your application:
49+
50+
#### 1. Configure Application Metadata
51+
52+
First, configure the [Application Metadata](application-metadata.md) by calling the <xref:Microsoft.Extensions.Hosting.ApplicationMetadataHostBuilderExtensions.UseApplicationMetadata%2A> methods:
53+
54+
```csharp
55+
var builder = Host.CreateApplicationBuilder(args);
56+
builder.UseApplicationMetadata()
57+
```
58+
59+
This method automatically picks up values from the <xref:Microsoft.Extensions.Hosting.IHostEnvironment> and saves them to the default configuration section `ambientmetadata:application`.
60+
61+
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:
62+
63+
```csharp
64+
var builder = Host.CreateApplicationBuilder(args)
65+
.ConfigureAppConfiguration(static (context, builder) =>
66+
builder.AddApplicationMetadata(context.HostingEnvironment));
67+
68+
builder.Services.AddApplicationMetadata(
69+
builder.Configuration.GetSection("ambientmetadata:application")));
70+
```
71+
72+
#### 2. Provide additional configuration (optional)
73+
74+
You can provide additional configuration via `appsettings.json`. There are two properties in the [Application Metadata](application-metadata.md) that don't get values automatically: `BuildVersion` and `DeploymentRing`. If you want to use them, provide values manually:
75+
76+
:::code language="json" source="snippets/servicelogenricher/appsettings.json" range="2-7":::
77+
78+
#### 3. Register the service log enricher
79+
80+
Register the log enricher into the dependency injection container using <xref:Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddServiceLogEnricher(Microsoft.Extensions.DependencyInjection.IServiceCollection)>:
81+
82+
```csharp
83+
serviceCollection.AddServiceLogEnricher();
84+
```
85+
86+
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})>:
87+
88+
```csharp
89+
serviceCollection.AddServiceLogEnricher(options =>
90+
{
91+
options.BuildVersion = true;
92+
options.DeploymentRing = true;
93+
});
94+
```
95+
96+
Alternatively, configure options using `appsettings.json`:
97+
98+
:::code language="json" source="snippets/servicelogenricher/appsettings.json" range="8-11":::
99+
100+
And apply the configuration using <xref:Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddServiceLogEnricher(Microsoft.Extensions.DependencyInjection.IServiceCollection,Microsoft.Extensions.Configuration.IConfigurationSection)>:
101+
102+
```csharp
103+
var builder = Host.CreateApplicationBuilder(args);
104+
builder.Services.AddServiceLogEnricher(builder.Configuration.GetSection("ApplicationLogEnricherOptions"));
105+
106+
```
107+
108+
### `ApplicationLogEnricherOptions` Configuration options
109+
110+
The service log enricher supports several configuration options through the <xref:Microsoft.Extensions.Diagnostics.Enrichment.ApplicationLogEnricherOptions> class:
111+
112+
| Property | Default Value | Dimension Name | Description |
113+
|----------|---------------|----------------|-------------|
114+
| `EnvironmentName` | true | `deployment.environment` | Environment name from hosting environment or configuration |
115+
| `ApplicationName` | true | `service.name` | Application name from hosting environment or configuration |
116+
| `BuildVersion` | false | `service.version` | Build version from configuration |
117+
| `DeploymentRing` | false | `DeploymentRing` | Deployment ring from configuration |
118+
119+
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.
120+
121+
### Complete example
122+
123+
Here's a complete example showing how to set up the service log enricher:
124+
125+
**appsettings.json:**
126+
127+
:::code language="json" source="snippets/servicelogenricher/appsettings.json":::
128+
129+
**Program.cs:**
130+
131+
:::code language="csharp" source="snippets/servicelogenricher/Program.cs" :::
132+
133+
### Enriched log output
134+
135+
With the service log enricher configured, your log output will include service-specific dimensions:
136+
137+
:::code language="json" source="snippets/servicelogenricher/output-full.json" highlight="8-11" :::
138+
139+
## Next steps
140+
141+
- Learn about [application metadata configuration](application-metadata.md)

‎docs/core/enrichment/application-metadata.md‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
---
2+
title: Application metadata
3+
description: Learn how to use the application metadata to add service-specific information to your service in .NET.
4+
ms.date: 10/14/2025
5+
---
6+
7+
# Application ambient metadata
8+
9+
The [`Microsoft.Extensions.AmbientMetadata.Application`](https://www.nuget.org/packages/Microsoft.Extensions.AmbientMetadata.Application) NuGet package provides functionality to capture and flow application-level ambient metadata throughout your application. This metadata includes information such as the application name, version, deployment environment, and deployment ring, which is valuable for enriching telemetry, troubleshooting, and analysis.
10+
11+
## Why use application metadata
12+
13+
Application metadata provides essential context about your running application that can enhance observability:
14+
15+
- **Telemetry enrichment**: Automatically add application details to logs, metrics, and traces.
16+
- **Troubleshooting**: Quickly identify which version of your application is experiencing issues.
17+
- **Environment identification**: Distinguish between different environments in your telemetry.
18+
- **Deployment tracking**: Track issues across different deployment rings or regions.
19+
- **Consistent metadata**: Ensure all components in your application use the same metadata values.
20+
21+
## Install the package
22+
23+
To get started, install the [📦 Microsoft.Extensions.AmbientMetadata.Application](https://www.nuget.org/packages/Microsoft.Extensions.AmbientMetadata.Application) NuGet package:
24+
25+
### [.NET CLI](#tab/dotnet-cli)
26+
27+
```dotnetcli
28+
dotnet add package Microsoft.Extensions.AmbientMetadata.Application
29+
```
30+
31+
Or, if you're using .NET 10+ SDK:
32+
33+
```dotnetcli
34+
dotnet package add Microsoft.Extensions.AmbientMetadata.Application
35+
```
36+
37+
### [PackageReference](#tab/package-reference)
38+
39+
```xml
40+
<PackageReference Include="Microsoft.Extensions.AmbientMetadata.Application"
41+
Version="*" /> <!-- Adjust version -->
42+
```
43+
44+
---
45+
46+
## Configure application metadata
47+
48+
Application metadata can be configured through your application's configuration system. The package looks for metadata under the `ambientmetadata:application` configuration section by default.
49+
50+
### Configure with appsettings.json
51+
52+
Add the application metadata to your `appsettings.json` file:
53+
54+
```json
55+
{
56+
"ambientmetadata": {
57+
"application": {
58+
"ApplicationName": "MyWebApi",
59+
"BuildVersion": "1.0.0",
60+
"DeploymentRing": "Production",
61+
"EnvironmentName": "Production"
62+
}
63+
}
64+
}
65+
```
66+
67+
### Configure with IHostBuilder
68+
69+
Use the <xref:Microsoft.Extensions.Hosting.ApplicationMetadataHostBuilderExtensions.UseApplicationMetadata%2A> extensions method to register application metadata, which populates `ApplicationName` and `EnvironmentName` values automatically from `IHostEnvironment`.
70+
Optionally, you can provide values for `BuildVersion` and `DeploymentRing` via the `appsettings.json` file.
71+
72+
The following table shows the metadata made available by the provider via <xref:Microsoft.Extensions.Configuration.IConfiguration>:
73+
74+
| Key | Required? | Where the value comes from| Value Example | Description|
75+
|-|-|-|-|-|
76+
| `ambientmetadata:application:applicationname` | yes | automatically from `IHostEnvironment` |`myApp` | The application name.|
77+
| `ambientmetadata:application:environmentname` | yes | automatically from `IHostEnvironment` | `Production`, `Development`| The environment the application is deployed to.|
78+
| `ambientmetadata:application:buildversion` | no | configure it in `IConfiguration` | `1.0.0-rc1` | The application's build version.|
79+
| `ambientmetadata:application:deploymentring` | no | configure it in `IConfiguration` | `r0`, `public` | The deployment ring from where the application is running.|
80+
81+
```csharp
82+
var builder = Host.CreateDefaultBuilder(args)
83+
// ApplicationName and EnvironmentName will be imported from `IHostEnvironment`
84+
// BuildVersion and DeploymentRing will be imported from the "appsettings.json" file.
85+
builder.UseApplicationMetadata();
86+
87+
var host = builder.Build();
88+
await host.StartAsync();
89+
90+
var metadataOptions = host.Services.GetRequiredService<IOptions<ApplicationMetadata>>();
91+
var buildVersion = metadataOptions.Value.BuildVersion;
92+
```
93+
94+
Alternatively, you can achieve the same result as above by doing this:
95+
96+
```csharp
97+
var builder = Host.CreateApplicationBuilder()
98+
.ConfigureAppConfiguration(static (context, builder) =>
99+
builder.AddApplicationMetadata(context.HostingEnvironment));
100+
builder.Services.AddApplicationMetadata(
101+
builder.Configuration.GetSection("ambientmetadata:application")));
102+
var host = builder.Build();
103+
104+
var metadataOptions = host.Services.GetRequiredService<IOptions<ApplicationMetadata>>();
105+
var buildVersion = metadataOptions.Value.BuildVersion;
106+
```
107+
108+
Your `appsettings.json` can have a section as follows :
109+
110+
:::code language="json" source="snippets/servicelogenricher/appsettings.json" range="2-7":::
111+
112+
### Configure with IHostApplicationBuilder
113+
114+
For applications using <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder>:
115+
116+
```csharp
117+
var builder = Host.CreateApplicationBuilder(args)
118+
// ApplicationName and EnvironmentName will be imported from `IHostEnvironment`
119+
// BuildVersion and DeploymentRing will be imported from the "appsettings.json" file.
120+
builder.UseApplicationMetadata();
121+
122+
var host = builder.Build();
123+
await host.StartAsync();
124+
125+
var metadataOptions = host.Services.GetRequiredService<IOptions<ApplicationMetadata>>();
126+
var buildVersion = metadataOptions.Value.BuildVersion;
127+
```
128+
129+
Your `appsettings.json` can have a section as follows :
130+
131+
:::code language="json" source="snippets/servicelogenricher/appsettings.json" range="2-7":::
132+
133+
## Access application metadata
134+
135+
Once configured, you can inject and use the <xref:Microsoft.Extensions.AmbientMetadata.ApplicationMetadata> type:
136+
137+
```csharp
138+
using Microsoft.Extensions.AmbientMetadata;
139+
using Microsoft.Extensions.Configuration;
140+
using Microsoft.Extensions.DependencyInjection;
141+
using Microsoft.Extensions.Hosting;
142+
using Microsoft.Extensions.Options;
143+
144+
var builder = Host.CreateApplicationBuilder(args);
145+
builder.UseApplicationMetadata();
146+
147+
var host = builder.Build();
148+
149+
var metadata = host.Services.GetRequiredService<IOptions<ApplicationMetadata>>().Value;
150+
Console.WriteLine($"Application: {metadata.ApplicationName}");
151+
Console.WriteLine($"Version: {metadata.BuildVersion}");
152+
Console.WriteLine($"Environment: {metadata.EnvironmentName}");
153+
Console.WriteLine($"Deployment Ring: {metadata.DeploymentRing}");
154+
await host.RunAsync();
155+
```
156+
157+
## ApplicationMetadata properties
158+
159+
The <xref:Microsoft.Extensions.AmbientMetadata.ApplicationMetadata> class includes the following properties:
160+
161+
| Property | Description |
162+
|----------|-------------|
163+
| `ApplicationName` | The name of the application. |
164+
| `BuildVersion` | The version of the application build. |
165+
| `DeploymentRing` | The deployment ring or stage (for example, Canary, Production). |
166+
| `EnvironmentName` | The environment where the application is running (for example, Development, Staging, Production). |
167+
168+
## Use with logging
169+
170+
Application metadata is particularly useful for enriching log messages:
171+
172+
```csharp
173+
using Microsoft.Extensions.AmbientMetadata;
174+
using Microsoft.Extensions.DependencyInjection;
175+
using Microsoft.Extensions.Hosting;
176+
using Microsoft.Extensions.Logging;
177+
using Microsoft.Extensions.Options;
178+
179+
var builder = Host.CreateApplicationBuilder(args);
180+
181+
builder.UseApplicationMetadata();
182+
builder.Services.AddSingleton<LoggingService>();
183+
184+
var host = builder.Build();
185+
186+
var loggingService = host.Services.GetRequiredService<LoggingService>();
187+
loggingService.LogWithMetadata();
188+
189+
await host.RunAsync();
190+
191+
public class LoggingService(
192+
ILogger<LoggingService> logger,
193+
IOptions<ApplicationMetadata> metadata)
194+
{
195+
private readonly ILogger<LoggingService> _logger = logger;
196+
private readonly ApplicationMetadata _metadata = metadata.Value;
197+
198+
public void LogWithMetadata()
199+
{
200+
_logger.LogInformation(
201+
"Processing request in {ApplicationName} v{Version} ({Environment})",
202+
_metadata.ApplicationName,
203+
_metadata.BuildVersion,
204+
_metadata.EnvironmentName);
205+
}
206+
}
207+
```
208+
209+
## Custom configuration section
210+
211+
If you prefer to use a different configuration section name, specify it when calling <xref:Microsoft.Extensions.Hosting.ApplicationMetadataHostBuilderExtensions.UseApplicationMetadata``1(``0,System.String)>:
212+
213+
```csharp
214+
using Microsoft.Extensions.Hosting;
215+
216+
var builder = Host.CreateApplicationBuilder(args);
217+
218+
// Use custom configuration section
219+
builder.UseApplicationMetadata("myapp:metadata");
220+
221+
var host = builder.Build();
222+
223+
await host.RunAsync();
224+
```
225+
226+
With this configuration, your settings would look like:
227+
228+
```json
229+
{
230+
"myapp": {
231+
"metadata": {
232+
"ApplicationName": "MyWebApi", // Your ApplicationName will be imported from `IHostEnvironment`
233+
"BuildVersion": "1.0.0",
234+
"DeploymentRing": "Production",
235+
"EnvironmentName": "Production" // Your EnvironmentName will be imported from `IHostEnvironment`
236+
}
237+
}
238+
}
239+
```

0 commit comments

Comments
 (0)