docs: publish v2.5 feature docs (#416)

docs/versioned_docs/version-v2.5.0/01-index.md

@@ -0,0 +1,32 @@
+---
+title: "Arcus Observability"
+layout: default
+slug: /
+sidebar_label: Welcome
+---
+
+# Introduction
+
+Arcus Observability allows you to work easily with Azure Application Insights telemetry. Instead of managing logging, correlation, tracking, Arcus Observability allows you to work with the common `ILogger` infrastructure and still be able to write multi-dimensional telemetry data. The library supports multiple telemetry types like tracking dependencies, requests, events, metrics, while also be able to filter with Serilog filters and enrich with custom correlation.
+
+![Logger Arcus - Application Insights](/img/logger-arcus-appinsights.png)
+
+# Guidance
+
+- [Using Arcus & Serilog in ASP.NET Core](./03-Guidance/use-with-dotnet-and-aspnetcore.md)
+- [Using Arcus & Serilog in Azure Functions](./03-Guidance/use-with-dotnet-and-functions.md)
+
+# Installation
+
+The Arcus.Observability.Correlation package can be installed via NuGet:
+
+```shell
+PM > Install-Package Arcus.Observability.Serilog.Sinks.ApplicationInsights
+```
+
+For more granular packages we recommend reading [the documentation](./02-Features/sinks/azure-application-insights.md).
+
+# License
+This is licensed under The MIT License (MIT). Which means that you can use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the web application. But you always need to state that Codit is the original author of this web application.
+
+*[Full license here](https://github.com/arcus-azure/arcus.observability/blob/master/LICENSE)*

docs/versioned_docs/version-v2.5.0/02-Features/correlation.md

@@ -0,0 +1,221 @@
+---
+title: "Correlation"
+layout: default
+---
+
+# Correlation
+
+`CorrelationInfo` provides a common set of correlation levels:
+
+- Transaction Id - ID that relates different requests together into a functional transaction.
+- Operation Id - Unique ID information for a single request.
+- Operation parent Id - ID of the original service that initiated the request.
+
+## Installation
+
+This feature requires to install our NuGet package
+
+```shell
+PM > Install-Package Arcus.Observability.Correlation
+```
+
+## What We Provide
+
+The `Arcus.Observability.Correlation` library provides a way to get access to correlation information across your application.
+What it **DOES NOT** provide is how this correlation information is initially set.
+
+It uses the Microsoft dependency injection mechanism to register an `ICorrelationInfoAccessor` and `ICorrelationInfoAccessor<>` implementation that is available.
+
+**Example**
+
+```csharp
+using Arcus.Observability.Correlation;
+
+namespace Application
+{
+    public class Startup
+    {
+        public void ConfigureServices(IServiceCollection services)
+        {
+            // Adds operation and transaction correlation to the application,
+            // using the `DefaultCorrelationInfoAccessor` as `ICorrelationInfoAccessor` that stores the `CorrelationInfo` model internally.
+            services.AddCorrelation();
+        }
+    }
+}
+```
+## Custom Correlation
+
+We register two interfaces during the registration of the correlation: `ICorrelationInfoAccessor` and `ICorrelationInfoAccessor<>`.
+The reason is because some applications require a custom `CorrelationInfo` model, and with using the generic interface `ICorrelationInfoAccessor<>` we can support this.
+
+**Example**
+
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+using Arcus.Observability.Correlation;
+
+namespace Application
+{
+    public class OrderCorrelationInfo : CorrelationInfo
+    {
+        public string OrderId { get; }
+    }
+
+    public class Startup
+    {
+        public void ConfigureService(IServiceCollection services)
+        {
+            services.AddCorrelation<OrderCorrelationInfo>();
+        }
+    }
+}
+```
+
+## Accessing Correlation Throughout the Application
+
+When a part of the application needs access to the correlation information, you can inject one of the two interfaces:
+
+```csharp
+using Arcus.Observability.Correlation;
+
+namespace Application
+{
+    public class OrderService
+    {
+        public OrderService(ICorrelationInfoAccessor accessor)
+        {
+             CorrelationInfo correlationInfo = accessor.CorrelationInfo;
+        }
+    }
+}
+```
+
+Or, alternatively when using custom correlation:
+
+```csharp
+using Arcus.Observability.Correlation;
+
+namespace Application
+{
+    public class OrderService
+    {
+        public OrderService(ICorrelationInfoAccessor<OrderCorrelationInfo> accessor)
+        {
+             OrderCorrelationInfo correlationInfo = accessor.CorrelationInfo;
+        }
+    }
+}
+```
+
+## Configuration
+
+The library also provides a way configure some correlation specific options that you can later retrieve during get/set of the correlation information in your application.
+
+```csharp
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddCorrelation(options =>
+    {
+        // Configuration on the transaction ID (`X-Transaction-ID`) request/response header.
+        // ---------------------------------------------------------------------------------
+
+        // Whether the transaction ID can be specified in the request, and will be used throughout the request handling.
+        // The request will return early when the `.AllowInRequest` is set to `false` and the request does contain the header (default: true).
+        options.Transaction.AllowInRequest = true;
+
+        // Whether or not the transaction ID should be generated when there isn't any transaction ID found in the request.
+        // When the `.GenerateWhenNotSpecified` is set to `false` and the request doesn't contain the header, no value will be available for the transaction ID; 
+        // otherwise a GUID will be generated (default: true).
+        options.Transaction.GenerateWhenNotSpecified = true;
+
+        // Whether to include the transaction ID in the response (default: true).
+        options.Transaction.IncludeInResponse = true;
+
+        // The header to look for in the request, and will be set in the response (default: X-Transaction-ID).
+        options.Transaction.HeaderName = "X-Transaction-ID";
+
+        // The function that will generate the transaction ID, when the `.GenerateWhenNotSpecified` is set to `false` and the request doesn't contain the header.
+        // (default: new `Guid`).
+        options.Transaction.GenerateId = () => $"Transaction-{Guid.NewGuid()}";
+
+        // Configuration on the operation ID (`RequestId`) response header.
+        // ----------------------------------------------------------------
+
+        // Whether to include the operation ID in the response (default: true).
+        options.Operation.IncludeInResponse = true;
+
+        // The header that will contain the operation ID in the response (default: RequestId).
+        options.Operation.HeaderName = "RequestId";
+
+        // The function that will generate the operation ID header value.
+        // (default: new `Guid`).
+        options.Operation.GenerateId = () => $"Operation-{Guid.NewGuid()}";
+
+        // Configuration on the operation parent ID.
+        // -----------------------------------------
+
+        // Whether to extract the operation parent ID from the request or not (default: true).
+        options.OperationParent.ExtractFromRequest = false;
+
+        // The header that will contain the full operation parent ID (default: Request-Id).
+        options.OperationParent.OperationParentHeaderName = "Request-Id";
+
+        // The function that will generate the operation parent ID when it shouldn't be extracted from the request.
+        options.OperationParent.GenerateId = () => $"Parent-{Guid.newGuid()}";
+    });
+}
+```
+
+Later in the application, the options can be retrieved by injecting the `IOptions<CorrelationInfoOptions>` type.
+
+### Custom Configuration
+
+We also provide a way to provide custom configuration options when the application uses a custom correlation model.
+
+For example, with a custom correlation model:
+
+```csharp
+using Arcus.Observability.Correlation;
+
+namespace Application
+{
+    public class OrderCorrelationInfo : CorrelationInfo
+    {
+        public string OrderId { get; }
+    }
+}
+```
+
+We could introduce an `OrderCorrelationInfoOptions` model:
+
+```csharp
+using Arcus.Observability.Correlation;
+
+namespace Application
+{
+    public class OrderCorrelationInfoOptions : CorrelationInfoOptions
+    {
+        public bool IncludeOrderId { get; set; }
+    }
+}
+```
+
+This custom options model can then be included when registering the correlation:
+
+```csharp
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Application
+{
+    public class Startup
+    {
+        public void ConfigureServices(IServiceCollection services)
+        {
+            services.AddCorrelation<OrderCorrelationInfo, OrderCorrelationInfoOptions>(options => options.IncludeOrderId = true);
+        }
+    }
+}
+```
+
+

docs/versioned_docs/version-v2.5.0/02-Features/making-telemetry-more-powerful.md

@@ -0,0 +1,64 @@
+---
+title: "Making telemetry more powerful"
+layout: default
+---
+
+# Making telemetry more powerful
+
+## Providing contextual information
+
+In order to make telemetry more powerful we **highly recommend providing contextual information around what the situation is of your application**. That's why every telemetry type that you can write, allows you to provide context in the form of a dictionary.
+
+```csharp
+using Microsoft.Extensions.Logging;
+
+// Provide context around event
+var telemetryContext = new Dictionary<string, object>
+{
+    {"Customer", "Arcus"},
+    {"OrderId", "ABC"},
+};
+
+logger.LogEvent("Order Created", telemetryContext);
+// Output: "Events Order Created (Context: [Customer, Arcus], [OrderId, ABC])"
+```
+
+By doing so, you'll be able to interact more efficient with your logs by filtering, searching, ... on it.
+
+We support this for all [telemetry types that you can write](./writing-different-telemetry-types.md).
+
+### Seeing the power in action
+
+Let's use an example - When measuring a metric you get an understanding of the count, in our case the number of orders received:
+
+```csharp
+using Microsoft.Extensions.Logging;
+
+logger.LogMetric("Orders Received", 133);
+// Log output: "Metric Orders Received: 133 (Context: )"
+```
+
+If we output this to Azure Application Insights as a metric similar to our example:
+![Single-dimension Metric](/media/single-dimensional-metric.png)
+
+However, you can very easily provide additional context, allowing you to get an understanding of the number of orders received and annotate it with the vendor information.
+
+```csharp
+using Microsoft.Extensions.Logging;
+
+var telemetryContext = new Dictionary<string, object>
+{
+    { "Customer", "Contoso"},
+};
+
+logger.LogMetric("Orders Received", 133, telemetryContext);
+// Log output: "Metric Orders Received: 133 (Context: [Customer, Contoso])"
+```
+
+The outputted telemetry will contain that information and depending on the sink that you are using it's even going to be more powerful.
+
+For example, when using Azure Application Insights your metric will evolve from a single-dimensional metric to multi-dimensional metrics allowing you to get the total number of orders, get the number of orders per vendor or filter the metric to one specific vendor.
+
+Here we are using our multi-dimensional metric and splitting it per customer to get more detailed insights:
+
+![Multi-dimension Metric](/media/multi-dimensional-metrics.png)