Configuration

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`	`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. Override these values only when you need more control.

Some behaviour on this page requires Foveus.SDK 1.1.0-beta.18 or later: disabling Foveus on invalid configuration (earlier versions throw at startup), reading Source, HttpTimeout, MaxRetryAttempts, RetryBaseDelay and MaxBodyCaptureSizeBytes from configuration (earlier versions ignore them), and masking redacted query-string parameters.

Configuration methods

You can configure Foveus in two 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.

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 and environment unless you override them. The key decides the mode. You can override defaults when needed:

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

For live telemetry, use a live key.

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

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.

Core options

Option	Required?	Default	Description
`ApiKey`	Yes	None	Your Foveus API key. Its prefix decides the mode. Test keys are created during onboarding. Live keys are issued by the Foveus team.
`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	`test` or `live`, from the key	A free-text label for the deployment, such as `staging` or `production`. It is not the ASP.NET Core environment.
`ApiEndpoint`	No	`https://foveus.onrender.com`	The Foveus ingestion endpoint. Override it only for a local or private backend.

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 is a free-text label that describes where your service is running. If you do not set it, it is test or live, taken from the API key. It is not read from the ASP.NET Core environment.

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

Examples:

development
test
staging
production

Mode

The mode is the Foveus telemetry boundary. The API key decides it: a fov_test_ key sends to Test mode and a fov_live_ key sends to Live mode. There is no Mode setting. To send live telemetry, use a live key:

{
  "Foveus": {
    "ApiKey": "fov_live_..."
  }
}

During private beta, live keys are issued by the Foveus team. 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. Source, HttpTimeout, MaxRetryAttempts, RetryBaseDelay and MaxBodyCaptureSizeBytes are read from configuration only by the SDK version noted at the top of this page. 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. Profiles:

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 is more important than detailed context capture.	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"
  }
}

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. Failed requests always capture context.

{
  "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

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 fields to the redaction list.

{
  "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. Avoid sending sensitive data when possible. See Redaction for details.

Production setup

For production, use:

a live API key
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",
    "CaptureProfile": "Balanced",
    "CaptureResponseBodies": false,
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}

Troubleshooting

No executions appear

Check that:

ApiKey is set
the startup log does not contain Foveus is disabled: — if it does, fix the reason it gives
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

The service is using a fov_test_ key. A test key always sends to Test mode, whatever Environment is set to. If you are sending production telemetry, use a live key.

{
  "Foveus": {
    "ApiKey": "fov_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

Start here

Get started

Core concepts

Guides

SDK

Security and data

API reference

Configuration methods

Minimal setup

Configuration-based setup

Invalid configuration

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