Dotnet

Use the Foveus .NET SDK to connect your .NET service to Foveus. The SDK captures execution telemetry from your application and sends it to your Foveus workspace. For an ASP.NET Core API, this usually means capturing one execution per HTTP request. For workers and background services, Foveus captures logs, exceptions, outbound HTTP telemetry, metrics, and trace propagation. A worker has no execution boundary of its own: mark each unit of work with BeginExecution to record it as one execution. See Worker services.

Install the SDK

Install the package in your service.

dotnet add package Foveus.SDK

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

Supported .NET versions

The SDK targets netstandard2.0, net6.0 and net8.0.

Host	What works
ASP.NET Core on .NET 6 or later	Everything on this page, including the `UseFoveus()` middleware
`netstandard2.0` hosts	Logging, outbound HTTP telemetry and metrics. No `UseFoveus()` middleware.
.NET Framework	Not tested

The SDK has been runtime-tested on a .NET 10 host.

Several behaviours on this page require Foveus.SDK 1.1.0-beta.18 or later: disabling Foveus on invalid configuration, flushing queued telemetry on shutdown, BeginExecution, masking redacted query-string parameters, and reading Source, HttpTimeout, MaxRetryAttempts, RetryBaseDelay and MaxBodyCaptureSizeBytes from configuration. Earlier versions throw at startup on invalid configuration and discard queued telemetry on shutdown.

Minimal setup

For most services, start with your test API key.

builder.Services.AddFoveus("fov_test_...");

Then add the middleware for ASP.NET Core APIs.

app.UseFoveus();

With this setup, Foveus uses safe defaults:

Option	Default
`ServiceName`	Project assembly name
`Environment`	`test` or `live`, taken from the API key

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. You can override these values later.

Invalid configuration

If the API key is missing, empty or malformed, has an unknown prefix, ApiEndpoint is not an http or https URL, or a value is out of range, Foveus disables itself. It writes Foveus is disabled: <reason> to the console and to your application’s log, and your application keeps running without Foveus telemetry. A key that is revoked later is not a startup failure: ingestion requests fail with HTTP 401 at runtime.

Configuration-based setup

For most real applications, load configuration from appsettings.json, environment variables, or your secret manager.

builder.Services.AddFoveus(builder.Configuration);

Example configuration:

{
  "Foveus": {
    "ApiKey": "fov_test_..."
  }
}

Override defaults when needed:

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "orders-api",
    "Environment": "staging"
  }
}

Environment is a free-text label for the deployment. It is not the ASP.NET Core environment. For production telemetry, use a live key.

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "ServiceName": "orders-api",
    "Environment": "production"
  }
}

What the SDK captures

The exact data depends on your configuration and application type. The SDK can capture:

HTTP executions
endpoint and method
request query values
request body context
response body context
execution duration
outcome and failure evidence
exception context
logs, if logging integration is configured
outbound HTTP telemetry for clients created through IHttpClientFactory
consumed MassTransit messages, when cfg.AddFoveusInstrumentation(context) is configured
metrics
SDK health and performance signals

The SDK does not capture database calls, SQL or EF Core, cache operations, Hangfire, Quartz, Kafka or Azure Service Bus. There is no OpenTelemetry integration.

HTTP executions

For ASP.NET Core APIs, the middleware captures requests as executions.

app.UseFoveus();

A request such as:

POST /orders

can appear in Foveus as an execution with:

service name
environment
mode
endpoint
method
duration
status
request context
response context
logs, if configured

Worker services

Foveus can also be used in .NET Worker Service and BackgroundService apps. Worker services use builder.Services.AddFoveus(...), but they do not call app.UseFoveus() because workers do not have an ASP.NET HTTP middleware pipeline. Basic worker setup:

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddFoveus(builder.Configuration);

builder.Services.AddHostedService<Worker>();

var host = builder.Build();

await host.RunAsync();

Example configuration:

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

For worker services, Foveus can capture:

ILogger logs
logged exceptions
outbound HTTP telemetry
metrics
trace propagation
one execution per unit of work, when you mark it with BeginExecution
SDK shutdown flushing
MassTransit consumers, when cfg.AddFoveusInstrumentation(context) is configured

Foveus does not create execution boundaries automatically for arbitrary BackgroundService loops, and it does not capture scheduler, cron or Hangfire job identity. See Worker services.

Request and response context

Foveus can capture structured request and response context. By default, request bodies are captured and response bodies are not (CaptureResponseBodies is false). Context is captured for every failed request and for 1% of successful requests (ContextSamplingRate is 0.01). For example, if your response includes:

{
  "orderStatus": {
    "value": 1,
    "label": "Confirmed"
  }
}

Foveus can index safe scalar fields for search.

