Worker services

Foveus can be used in .NET Worker Service and BackgroundService applications. Worker services do not have an ASP.NET HTTP middleware pipeline, so setup is slightly different from an HTTP API, and a worker has no execution boundary of its own. You mark where each unit of work starts and ends with BeginExecution. Use Foveus in worker services to capture:

ILogger logs
logged exceptions
outbound HTTP telemetry
metrics
one execution per unit of work, when you mark it with BeginExecution
trace propagation on outbound HTTP
SDK shutdown flushing
MassTransit consumers, when instrumentation is configured

Install the SDK

Install the Foveus SDK package.

dotnet add package Foveus.SDK

If your worker uses Serilog, also install the Serilog integration.

dotnet add package Foveus.Serilog

During private beta, your package names or package source may be different. Use the package names and feed URL provided during onboarding.

Basic setup

Add Foveus to your worker host.

using Foveus.SDK.Extensions;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddFoveus(builder.Configuration);

builder.Services.AddHostedService<Worker>();

var host = builder.Build();

await host.RunAsync();

Do not call app.UseFoveus() in a worker service. It is ASP.NET Core middleware and only applies to HTTP applications. If the Foveus configuration is invalid (for example a missing or malformed API key), Foveus disables itself, writes a diagnostic to the console and to your application’s logs, and the worker keeps running without Foveus telemetry.

Configure the worker

Add a Foveus section to your configuration.

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "billing-worker"
  }
}

The key decides the mode: a fov_test_ key sends to Test mode and a fov_live_ key sends to Live mode. There is no separate mode setting. Environment is a label for your deployment. When you do not set it, it is test or live, taken from the key. Source is detected automatically; set it to worker only if detection picks the wrong value.

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "ServiceName": "billing-worker",
    "Environment": "production",
    "Source": "worker"
  }
}

Execution boundaries for worker jobs

A BackgroundService runs for the whole life of the process, so Foveus cannot tell where one piece of its work ends and the next begins. Mark each unit of work — one loop iteration, one job pass, one batch — with BeginExecution.

BeginExecution requires Foveus.SDK 1.1.0-beta.18 or later.

using Foveus.SDK.Metrics;

public sealed class InvoiceSyncWorker : BackgroundService
{
    private readonly IMetricsCollector _metrics;
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly ILogger<InvoiceSyncWorker> _logger;

    public InvoiceSyncWorker(
        IMetricsCollector metrics,
        IHttpClientFactory httpClientFactory,
        ILogger<InvoiceSyncWorker> logger)
    {
        _metrics = metrics;
        _httpClientFactory = httpClientFactory;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            using (var execution = _metrics.BeginExecution("invoice-sync.pass"))
            {
                try
                {
                    var client = _httpClientFactory.CreateClient("billing-provider");
                    await client.GetAsync("/invoices/pending", stoppingToken);
                    _logger.LogInformation("Invoice sync pass completed");
                }
                catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
                {
                    execution.MarkCancelled();
                    throw;
                }
                catch (Exception ex)
                {
                    execution.MarkFailed();
                    _logger.LogError(ex, "Invoice sync pass failed in execution {ExecutionId}", execution.ExecutionId);
                }
            }

            await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
        }
    }
}

Each scope is one execution:

It gets its own execution id and appears in the dashboard with trigger job, the name you gave it, and its measured duration.
Logs, logged exceptions, outbound HttpClient calls and metrics recorded inside the scope belong to it. Outbound calls appear as its child executions.
Its status is failed when you call MarkFailed() or log an exception inside it, degraded when you call MarkCancelled(), and success otherwise.
Disposing the scope ends the execution and restores the previous context, so the next iteration gets a new execution.
A scope started while another execution is active (an HTTP request, or an outer scope) is recorded as that execution’s child.
Concurrent workers each get their own execution; scopes do not leak between them.

Enter the scope in the method that does the work (using var execution = ... or a using block), not inside a callback. Then the worker’s own catch block — the line an on-call engineer reads first — still runs inside the execution.

Without a scope

Work done outside any execution is still captured, but it is not grouped:

