Configuration - Foveus

Configure the Foveus .NET SDK to control how your service sends telemetry. For most services, you only need to pass your API key.

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

Then add the middleware:

app.UseFoveus();

With this setup, Foveus uses safe defaults:

Option	Default
`ServiceName`	Project assembly name
`Environment`	Current app environment
`Mode`	`test`

Override these values only when you need more control.

Configuration methods

You can configure Foveus in three common ways:

Method	Use when
Minimal setup	You want to connect quickly with an API key.
Configuration-based setup	You want to use `appsettings.json`, environment variables, or a secret manager.
Options-based setup	You want to configure values directly in code.

Minimal setup

Use minimal setup for local development, sandbox testing, or quick validation.

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

Then add the middleware:

app.UseFoveus();

Do not hardcode API keys in production code. Use this only for local testing or quick validation.

Configuration-based setup

For most applications, configure Foveus from appsettings.json, environment variables, or your secret manager.

builder.Services.AddFoveus(builder.Configuration);

Add a Foveus section to your configuration.

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

Foveus still uses the default service name, environment, and mode unless you override them. You can override defaults when needed:

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

For live telemetry, use a live key and set Mode to live.

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

Options-based setup

Use options-based setup when you want to configure the SDK directly in code.

builder.Services.AddFoveus(options =>
{
    options.ApiKey = builder.Configuration["Foveus:ApiKey"];
});

Override defaults when needed:

builder.Services.AddFoveus(options =>
{
    options.ApiKey = builder.Configuration["Foveus:ApiKey"];
    options.ServiceName = "orders-api";
    options.Environment = "staging";
});

For live telemetry:

builder.Services.AddFoveus(options =>
{
    options.ApiKey = builder.Configuration["Foveus:ApiKey"];
    options.ServiceName = "orders-api";
    options.Environment = "production";
    options.Mode = "live";
});

Core options

Option	Required?	Default	Description
`ApiKey`	Yes	None	Your Foveus API key. Test keys are created automatically during onboarding. Live keys are created from Settings.
`ServiceName`	No	Project assembly name	The service name shown in Foveus. Override this when your assembly name is not the name your team uses.
`Environment`	No	Current app environment	The deployment environment, such as `Development`, `staging`, or `production`.
`Mode`	No	`test`	The Foveus data mode. Set this to `live` only when using a live key for production telemetry.

Service name

ServiceName identifies the service producing telemetry. If you do not set it, Foveus uses your project assembly name.

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

Foveus works with your existing service naming convention. Override ServiceName only when the default is not what you want to see in the dashboard.

Environment

Environment describes where your service is running. If you do not set it, Foveus uses the current app environment.

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "Environment": "staging"
  }
}

Examples:

Development
test
staging
production

Mode

Mode controls the Foveus telemetry boundary. Foveus defaults to Test mode. You only need to set Mode when sending live telemetry.

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live"
  }
}

Use a live key with Live mode. Do not use live keys in local development.

Middleware

For ASP.NET Core APIs, add the Foveus middleware.

app.UseFoveus();

The middleware captures HTTP executions. Place it after middleware that sets request context, authentication, or correlation IDs if your service depends on those values.

Advanced options

Most SDK options can also be configured from appsettings.json under the Foveus section. Use this when you want to tune capture behavior, performance, redaction, batching, or path filtering without constructing options manually in code.

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "orders-api",
    "CaptureProfile": "Balanced",
    "CaptureRequestBodies": true,
    "CaptureResponseBodies": false,
    "ContextSamplingRate": 0.01,
    "ExcludedPathPrefixes": ["/health", "/metrics"],
    "RedactedFields": ["nationalId", "accountNumber"]
  }
}

Then load the configuration:

builder.Services.AddFoveus(builder.Configuration);

You do not need to construct FoveusOptions directly for most services. Use appsettings.json or environment variables when you want configuration outside code.

For the full list of SDK options, see FoveusOptions.

Capture profiles

CaptureProfile lets you quickly tune how much telemetry Foveus captures. Common profiles include:

Profile	Use for
`Balanced`	Normal production usage.
`Debug`	Local development or deep troubleshooting.
`HighThroughput`	Busy services where low overhead is more important than detailed context capture.

Example:

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

Use Debug only when you need deeper local troubleshooting. It can capture more context than you usually want in production.

Capture behavior

The SDK can capture telemetry such as:

HTTP executions
request metadata
response metadata
request query values
request body context
response body context
logs, if logging integration is configured
outcome and failure evidence

The exact data captured depends on SDK settings, framework support, capture profile, and safety controls.

Request and response bodies

You can control whether Foveus captures request and response body context.

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "CaptureRequestBodies": true,
    "CaptureResponseBodies": false
  }
}

Request body capture is useful for debugging API behavior. Response body capture can be useful for business outcome analysis, but responses often contain sensitive data. Review your redaction settings before enabling it broadly.

Sampling

Use ContextSamplingRate to control how often successful context snapshots are captured.

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ContextSamplingRate": 0.01
  }
}

A value of 0.01 means 1%. Use a higher sampling rate while debugging. Use a lower rate for high-volume production services.

Path filtering

Use path filters to reduce noise or exclude endpoints you do not want to capture.

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}

This is useful for endpoints such as:

/health
/metrics
/ready
/live

Redaction

Foveus applies safety controls before storing or indexing context. You can add domain-specific fields to the redaction list.

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

Sensitive fields such as passwords, tokens, authorization headers, cookies, secrets, and card values should not be stored or indexed. Still, avoid sending sensitive data when possible. See Redaction for details.

Production setup

For production, use:

a live API key
Mode: "live"
a service name your team recognizes
a production environment label
a secret manager for API keys
conservative capture and redaction settings

Example:

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

Troubleshooting

No executions appear

Check that:

ApiKey is set
your service can reach Foveus
app.UseFoveus() is registered
you are viewing the right mode in the dashboard
your time range includes the request
your service name matches your search

Service name looks wrong

If the service name appears as your project assembly name and you want a different name, set ServiceName.

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

Telemetry appears in Test mode

Foveus defaults to Test mode. If you are sending production telemetry, set Mode to live.

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live"
  }
}

Context search does not find a field

Check that:

the field was captured in request, response, query, or custom context
the value is scalar
the value was ingested after context indexing was enabled
the key is not blocked by safety policy
the field is within capture and indexing limits

Next steps

Install the .NET SDK: Install the .NET SDK
Learn about services and environments: Services and environments
Search by context: Execution Context Search
Review FoveusOptions: FoveusOptions
Review redaction: Redaction

​Configuration methods

​Minimal setup

​Configuration-based setup

​Options-based setup

​Core options

​Service name

​Environment

​Mode

​Middleware

​Advanced options

​Capture profiles

​Capture behavior

​Request and response bodies

​Sampling

​Path filtering

​Redaction

​Production setup

​Troubleshooting

​No executions appear

​Service name looks wrong

​Telemetry appears in Test mode

​Context search does not find a field

​Next steps

Configuration methods

Minimal setup

Configuration-based setup

Options-based setup

Core options

Service name

Environment

Mode

Middleware

Advanced options

Capture profiles

Capture behavior

Request and response bodies

Sampling

Path filtering

Redaction

Production setup

Troubleshooting

No executions appear

Service name looks wrong

Telemetry appears in Test mode

Context search does not find a field

Next steps