service:orders-api context:orderStatus.value=1

Or:

service:orders-api context:orderStatus.label="Confirmed"

Strings should use quotes. Numbers and booleans do not need quotes.

Execution Context Search uses indexed context fields. It does not scan arbitrary raw request or response bodies.

Logs

If logging integration is enabled, Foveus can correlate logs with executions. This helps you inspect logs for one request or operation instead of searching through unrelated log streams. If your service uses Serilog, use the dedicated Serilog integration. See Serilog integration.

Capture profiles

Use CaptureProfile to tune how much telemetry the SDK captures.

Profile	Use for	What it changes
`Balanced`	Normal production usage. The default.	Request bodies on, response bodies off.
`Debug`	Local development or deep troubleshooting.	Batches of 10 every 1 s, context for every request, request and response bodies with a sanitized response preview, debug logging and console output.
`HighThroughput`	Busy services where low overhead matters most.	Bodies off, metrics pre-aggregation on, batch size 500 every 2 s, queue size 50,000, context sampling 0.1%.

Example:

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "CaptureProfile": "Balanced"
  }
}

Redaction and safety

The SDK redacts these headers by default: Authorization, Cookie, Set-Cookie, X-API-Key, X-Auth-Token and Authentication. In captured JSON request and response bodies, it redacts fields with these names by default: password, token, secret, key, creditCard, ssn, email, phone, address, accessToken, access_token, refreshToken, refresh_token, idToken, id_token, apiKey, api_key, clientSecret, client_secret, authorization, cardNumber, cvv, cvc, pin and otp. You can add domain-specific redacted fields.

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "RedactedFields": ["nationalId", "accountNumber"]
  }
}

Field names match exactly, ignoring case: password is redacted, userPassword is not. A string, number, boolean or null value is replaced with "***"; an object or array under a redacted key is not masked. Query-string parameters whose name is a redacted field are stored as ***; other parameters are stored as sent. Earlier SDK versions store the whole query string as sent. Log messages and exception messages are not redacted. See Redaction.

Redaction is a safety layer. Do not intentionally send secrets, credentials, card data, or highly sensitive personal data to Foveus.

Performance controls

The SDK is designed to keep overhead bounded. You can tune:

capture profile
context sampling
request and response body capture
maximum body size
path exclusions
batch size
batch interval
retry settings
queue size

For high-volume services, use HighThroughput or lower the sampling rate.

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "CaptureProfile": "HighThroughput",
    "ContextSamplingRate": 0.001,
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}

Common setup

Local development

{
  "Foveus": {
    "ApiKey": "fov_test_..."
  }
}

The fov_test_ key sends telemetry to Test mode.

Staging

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "orders-api",
    "Environment": "staging"
  }
}

Production API

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "ServiceName": "orders-api",
    "Environment": "production",
    "CaptureProfile": "Balanced",
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}

Production worker

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

Troubleshooting

No executions appear

Check that:

the API key is configured
the startup log does not contain Foveus is disabled: — if it does, fix the reason it gives
the service can reach Foveus
app.UseFoveus() is registered for ASP.NET Core APIs
the dashboard is showing the right mode
the time range includes the request
your service name matches your search

Worker logs appear, but jobs do not show as executions

That is expected when the work is not inside a BeginExecution scope. Foveus does not create execution boundaries for arbitrary BackgroundService loops. Wrap each unit of work in BeginExecution. Without it, logs have no execution and each outbound call is recorded as its own root execution. See Worker services.

The service name looks wrong

If you did not set ServiceName, Foveus uses your project assembly name. Override it if needed.

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "orders-api"
  }
}

Response context is missing

Check that:

response body capture is enabled
the response body is within the capture size limit
the route is not excluded
sampling did not skip the context snapshot
redaction did not mask the field

Too much context is being captured

Use:

ExcludedPathPrefixes
ExcludedExactPaths
lower ContextSamplingRate
CaptureProfile: "HighThroughput"
lower body capture settings

Next steps

Configure the SDK: SDK configuration
Set up worker services: Worker services
Review all options: FoveusOptions
Configure Serilog: Serilog integration
Configure redaction: Redaction
Review performance overhead: Performance overhead
Send your first execution: Send your first execution

Start here

Get started

Core concepts

Guides

SDK

Security and data

API reference

Install the SDK

Supported .NET versions

Minimal setup

Invalid configuration

Configuration-based setup

What the SDK captures

HTTP executions

Worker services

Request and response context

Logs

Capture profiles

Redaction and safety

Performance controls

Common setup

Local development

Staging

Production API

Production worker

Troubleshooting

No executions appear

Worker logs appear, but jobs do not show as executions

The service name looks wrong

Response context is missing

Too much context is being captured

Next steps