OpenTelemetry.Instrumentation.Hangfire 1.13.0-beta.1

Hangfire Instrumentation for OpenTelemetry .NET

This is an Instrumentation Library, which instruments Hangfire and collects telemetry about BackgroundJob.

Steps to enable OpenTelemetry.Instrumentation.Hangfire

Step 1: Install and configure Hangfire

Getting Started

Step 2: Install Hangfire instrumentation Package

Add a reference to the OpenTelemetry.Instrumentation.Hangfire package. Also, add any other instrumentations & exporters you will need.

dotnet add package OpenTelemetry.Instrumentation.Hangfire --prerelease

Step 3: Enable Hangfire Instrumentation at application startup

Hangfire instrumentation must be enabled at application startup.

The following example demonstrates adding Hangfire instrumentation to a console application. This example also sets up the OpenTelemetry Console exporter, which requires adding the package OpenTelemetry.Exporter.Console to the application.

using OpenTelemetry.Trace;

public class Program
{
    public static void Main(string[] args)
    {
        using var tracerProvider = Sdk
            .CreateTracerProviderBuilder()
            .AddHangfireInstrumentation()
            .AddConsoleExporter()
            .Build();
    }
}

For an ASP.NET Core application, adding instrumentation is typically done in the ConfigureServices of your Startup class. Refer to example.

For an ASP.NET application, adding instrumentation is typically done in the Global.asax.cs. Refer to example.

Advanced configuration

This instrumentation can be configured to change the default behavior by using HangfireInstrumentationOptions.

using var tracerProvider = Sdk
    .CreateTracerProviderBuilder()
    .AddHangfireInstrumentation(options =>
    {
        options.DisplayNameFunc = job => $"JOB {job.Id}";
        options.Filter = job => job.Id == "Filter this job";
        options.RecordException = true;
    })
    .AddConsoleExporter()
    .Build();

When used with OpenTelemetry.Extensions.Hosting, all configurations to HangfireInstrumentationOptions can be done in the ConfigureServices method of your applications Startup class as shown below.

// Configure
services.Configure<HangfireInstrumentationOptions>(options =>
{
    options.DisplayNameFunc = job => $"JOB {job.Id}";
    options.Filter = job => job.Id == "Filter this job";
    options.RecordException = true;
});

services.AddOpenTelemetry()
    .WithTracing(builder => builder
        .AddHangfireInstrumentation()
        .AddConsoleExporter());

RecordException

Configures a value indicating whether the exception will be recorded as ActivityEvent or not. See Semantic Conventions for Exceptions on Spans

using var tracerProvider = Sdk
    .CreateTracerProviderBuilder()
    .AddHangfireInstrumentation(options =>
    {
        options.RecordException = true;
    })
    .AddConsoleExporter()
    .Build();

DisplayNameFunc

This option allows changing activity display name.

using var tracerProvider = Sdk
    .CreateTracerProviderBuilder()
    .AddHangfireInstrumentation(options =>
    {
        options.DisplayNameFunc = job => $"JOB {job.Id}";
    })
    .AddConsoleExporter()
    .Build();

If not configured the default is

$"JOB {BackgroundJob.Job.Type.Name}.{BackgroundJob.Job.Method.Name}"

Filter

This option can be used to filter out activities based on the BackgroundJob being executed. The Filter function should return true if the telemetry is to be collected, and false if it should not.

The following code snippet shows how to use Filter to filter out traces for job with a specified job id.

using var tracerProvider = Sdk
    .CreateTracerProviderBuilder()
    .AddHangfireInstrumentation(options =>
    {
        options.Filter = job => job.Id == "Filter this job";
    })
    .AddConsoleExporter()
    .Build();

References

• OpenTelemetry Project
• Hangfire Project