KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

serilog-sinks-applicationinsights

★ 232 Open GitHub ↗

A Serilog sink that writes events to Microsoft Azure Application Insights

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Serilog.Sinks.ApplicationInsights&nbsp;[![Build status](https://github.com/serilog-contrib/serilog-sinks-applicationinsights/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/serilog-contrib/serilog-sinks-applicationinsights/actions)&nbsp;[![NuGet Version](https://img.shields.io/nuget/v/Serilog.Sinks.ApplicationInsights.svg?style=flat)](https://www.nuget.org/packages/Serilog.Sinks.ApplicationInsights/)&nbsp;[![NuGet Downloads](https://img.shields.io/nuget/dt/Serilog.Sinks.ApplicationInsights.svg)](https://www.nuget.org/packages/Serilog.Sinks.ApplicationInsights/)

A sink for Serilog that writes events to Microsoft Application Insights. This sink comes with several defaults that send
Serilog `LogEvent` messages to Application Insights as either `EventTelemetry` or `TraceTelemetry`.

## Install

```powershell
dotnet add package Serilog.Sinks.ApplicationInsights
```

## Configuring

The recommended way to configure the sink is to reuse the `TelemetryConfiguration` (or `TelemetryClient`) already configured by your application (for example via dependency injection in ASP.NET Core, Azure Functions, Worker Services).

```csharp
Log.Logger = new LoggerConfiguration()
    .WriteTo.ApplicationInsights(
        telemetryConfiguration, // from DI (recommended)
        TelemetryConverter.Traces)
    .CreateLogger();
```

If you don't have an existing `TelemetryConfiguration` (uncommon), you can use the connection string overload:

```csharp
Log.Logger = new LoggerConfiguration()
    .WriteTo.ApplicationInsights(
        "<your Application Insights connection string>",
        TelemetryConverter.Traces)
    .CreateLogger();
```

Legacy: some older application types used `TelemetryConfiguration.Active`. This is not recommended on modern .NET and may be deprecated depending on the Application Insights SDK version.

> You can also pass an *instrumentation key* and this sink will create a new `TelemetryConfiguration` based on it,
> however it's actively discouraged compared to using already initialised telemetry configuration, as your telemetry
> won't
> be properly correlated.

**Note:** Whether you choose `Events` or `Traces`, if the LogEvent contains any exceptions it will always be sent
as `ExceptionTelemetry`.

### `TelemetryConfiguration.Active` is deprecated in the App Insights SDK for .NET Core, what do I do?

The
singleton [`TelemetryConfiguration.Active` has been deprecated in the Application Insights SDK on .NET Core in favor of dependency injection pattern](https://github.com/microsoft/ApplicationInsights-dotnet/issues/1152)
.

Therefore, now we need to pass in the `TelemetryConfiguration` instance that was added either
by `services.AddApplicationInsightsTelemetryWorkerService()` (if you're developing
a [non-http application](https://docs.microsoft.com/en-us/azure/azure-monitor/app/worker-service))
or `services.AddApplicationInsightsTelemetry()` (if you're developing
an [ASP.Net Core application](https://docs.microsoft.com/en-us/azure/azure-monitor/app/asp-net-core)) during Startup
in `ConfigureServices`.

```csharp
Log.Logger = new LoggerConfiguration()
    .WriteTo.ApplicationInsights(
        serviceProvider.GetRequiredService<TelemetryConfiguration>(),
        TelemetryConverter.Traces)
    .CreateLogger();
```

However, you probably want to setup your Logger as close to the entry point of your application as possible, so that any
startup errors can be caught and properly logged. The problem is that now we're in a chicken-and-egg situation: we want
to setup the logger early, but we need the `TelemetryConfiguration` which still haven't been added to our DI container.

Luckily [from version 4.0.x of the `Serilog.Extensions.Hosting` we have the possibility to configure a bootstrap logger](https://nblumhardt.com/2020/10/bootstrap-logger/)
to capture early errors, and then change it using DI-dependent services once they are configured.

```csharp
// dotnet add package Serilog.Extensions.Hosting

public static class Program
{
    public static void Main(string[] args)
    {
        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .CreateBootstrapLogger();

try
        {
            CreateHostBuilder(args).Build().Run();
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "An unhandled exception occurred during bootstrapping");
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }

public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .UseSerilog((context, services, loggerConfiguration) => loggerConfiguration
                .WriteTo.ApplicationInsights(
                    services.GetRequiredService<TelemetryConfiguration>(),
                    TelemetryConverter.Traces))
            .ConfigureWebHostDefaults(webBuilder => { webBuilder.UseStartup<Startup>(); });
}
```

### Configuring with `ReadFrom.Configuration()`

Configuring in code, as shown above, is recommended because the existing `TelemetryClient` can be injected.

The following configuration shows how to create an ApplicationInsights sink
with [ReadFrom.Configuration(configuration)](https://github.com/serilog/serilog-settings-configuration).

```json
{
  "Serilog": {
    "Using": [
      "Serilog.Sinks.ApplicationInsights"
    ],
    "MinimumLevel": {
      "Default": "Information",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    },
    "WriteTo": [
      {
        "Name": "ApplicationInsights",
        "Args": {
          "connectionString": "[your connection string here]",
          "telemetryConverter":
                        "Serilog.Sinks.ApplicationInsights.TelemetryConverters.TraceTelemetryConverter, Serilog.Sinks.ApplicationInsights"
        }
      }
    ],
    "Enrich": [ "FromLogContext" ],
    "Properties": {
      "Application": "Sample"
    }
  }
}
```

The `telemetryConverter` has to be specified with the full type name and the assembly name.

A `connectionString` can be omitted if it's [supplied in the `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable](https://docs.microsoft.com/en-us/azure/azure-monitor/app/migrate-from-instrumentation-keys-to-connection-strings).

## What does the sink submit?

By default, trace telemetry submits:

- **rendered message** in trace's standard *message* property.
- **severity** in trace's standard *severityLevel* property.
- **timestamp** in trace's standard *timestamp* property.
- **operation id** from `OperationId` property, or the `LogEvent.TraceId` property.
- **operation parent id** from `ParentSpanId` property.
- **operation name** from `OperationName` property.
- **component version** from `Version` property.
- **messageTemplate** in *customDimensions*.
- **custom log properties** as *customDimensions*.

Event telemetry submits:

- **message template** as *event name*.
- **renderedMessage** in *customDimensions*.
- **timestamp** in event's standard *timestamp* property.
- **operation id** from `OperationId` property, or the `LogEvent.TraceId` property.
- **operation parent id** from `ParentSpanId` property.
- **operation name** from `OperationName` property.
- **component version** from `Version` property.
- **custom log properties** as *customDimensions*.

Exception telemetry submits:

- **exception** as standard AI exception.
- **severity** in trace's standard *severityLevel* property.
- **timestamp** in trace's standard *timestamp* property.
- **operation id** from `OperationId` property, or the `LogEvent.TraceId` property.
- **operation parent id** from `ParentSpanId` property.
- **operation name** from `OperationName` property.
- **component version** from `Version` property.
- **custom log properties** as *customDimensions*.

> Note that **log context** properties are also included in *customDimensions* when Serilog is configured
> with `.Enrich.FromLogContext()`.

## How custom properties are logged?

By default custom properties are converted to compact JSON, for instance:

```csharp
var position = new { Latitude = 25, Longitude = 134 };
var elapsedMs = 34;
var numbers = new int[] { 1, 2, 3, 4 };

Logger.Information("Processed {@Position} in {Elapsed:000} ms., str {str}, numbers: {numbers}",
    position, elapsedMs, "test", numbers);
```

will produce the following properties in *customDimensions*:

|Property|Value|
|--------|-----|
|Elapsed|34|
|Position|{"Latitude":25,"Longitude":134}|
|numbers|[1,2,3,4]|

This is a breaking change from v2 which was producing these properties:

|Property|Value|
|--------|-----|
|Elapsed|34|
|Position.Latitude|25|
|Position.Longitude|134|
|numbers.0|1|
|numbers.1|2|
|numbers.2|3|
|numbers.3|4|

You can revert the old behavior by overriding standard telemetry formatter, for instance:

```csharp
private class DottedOutTraceTelemetryConverter : TraceTelemetryConverter
{
    public override IValueFormatter ValueFormatter => new ApplicationInsightsDottedValueFormatter();
}
```

## Customizing

Additionally, you can also customize *whether* to send the LogEvents at all, if so *which type(s)* of Telemetry to send
and also *what to send* (all or no LogEvent properties at all) by passing your own `ITelemetryConverter` instead
of `TelemetryConverter.Traces` or `TelemetryConverter.Events` by either implementing your own `ITelemetryConverter` or
deriving from `TraceTelemetryConverter` or `EventTelemetryConverter` and overriding specific bits.

```csharp
Log.Logger = new LoggerConfiguration()
    .WriteTo.ApplicationInsights(configuration, new CustomConverter())
    .CreateLogger();
// ...

private class CustomConverter : TraceTelemetryConverter
{
    public override IEnumerable<ITelemetry> Convert(LogEvent logEvent, IFormatProvider formatProvider)
    {
        // first create a default TraceTelemetry using the sink's default logic
        // .. but without the log level, and (rendered) message (template) included in the Properties
        foreach (ITelemetry telemetry in base.Convert(logEvent, formatProvider))
        {
            // then go ahead and post-process the telemetry's context to contain the user id as desired
            if (logEvent.Properties.ContainsKey("UserId"))
            {
                telemetry.Context.User.Id = logEvent.Properties["UserId"].ToString();
            }
            // post-process the telemetry's context to contain the operation id
            if (logEvent.Properties.ContainsKey("OperationId"))
            {
                telemetry.Context.Operation.Id = logEvent.Properties["OperationId"].ToString();
            }
            // post-process the telemetry's context to contain the operation parent id
            if (logEvent.Properties.ContainsKey("ParentSpanId"))
            {
                telemetry.Context.Operation.ParentId = logEvent.Properties["ParentSpanId"].ToString();
            }
            // typecast to ISupportProperties so you can manipulate the properties as desired
            ISupportProperties propTelemetry = (ISupportProperties)telemetry;

// find redundant properties
            var removeProps = new[] { "UserId", "ParentSpanId", "OperationId" };
            removeProps = removeProps.Where(prop => propTelemetry.Properties.ContainsKey(prop)).ToArray();

foreach (var prop in removeProps)
            {
                // remove redundant properties
                propTelemetry.Properties.Remove(prop);
            }

yield return telemetry;
        }
    }
}
```

If you want to skip sending a particular LogEvent, just return `null` from your own converter method.

### Customising included properties

The easiest way to customise included properties is to subclass one of the `ITelemetryConverter` implementations. For
instance, let's include `renderedMessage` in event telemetry:

```csharp
private class IncludeRenderedMessageConverter : EventTelemetryConverter
{
    public override void ForwardPropertiesToTelemetryProperties(LogEvent logEvent,
        ISupportProperties telemetryProperties, IFormatProvider formatProvider)
    {
        base.ForwardPropertiesToTelemetryProperties(logEvent, telemetryProperties, formatProvider,
            includeLogLevel: false,
            includeRenderedMessage: true,
            includeMessageTemplate: false);
    }
}
```

## How, When and Why to Flush Messages Manually

### Or: Where did my Messages go?

As explained by
the [Application Insights documentation](https://learn.microsoft.com/en-us/azure/azure-monitor/app/classic-api?tabs=dotnet#flushing-data)
, the default behaviour of the AI client is to buffer messages and send them to AI in batches whenever the client seems
fit. However, this may lead to lost messages when your application terminates while there are still unsent messages in
said buffer.

You can control when AI shall flush its messages, for example when your application closes:

1) Create a custom `TelemetryClient` and hold on to it in a field or property:

```csharp
// private TelemetryClient _telemetryClient;

// ...
var telemetryConfiguration = TelemetryConfiguration.CreateDefault();
telemetryConfiguration.ConnectionString = "<your Application Insights connection string>";

_telemetryClient = new TelemetryClient(telemetryConfiguration);
```

2) Use that custom `TelemetryClient` to initialize the Sink:

```csharp
var log = new LoggerConfiguration()
    .WriteTo.ApplicationInsights(_telemetryClient, TelemetryConverter.Events)
    .CreateLogger();
```

3) Call .Flush() on the TelemetryClient whenever you deem necessary, i.e. Application Shutdown:

```csharp
_telemetryClient.Flush();

// The AI documentation mentions that calling `Flush()` *can* be asynchronous and non-blocking so
// depending on the underlying Channel to AI you might want to wait some time
// specific to your application and its connectivity constraints for the flush to finish.

await Task.Delay(1000);

// or

System.Threading.Thread.Sleep(1000);

```

## Including Operation Id

Application Insight's operation id is set from the following sources in order of precedence:

1. `OperationId` LogEvent property
2. `TraceId` LogEvent property

This can be set like so:

```csharp

public class OperationIdEnricher : ILogEventEnricher
{
    public void Enrich(LogEvent logEvent, ILogEventPropertyFactory propertyFactory)
    {
        if (logEvent.Properties.TryGetValue("RequestId", out var requestId))
        {
            logEvent.AddPropertyIfAbsent(new LogEventProperty("OperationId", requestId));
        }
    }
}
```

## Including Version

Application Insight supports component version and is pushed out if you set `Version` log event property. If it's
present, AI's operation version will include the value from this property.

## Using with SerilogTracing

[SerilogTracing](https://github.com/serilog-tracing/serilog-tracing) provides tracing primitives that integrate with Serilog's structured logging. When used with this sink, tracing context is automatically included in Application Insights telemetry.

The following `LogEvent` properties are mapped to Application Insights telemetry:

| LogEvent Property | Application Insights Telemetry | Notes |
|-------------------|---------------------------------|-------|
| `TraceId` | `Context.Operation.Id` | From TraceId captured in LogEvent |
| `SpanId` | `Id` (for Request/Dependency telemetry) | From SpanId captured in LogEvent |
| `ParentSpanId` | `Context.Operation.ParentId` | |
| `OperationName` | `Context.Operation.Name` | |
| `OperationId` | `Context.Operation.Id` | Overrides TraceId |
| `Version` | `Context.Component.Version` | |

If present, `Baggage` is forwarded to Application Insights custom dimensions (`telemetry.Properties`).

Precedence for `Context.Operation.Id`: `OperationId` property > `TraceId` property (when both `OperationId` and `TraceId` properties are absent).

### Enriching from `Activity` (explicit opt-in)

This sink is designed to work well with Serilog's asynchronous/batched processing. To keep telemetry deterministic, adding `OperationName` and `Baggage` from the ambient `Activity` is an explicit opt-in: copy the values onto the `LogEvent` before it reaches the sink.

The sink includes an enricher that adds this by default. Enable it using the provided `Enrich` extension method:

```csharp
Log.Logger = new LoggerConfiguration()
    .Enrich.WithActivityDetails(includeOperationName: true, includeBaggage: true)
    .WriteTo.ApplicationInsights(telemetryConfiguration, TelemetryConverter.Traces)
    .CreateLogger();
```

## Upgrading to 5.0 (from 4.x)

This is a new major release (5.0). Notable changes:

- **OperationName and Baggage are opt-in:** they are only forwarded when present as `LogEvent` properties (use the built-in enricher above or your own enricher).
- **Less redundancy in custom dimensions by default:** operation-related values are set on `ITelemetry.Context` and are not duplicated into `telemetry.Properties` unless enabled.

### `TelemetryConverterBase` constructor flags

Converters derived from `TelemetryConverterBase` can be configured to also include selected operation-related values in `telemetry.Properties` (custom dimensions):

```csharp
public TelemetryConverterBase(
    bool includeOperationIdPropertyAsTelemetryProperty,
    bool includeParentSpanIdPropertyAsTelemetryProperty,
    bool includeOperationNamePropertyAsTelemetryProperty,
    bool includeVersionPropertyAsTelemetryProperty)
```

If you previously relied on these values being present in `telemetry.Properties`, enable the relevant flags when constructing your converter, or post-process telemetry in a custom converter.

## Using with Azure Functions

Azure functions has out of the box integration with Application Insights, which automatically logs functions execution
start, end, and any exception. Please refer to
the [original documentation](https://docs.microsoft.com/en-us/azure/azure-functions/functions-monitoring) on how to
enable it.

This sink can enrich AI messages, preserving *operation_Id* and other context information which is *already provided by
functions runtime*. The easiest way to configure Serilog in this case is to use the injected **TelemetryClient** which
should be automatically configured by the environment through the **APPLICATIONINSIGHTS_CONNECTION_STRING** appsetting.
You can, for instance, initialise logging in the static constructor:

```csharp
[assembly: FunctionsStartup(typeof(MyFunctions.Startup))]
namespace MyFunctions
{
    public class Startup : FunctionsStartup
    {
        public override void Configure(IFunctionsHostBuilder builder)
        {
            builder.Services.AddSingleton<ILoggerProvider>((sp) =>
            {
                Log.Logger = new LoggerConfiguration()
                    .Enrich.FromLogContext()
                    .WriteTo.ApplicationInsights(sp.GetRequiredService<TelemetryClient>(), TelemetryConverter.Traces)
                    .CreateLogger();
                return new SerilogLoggerProvider(Log.Logger, true);
            });
        }
    }
}
```

See also: [Serilog Documentation](https://github.com/serilog/serilog/wiki)

serilog-sinks-applicationinsights

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README