Skip to main content
Version: v3.1.0

Simplified telemetry tracking

Arcus provides a simplified way of tracking telemetry in applications. Based on your preferences and needs, one of the following telemetry tracking systems can be used as infrastructure where Arcus Observability can build upon.

To build upon OpenTelemetry's infrastructure, install the following NuGet package:

PS> Install-Package -Name Arcus.Observability.Telemetry.OpenTelemetry

Only a single line is required to activate Arcus' alternative to telemetry tracking:

using OpenTelemetry;

Host.CreateDefaultBuilder()
    .ConfigureServices(services =>
    {
        services.AddOpenTelemetry()
+               .UseArcusObservability();
    });

Telemetry tracking happens via the IObservability facade, which is an interface that gets registered in the application services.

note

An ActivitySource is registered as a singleton for the entire lifetime of the application. This ActivitySource is also registered in OpenTelemetry's 'tracked sources'. The same applies for the Meter type. A single instance is used throughout the application which is used for recording metrics in the application.

Tracking metrics​

OpenTelemetry works with .NET default Meter infrastructure to track metrics in observability backends. One can still use this way of working in case more advanced metrics have to be tracked. For simple delta values, Arcus provides a simple solution with the IObservability.RecordMetric("<metric-name>") method.

using Arcus.Observability;

public class OrderMessageHandler(IObservability observability)
{
    public async Task ProcessOrdersAsync(OrderBatch orders)
    {
        // TODO: process orders

        var telemetryContext = new Dictionary<string, object> 
        {
            ["BatchId"] = orders.Id
        };
        observability.RecordMetric("orders_processed").WithValue(orders.Length, telemetryContext);
    }
}

Tracking requests/dependencies​

OpenTelemetry works with .NET default Activity instances to track requests/dependencies in application. One can still use this way of working in case more advanced distributed traces are needed. For simple parent/child relationships, Arcus provides a simple solution with the IObservability.StartCustom[Request/Dependency]("<operation-name>") method for cases where Microsoft does not built-in track the request/dependency.

The IsSuccessful property on both operations allows to specify how the status of the request/dependency operation should be tracked.

using Arcus.Observability;

public class OrderProcessingHost(IObservability observability)
{
    public async Task ReceiveOrdersAsync(OrderBatch orders)
    {
        var telemetryContext = new Dictionary<string, object> 
        {
            ["BatchId"] = orders.Id
        };

        using (var request = observability.StartCustomRequest("Process Orders", telemetryContext))
        {
            try
            {
                // TODO: process orders
                
                using (var dependency = observability.StartCustomDependency("Publish Results", telemetryContext))
                {
                    try
                    {
                        // TODO: publish results
                    }
                    catch (PublishException exception)
                    {
                      dependency.IsSuccessful = false;
                    }
                }
            }
            catch (ProcessException exception)
            {
                request.IsSuccessful = false;
            }
        }
    }
}

Customization​

Several options are available on the facade to configure at a global level the tracked telemetry.

services.OpenTelemetry()
        .UseArcusObservability(options =>
        {
            // Configure the resource's service name via an `IAppName` implementation.
            // Corresponds with OpenTelemetry's service.name and Azure Application Insights Cloud's role name.
            // Default: Assembly name of running application.
            options.UseAppName("Order.Handler");

            // Configure the resource's service version via an `IAppVersion` implementation.
            // Corresponds with OpenTelemetry's service.version.
            options.UseAssemblyAppVersion<Program>();
        });