Skip to content

Commit d435918

Browse files
mariamgergesmariamgerges
committed
adding docs
1 parent 9e06dd5 commit d435918

File tree

6 files changed

+308
-0
lines changed

6 files changed

+308
-0
lines changed

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

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
title: Application 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 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](xref:application-metadata) 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+
## Application log enricher
34+
35+
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.
36+
37+
### Step-by-step configuration
38+
39+
Follow these steps to configure the application log enricher in your application:
40+
41+
#### 1. Configure Application Metadata
42+
43+
First, configure the [Application Metadata](xref:application-metadata) by calling the <xref:Microsoft.Extensions.Hosting.ApplicationMetadataHostBuilderExtensions.UseApplicationMetadata> method:
44+
45+
```csharp
46+
var builder = Host.CreateDefaultBuilder();
47+
builder.UseApplicationMetadata()
48+
```
49+
50+
This method automatically picks up values from the <xref:Microsoft.Extensions.Hosting.IHostEnvironment> and saves them to the default configuration section `ambientmetadata:application`.
51+
52+
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:
53+
54+
```csharp
55+
var hostBuilder = Host.CreateDefaultBuilder()
56+
.ConfigureAppConfiguration((context, builder) =>
57+
builder.AddApplicationMetadata(context.HostingEnvironment))
58+
.ConfigureServices((context, services) =>
59+
services.AddApplicationMetadata(context.Configuration.GetSection("ambientmetadata:application")));
60+
```
61+
62+
#### 2. Provide additional configuration (optional)
63+
64+
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:
65+
66+
:::code language="json" source="snippets/servicelogenricher/appsettings.json" range="2-7":::
67+
68+
#### 3. Register the service log enricher
69+
70+
Register the log enricher into the dependency injection container using <xref:Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddServiceLogEnricher>:
71+
72+
```csharp
73+
serviceCollection.AddServiceLogEnricher();
74+
```
75+
76+
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))>:
77+
78+
```csharp
79+
serviceCollection.AddServiceLogEnricher(options =>
80+
{
81+
options.BuildVersion = true;
82+
options.DeploymentRing = true;
83+
});
84+
```
85+
86+
Alternatively, configure options using `appsettings.json`:
87+
88+
:::code language="json" source="snippets/servicelogenricher/appsettings.json" range="9-12":::
89+
90+
And apply the configuration using <xref:Microsoft.Extensions.DependencyInjection.ApplicationEnricherServiceCollectionExtensions.AddServiceLogEnricher(Microsoft.Extensions.DependencyInjection.IServiceCollection,Microsoft.Extensions.Configuration.IConfigurationSection)>:
91+
92+
```csharp
93+
var builder = Host.CreateDefaultBuilder(args);
94+
builder.ConfigureServices((context, services) =>
95+
{
96+
services.AddServiceLogEnricher(context.Configuration.GetSection("applicationlogenricheroptions"));
97+
});
98+
```
99+
100+
### `ApplicationLogEnricherOptions` Configuration options
101+
102+
The service log enricher supports several configuration options through the <xref:Microsoft.Extensions.Diagnostics.Enrichment.ApplicationLogEnricherOptions> class:
103+
104+
| Property | Default Value | Dimension Name | Description |
105+
|----------|---------------|----------------|-------------|
106+
| `EnvironmentName` | true | `deployment.environment` | Environment name from hosting environment or configuration |
107+
| `ApplicationName` | true | `service.name` | Application name from hosting environment or configuration |
108+
| `BuildVersion` | false | `service.version` | Build version from configuration |
109+
| `DeploymentRing` | false | `DeploymentRing` | Deployment ring from configuration |
110+
111+
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.
112+
113+
### Complete example
114+
115+
Here's a complete example showing how to set up the service log enricher:
116+
117+
**appsettings.json:**
118+
119+
:::code language="json" source="snippets/servicelogenricher/appsettings.json":::
120+
121+
**Program.cs:**
122+
123+
:::code language="csharp" source="snippets/servicelogenricher/Program.cs" :::
124+
125+
### Enriched log output
126+
127+
With the service log enricher configured, your log output will include service-specific dimensions:
128+
129+
:::code language="csharp" source="snippets/servicelogenricher/output-full.json" highlight="9-11" :::
130+
131+
## Next steps
132+
133+
- Learn about [application metadata configuration](xref:application-metadata)

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

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: Application metada
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 metadata
8+
9+
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.
10+
11+
## Install the package
12+
13+
To get started, install the [📦 Microsoft.Extensions.AmbientMetadata.Application](https://www.nuget.org/packages/Microsoft.Extensions.AmbientMetadata.Application) NuGet package:
14+
15+
### [.NET CLI](#tab/dotnet-cli)
16+
17+
```dotnetcli
18+
dotnet add package Microsoft.Extensions.AmbientMetadata.Application
19+
```
20+
21+
Or, if you're using .NET 10+ SDK:
22+
23+
```dotnetcli
24+
dotnet package add Microsoft.Extensions.AmbientMetadata.Application
25+
```
26+
27+
### [PackageReference](#tab/package-reference)
28+
29+
```xml
30+
<PackageReference Include="Microsoft.Extensions.AmbientMetadata.Application"
31+
Version="*" /> <!-- Adjust version -->
32+
```
33+
34+
The following shows the information made available by the provider via <xref:Microsoft.Extensions.Configuration.IConfiguration>:
35+
36+
| Key | Required? | Where the value comes from| Value Example | Description
37+
|-|-|-|-|
38+
| `ambientmetadata:application:applicationname` | yes | automatically from `IHostEnvironment` |`myApp` | The application name.
39+
| `ambientmetadata:application:environmentname` | yes | automatically from `IHostEnvironment` | `Production`, `Staging`, `Development` | The environment the application is deployed to.
40+
| `ambientmetadata:application:buildversion` | no | configure it in `IConfiguration` | `1.0.0-rc1` | The application's build version.
41+
| `ambientmetadata:application:deploymentring` | no | configure it in `IConfiguration` | `r0`, `public` | The deployment ring from where the application is running.
42+
43+
## Example
44+
45+
To use this provider, you need to use the <xref:Microsoft.Extensions.Hosting.ApplicationMetadataHostBuilderExtensions.UseApplicationMetadata> method,
46+
which populates `ApplicationName` and `EnvironmentName` values automatically from `IHostEnvironment`.
47+
Optionally, you can provide values for `BuildVersion` and `DeploymentRing` via the `appsettings.json` file.
48+
The complete example is as follows:
49+
50+
`appsettings.json`:
51+
52+
```json
53+
{
54+
"ambientmetadata": {
55+
"application": {
56+
"buildversion": "1.0.0.0", // provide a build version.
57+
"deploymentring": "deploymentRing" // provide a deployment ring value.
58+
}
59+
}
60+
}
61+
```
62+
63+
```cs
64+
using var host = await new HostBuilder()
65+
// ApplicationName and EnvironmentName will be imported from `IHostEnvironment` after calling the method below:
66+
.UseApplicationMetadata()
67+
.ConfigureAppConfiguration(builder =>
68+
{
69+
// BuildVersion and DeploymentRing will be imported from the "appsettings.json" file.
70+
_ = builder.AddJsonFile("appsettings.json");
71+
})
72+
.Build()
73+
.StartAsync();
74+
75+
// work with metadata options
76+
var metadataOptions = host.Services.GetRequiredService<IOptions<ApplicationMetadata>>();
77+
var buildVersion = metadataOptions.Value.BuildVersion;
78+
```
79+
80+
Alternatively, you can achieve the same result as above by doing this:
81+
82+
```cs
83+
using var hostBuilder = new HostBuilder()
84+
.ConfigureAppConfiguration((hostBuilderContext, configurationBuilder) => configurationBuilder
85+
.AddApplicationMetadata(hostBuilderContext.HostingEnvironment)
86+
.AddJsonFile("appsettings.json"))
87+
.ConfigureServices((hostBuilderContext, serviceCollection) => serviceCollection
88+
.AddApplicationMetadata(hostBuilderContext.Configuration.GetSection("ambientmetadata:application")))
89+
.Build();
90+
91+
// work with metadata options
92+
var metadataOptions = host.Services.GetRequiredService<IOptions<ApplicationMetadata>>();
93+
var buildVersion = metadataOptions.Value.BuildVersion;
94+
```

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"EventId": 0,
3+
"LogLevel": "Information",
4+
"Category": "Program",
5+
"Message": "This is a sample log message",
6+
"State": {
7+
"Message": "This is a sample log message",
8+
"service.name": "servicelogenricher",
9+
"deployment.environment": "Production",
10+
"DeploymentRing": "testring",
11+
"service.version": "1.2.3",
12+
"{OriginalFormat}": "This is a sample log message"
13+
}
14+
}

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
using System.Text.Json;
2+
using Microsoft.Extensions.DependencyInjection;
3+
using Microsoft.Extensions.Hosting;
4+
using Microsoft.Extensions.Logging;
5+
6+
var builder = Host.CreateDefaultBuilder(args);
7+
builder.UseApplicationMetadata();
8+
builder.ConfigureLogging(builder =>
9+
{
10+
builder.EnableEnrichment();
11+
builder.AddJsonConsole(op =>
12+
{
13+
op.JsonWriterOptions = new JsonWriterOptions
14+
{
15+
Indented = true
16+
};
17+
});
18+
});
19+
builder.ConfigureServices((context, services) =>
20+
{
21+
services.AddServiceLogEnricher(context.Configuration.GetSection("applicationlogenricheroptions"));
22+
});
23+
24+
var host = builder.Build();
25+
var logger = host.Services.GetRequiredService<ILogger<Program>>();
26+
27+
logger.LogInformation("This is a sample log message");
28+
29+
await host.RunAsync();
30+
31+

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"AmbientMetadata": {
3+
"Application": {
4+
"DeploymentRing": "testring",
5+
"BuildVersion": "1.2.3"
6+
}
7+
},
8+
"ApplicationLogEnricherOptions": {
9+
"BuildVersion": true,
10+
"DeploymentRing": true
11+
}
12+
}

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

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>net9.0</TargetFramework>
6+
<ImplicitUsings>enable</ImplicitUsings>
7+
<Nullable>enable</Nullable>
8+
</PropertyGroup>
9+
10+
<ItemGroup>
11+
<PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.9" />
12+
<PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.9" />
13+
<PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.9" />
14+
<PackageReference Include="Microsoft.Extensions.Telemetry" Version="9.9.0" />
15+
<PackageReference Include="Microsoft.Extensions.AmbientMetadata.Application" Version="9.9.0" />
16+
</ItemGroup>
17+
18+
<ItemGroup>
19+
<None Update="appsettings.json">
20+
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
21+
</None>
22+
</ItemGroup>
23+
24+
</Project>

0 commit comments

Comments
 (0)