Skip to main content
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 can capture logs, exceptions, outbound HTTP telemetry, metrics, and trace propagation.

​
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.

​
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:
OptionDefault
ServiceNameProject assembly name
EnvironmentCurrent app environment
Modetest
You can override these values later.

​
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"
  }
}
For production telemetry, use a live key and set Mode to live. 
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "ServiceName": "orders-api",
    "Environment": "production",
    "Mode": "live"
  }
}

​
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
  • metrics
  • SDK health and performance signals

​
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",
    "Source": "worker"
  }
}
For worker services, Foveus can capture:
  • ILogger logs
  • logged exceptions
  • outbound HTTP telemetry
  • metrics
  • trace propagation
  • SDK shutdown flushing
  • supported messaging instrumentation hooks
Full automatic per-job execution capture for arbitrary BackgroundService loops is not yet implemented. See Worker services.

​
Request and response context

Foveus can capture structured request and response context. 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.
ProfileUse for
BalancedNormal production usage.
DebugLocal development or deep troubleshooting.
HighThroughputBusy services where low overhead matters most.
Example: 
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "CaptureProfile": "Balanced"
  }
}

​
Redaction and safety

Foveus applies redaction and safety controls before storing or indexing context. You can add domain-specific redacted fields. 
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "RedactedFields": ["nationalId", "accountNumber"]
  }
}
Sensitive values such as passwords, tokens, authorization headers, cookies, secrets, and card values should not be stored or indexed.
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_...",
    "Mode": "live",
    "CaptureProfile": "HighThroughput",
    "ContextSamplingRate": 0.001,
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}

​
Common setup

​
Local development

{
  "Foveus": {
    "ApiKey": "fov_test_..."
  }
}
Foveus uses Test mode by default.

​
Staging

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

​
Production API

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

​
Production worker

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

​
Troubleshooting

​
No executions appear

Check that:
  • the API key is configured
  • 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 for arbitrary BackgroundService loops today. Foveus can capture worker logs, exceptions, outbound HTTP telemetry, metrics, and trace propagation, but full automatic per-job execution capture is still evolving. Use structured lifecycle logs or supported messaging instrumentation.

​
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