From 472b9e78ed0fc92a0d4f60adc96b7d23f350ec66 Mon Sep 17 00:00:00 2001 From: Kenneth Mugo Date: Tue, 16 Apr 2024 15:26:30 +0300 Subject: [PATCH 1/3] Improved documentation for Tingle.AspNetCore.ApplicationInsights --- .../README.md | 66 ++++++++++++------- 1 file changed, 41 insertions(+), 25 deletions(-) diff --git a/src/Tingle.AspNetCore.ApplicationInsights/README.md b/src/Tingle.AspNetCore.ApplicationInsights/README.md index abe151b..7c92b3b 100644 --- a/src/Tingle.AspNetCore.ApplicationInsights/README.md +++ b/src/Tingle.AspNetCore.ApplicationInsights/README.md @@ -1,52 +1,68 @@ # Tingle.AspNetCore.ApplicationInsights -> [!CAUTION] -> This documentation for `Tingle.AspNetCore.ApplicationInsights` may not cover the most recent version of the code. Use it sparingly -> -> See +This library provides some extensions for [Microsoft.ApplicationInsights](https://github.com/Microsoft/ApplicationInsights-dotnet). -This is a customized library developed by Tingle. The `ApplicationInsights` package in AspNetCore offers functionality to understand how the application is performing and how it is being used. `Tingle.AspNetCore.ApplicationInsights` has additional functionality for Application Insights on AspNetCore mainly used in building Tingle APIs and Services. +## Add details of the request source to application insights telemetry -## Adding to Service Collections +You can add some request source details to the `RequestTelemetry` that is sent along to application insights. The following details can be added: -The following logic is added to `Program.cs` file: +- The package name which should be found in the `X-App-Package-Id` request header +- The version name which should be found in the `X-App-Version-Name` request header +- The version code which should be found in the `X-App-Version-Code` request header +- The User Agent which should be found in the `User-Agent` request header +- The IP address -```csharp -// Enables Application Insights telemetry collection -builder.Services.AddApplicationInsightsTelemetryExtras(builder.Configuration) +To accomplish this, add the following logic to `Program.cs` or `Startup.cs` file: + +```cs +services.AddApplicationInsightsTelemetryExtras(); +services.AddHttpContextAccessor(); ``` -This library has a number of extensibility points, one of them being the telemetry initializer. To implement the telemetry initializer, a class is created that implements the `ITelemetryInitializer` interface. In this case, `ExtrasTelemetryInitializer` is a class implementing `ITelemetryInitializer` interface. The `ExtrasTelemetryInitializer` extends ApplicationInsights telemetry collection by supplying additional information about the application which includes the `AppPackageId`, `AppVersionName`, `AppVersionCode`, `AppClient`, `AppIpAddress` and `AppKind`. +We've injected the `IHttpContextAccessor` in the DI container so that we can access the `HttpContext` object that contains the HTTP request details. -In the `ITelemetryInitializer` interface's `Initialize` method, a `HttpContext` object is created. Whenever a new HTTP request or response is made, a `HttpContext` object is created which wraps all HTTP related information in one place. The `HttpContext` object is accessed through the `IHttpContextAccessor` and its default implementation `HttpAccessor`. It is necessary to use the `IHttpContextAccessor` so as to access the `HttpContext` object within a service. +## Add all request headers to application insights telemetry -The initializers are used to mark every collected telemetry item with the current web request identity so that traces and exceptions can be correlated to corresponding requests. +You can send all request headers to application insights by adding the following logic to `Program.cs` or `Startup.cs` file: -The library is used to track error details in application insights when the response is `BadRequestObjectResult` with the value of type `ProblemDetails`. +```cs +services.AddApplicationInsightsTelemetryHeaders(); +services.AddHttpContextAccessor(); +``` -From the request header, the application's package ID, version name, version code, client, IP address and kind properties are extracted so that the traces and exceptions can be correlated/matched to the corresponding requests. +We've injected the `IHttpContextAccessor` in the DI container so that we can access the `HttpContext` object that contains the HTTP request details. -## Configuration +## Add manual dependency tracking in application insights -The instrumentation key is specified in configuration. The following code sample shows how to specify an instrumentation key in `appsettings.json.` +A dependency is a component that's called by your application. It's typically a service called by using HTTP, a database, or a file system. Application Insights measures the duration of dependency calls and whether it's failing or not, along with information like the name of the dependency. You can investigate specific dependency calls and correlate them to requests and exceptions. The list of dependencies that are automatically tracked can be seen [here](https://learn.microsoft.com/en-us/azure/azure-monitor/app/asp-net-dependencies). -```json -{ - "ApplicationInsights:InstrumentationKey":"#{ApplicationInsightsInstrumentationKey}#" -} +So how do we assist in tracking of dependencies that aren't automatically tracked? + +We do this by using [ActivitySource](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activitysource?view=net-5.0&ref=jimmybogard.com)/[ActivityListener](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activitylistener?view=net-5.0&ref=jimmybogard.com) APIs, which make it quite a bit simpler to raise and listen to events for `Activity` start/stop. + +Per conventions, the activity source name should be the name of the assembly creating the activities. That makes it much easier to "discover" activities, you don't have to expose a constant or search through source code to discern the name. + +We can then create an `IHostedService` that uses `ActivityListener` internally, collects from the `ActivitySources` that are needed, creates instance(s) of `DependencyTelemetry` then sends to application insights via the [TrackDependency API](https://learn.microsoft.com/en-us/azure/azure-monitor/app/api-custom-events-metrics#trackdependency). + +This can be accomplished by adding the following logic to `Program.cs` or `Startup.cs` file: + +```cs +services.AddActivitySourceDependencyCollector(["Tingle.EventBus", "Tingle.Extensions.MongoDB"]); ``` -## Sample Usage +You can replace the array of activities supplied in `AddActivitySourceDependencyCollector(...)` with your own. + +## Track problem details in application insights + +Track the problem details in application insights when the response is a `BadRequestObjectResult` with value of `ProblemDetails`. The properties are seen as custom properties of an application insights telemetry record. To do this, annotate your controller with the `TrackProblems` attribute: -```csharp +```cs [TrackProblems] [ApiVersion("1")] [Route("v{version:apiVersion}/[controller]")] public class DummyController : ControllerBase { [HttpPost] - [ProducesResponseType(typeof(RequestEntry), 200)] - [ProducesResponseType(typeof(ErrorModel), 400)] public async Task SendAsync([FromBody] SendRequestModel model) { ... From 1103377c449628cf825bfc77e6c1f3762aa7a02b Mon Sep 17 00:00:00 2001 From: Kenneth Mugo Date: Tue, 16 Apr 2024 15:30:40 +0300 Subject: [PATCH 2/3] Slight update to docs --- src/Tingle.AspNetCore.ApplicationInsights/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/Tingle.AspNetCore.ApplicationInsights/README.md b/src/Tingle.AspNetCore.ApplicationInsights/README.md index 7c92b3b..e631dfa 100644 --- a/src/Tingle.AspNetCore.ApplicationInsights/README.md +++ b/src/Tingle.AspNetCore.ApplicationInsights/README.md @@ -21,6 +21,8 @@ services.AddHttpContextAccessor(); We've injected the `IHttpContextAccessor` in the DI container so that we can access the `HttpContext` object that contains the HTTP request details. +The request source details will be seen as custom properties of an application insights telemetry record. + ## Add all request headers to application insights telemetry You can send all request headers to application insights by adding the following logic to `Program.cs` or `Startup.cs` file: @@ -32,6 +34,8 @@ services.AddHttpContextAccessor(); We've injected the `IHttpContextAccessor` in the DI container so that we can access the `HttpContext` object that contains the HTTP request details. +The request headers will be seen as custom properties of an application insights telemetry record. + ## Add manual dependency tracking in application insights A dependency is a component that's called by your application. It's typically a service called by using HTTP, a database, or a file system. Application Insights measures the duration of dependency calls and whether it's failing or not, along with information like the name of the dependency. You can investigate specific dependency calls and correlate them to requests and exceptions. The list of dependencies that are automatically tracked can be seen [here](https://learn.microsoft.com/en-us/azure/azure-monitor/app/asp-net-dependencies). From eaa0da8c07f5592e61d9644f7a04e32850b6a2cd Mon Sep 17 00:00:00 2001 From: Kenneth Mugo Date: Tue, 16 Apr 2024 15:38:54 +0300 Subject: [PATCH 3/3] Slight update for link in documentation --- src/Tingle.AspNetCore.ApplicationInsights/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Tingle.AspNetCore.ApplicationInsights/README.md b/src/Tingle.AspNetCore.ApplicationInsights/README.md index e631dfa..2276ec1 100644 --- a/src/Tingle.AspNetCore.ApplicationInsights/README.md +++ b/src/Tingle.AspNetCore.ApplicationInsights/README.md @@ -38,7 +38,7 @@ The request headers will be seen as custom properties of an application insights ## Add manual dependency tracking in application insights -A dependency is a component that's called by your application. It's typically a service called by using HTTP, a database, or a file system. Application Insights measures the duration of dependency calls and whether it's failing or not, along with information like the name of the dependency. You can investigate specific dependency calls and correlate them to requests and exceptions. The list of dependencies that are automatically tracked can be seen [here](https://learn.microsoft.com/en-us/azure/azure-monitor/app/asp-net-dependencies). +A dependency is a component that's called by your application. It's typically a service called by using HTTP, a database, or a file system. Application Insights measures the duration of dependency calls and whether it's failing or not, along with information like the name of the dependency. You can investigate specific dependency calls and correlate them to requests and exceptions. The list of dependencies that are automatically tracked can be seen [here](https://learn.microsoft.com/en-us/azure/azure-monitor/app/asp-net-dependencies#automatically-tracked-dependencies). So how do we assist in tracking of dependencies that aren't automatically tracked?