logs are recorded without an execution id;
each logged exception becomes its own single-event execution, so an Issue counts every failure;
each outbound HTTP call is recorded as its own root execution;
custom metrics are recorded without an execution.

Foveus never invents a long-lived execution for a worker.

What works today

Capability	Status
`ILogger` logs	Supported
Logged exceptions (become Issues)	Supported
Outbound `HttpClient` telemetry through `IHttpClientFactory`	Supported
Trace and execution header propagation on outbound HTTP	Supported
One execution per unit of work with `BeginExecution`	Supported (SDK 1.1.0-beta.18+)
SDK shutdown flushing	Supported
MassTransit consumers as executions	Supported when `AddFoveusInstrumentation` is configured
Automatic execution boundaries for arbitrary worker loops	Not supported: use `BeginExecution`
Scheduler, cron or Hangfire job identity	Not supported
Linking work claimed from a database to the request that created it	Not supported: they are separate executions

Outbound HTTP telemetry

Foveus instruments outbound HttpClient calls created through IHttpClientFactory.

builder.Services.AddHttpClient("billing-provider", client =>
{
    client.BaseAddress = new Uri("https://billing.example.com");
});

Inside a BeginExecution scope, each call is recorded as a child of that execution and carries trace and execution headers to the service it calls.

MassTransit instrumentation

When configuring MassTransit, call AddFoveusInstrumentation:

builder.Services.AddMassTransit(x =>
{
    x.UsingRabbitMq((context, cfg) =>
    {
        cfg.AddFoveusInstrumentation(context);

        cfg.ConfigureEndpoints(context);
    });
});

Each consumed message then becomes an execution, linked to the request that published it when the publisher is instrumented too.

Message retries are not shown as separate attempts yet: a message that is retried appears as one execution. Consumer executions do not record a duration yet. MassTransit instrumentation is not automatic; the application must call cfg.AddFoveusInstrumentation(context). Verified with MassTransit’s in-memory transport; a RabbitMQ broker has not been tested.

Serilog workers

If your worker uses Serilog, use Foveus.Serilog.

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "billing-worker",
    "EnableFoveusLoggerProvider": false
  }
}

using Foveus.SDK.Extensions;
using Foveus.Serilog;
using Serilog;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddFoveus(builder.Configuration);

builder.Services.AddSerilog((services, loggerConfiguration) =>
{
    loggerConfiguration
        .ReadFrom.Configuration(builder.Configuration)
        .ReadFrom.Services(services)
        .WriteTo.Foveus(services);
});

builder.Services.AddHostedService<Worker>();

var host = builder.Build();

await host.RunAsync();

Set EnableFoveusLoggerProvider to false in Serilog-first apps to avoid duplicate logs. BeginExecution works the same way with Serilog.

The Serilog sink sends logs. Exceptions logged through Serilog are not turned into Issues; exceptions logged through ILogger with the Foveus logger provider are.

See Serilog integration.

Troubleshooting

Logs do not appear

Check that:

AddFoveus(builder.Configuration) is called
the startup log does not say Foveus is disabled: — if it does, fix the reason it gives
the dashboard is showing the mode that matches your key (fov_test_ or fov_live_)
the worker is actually writing logs, at a level that is enabled
the service can reach Foveus

Logs are duplicated

If the worker uses Serilog, disable the built-in Foveus logger provider with "EnableFoveusLoggerProvider": false.

Worker jobs do not show as separate executions

Wrap each unit of work in BeginExecution. Without it, logs have no execution and each outbound call is its own root execution.

Outbound HTTP is not captured

Check that:

the worker uses IHttpClientFactory
Foveus is registered before clients are created
the call is not excluded by configuration

What to do next

Configure the SDK: SDK configuration
Use Serilog: Serilog integration
Review FoveusOptions: FoveusOptions
Review performance overhead: Performance overhead

Start here

Get started

Core concepts

Guides

SDK

Security and data

API reference

Worker services

Install the SDK

Basic setup

Configure the worker

Execution boundaries for worker jobs

Without a scope

What works today

Outbound HTTP telemetry

MassTransit instrumentation

Serilog workers

Troubleshooting

Logs do not appear

Logs are duplicated

Worker jobs do not show as separate executions

Outbound HTTP is not captured

What to do next