Foveus options

FoveusOptions controls how the Foveus SDK identifies your service, captures telemetry, sends data, protects sensitive values, and tunes performance. Most applications should configure these options from appsettings.json.

builder.Services.AddFoveus(builder.Configuration);

Then add a Foveus section to your configuration.

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

You do not need to construct FoveusOptions manually for most services.

Reading Source, HttpTimeout, MaxRetryAttempts, RetryBaseDelay and MaxBodyCaptureSizeBytes from configuration, masking redacted query-string parameters, and disabling Foveus with a diagnostic when configuration is invalid all require Foveus.SDK 1.1.0-beta.18 or later. Earlier versions ignore those five keys and use the defaults, store query strings as sent, and throw at startup on invalid configuration.

Core options

Option	Default	Description
`ApiKey`	None	Your Foveus API key. Required. Its prefix decides the mode: `fov_test_` sends to Test, `fov_live_` to Live.
`ServiceName`	Project assembly name	The service name shown in Foveus.
`Environment`	`test` or `live`, from the key	A free-text label for the deployment, such as `staging` or `production`. Not the ASP.NET Core environment.
`ApiEndpoint`	`https://foveus.onrender.com`	The Foveus backend endpoint, the same for every key. Override it for a local or private backend.
`ServiceVersion`	Assembly version	The application version. Useful for investigating regressions after deployment.
`Source`	Auto-detected	The source type, such as `web`, `worker`, or `console`. Read from configuration only by the SDK version in the note above.

There is no Mode option. The API key decides the mode. 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, writes Foveus is disabled: <reason> to the console and to your application’s log, and your application keeps running without Foveus telemetry.

API key

ApiKey is required.

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

Test keys are created automatically during onboarding. Live keys are not self-serve during private beta. They are issued by the Foveus team.

ServiceName

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

Override this when your assembly name is not the name your team wants to see in Foveus.

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

Mode

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

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

Do not use a live key in local development.

Capture profiles

CaptureProfile lets you quickly tune capture behavior.

Profile	Best for	Behavior
`Balanced`	Normal production usage. The default.	The defaults in the tables below: batch size 100 every 5 s, context sampling 1%, request body capture on, response body capture 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 production services	Body capture 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 carefully. It can capture more context than you usually want in production.

Transport options

Transport options control how the SDK batches and sends telemetry to Foveus.

Option	Default	Description
`BatchSize`	`100`	Number of telemetry items to collect before sending.
`BatchInterval`	`5s`	Maximum wait before sending a partial batch.
`HttpTimeout`	`30s`	Timeout for calls to Foveus.
`MaxRetryAttempts`	`3`	Number of retry attempts.
`RetryBaseDelay`	`1s`	Base retry delay used for backoff.

HttpTimeout, MaxRetryAttempts and RetryBaseDelay are read from configuration only by the SDK version in the note at the top of this page. See Performance overhead for what happens when Foveus is unreachable. Example:

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "BatchSize": 100,
    "BatchInterval": "00:00:05",
    "HttpTimeout": "00:00:30",
    "MaxRetryAttempts": 3,
    "RetryBaseDelay": "00:00:01"
  }
}

Data capture options

Data capture options control what context the SDK captures.

Option	Default	Description
`CaptureRequestBodies`	`true`	Captures request body context.
`CaptureResponseBodies`	`false`	Captures response body context.
`StoreSanitizedResponsePreview`	`false`	Allows sanitized response previews when response capture is enabled.
`CaptureExceptionContext`	`true`	Captures exception details and related context.
`MaxBodyCaptureSizeBytes`	`65536`	Maximum body size captured (64 KB). Bodies are redacted before they are truncated. Read from configuration only by the SDK version in the note above.
`ContextSamplingRate`	`0.01`	Fraction of successful requests whose context is captured. Failed requests always capture context.
`ExcludedPathPrefixes`	Empty	Path prefixes to skip.
`ExcludedExactPaths`	Empty	Exact paths to skip.
`IncludedPathPrefixes`	Empty	If set, only matching path prefixes are captured.

Example:

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "CaptureRequestBodies": true,
    "CaptureResponseBodies": false,
    "ContextSamplingRate": 0.01,
    "ExcludedPathPrefixes": ["/health", "/metrics"],
    "ExcludedExactPaths": ["/healthz"]
  }
}

Request body capture

Request body capture helps you understand what the client sent.

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

Request body capture is useful for debugging API behavior, but you should still avoid sending sensitive data.

Response body capture

Response body capture helps you inspect business outcomes and provider responses.

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

Response bodies often contain sensitive data. Enable this intentionally and review redaction settings first.

Context sampling

ContextSamplingRate controls 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%. Increase it when debugging. Lower it for high-volume services.

Path filtering

Use path filters to reduce noise.

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

Use this for endpoints such as:

/health
/metrics
/ready
/live

Use IncludedPathPrefixes when you want allow-list behavior.

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "IncludedPathPrefixes": ["/api"]
  }
}

Privacy options

Privacy options control what Foveus masks or avoids storing.

Option	Default	Description
`RedactedHeaders`	See below	Extra header names to mask, added to the defaults.
`RedactedFields`	See below	Extra JSON field names to mask, added to the defaults.
`AnonymizeIpAddresses`	`true`	Zeroes the last octet of an IPv4 client address, or the last 80 bits of an IPv6 address.

Default redacted headers: Authorization, Cookie, Set-Cookie, X-API-Key, X-Auth-Token, Authentication. Default redacted fields: 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, otp. Field names match exactly, ignoring case: password is redacted, userPassword is not. In captured JSON bodies, a string, number, boolean or null value is replaced with "***"; an object or array under a redacted key is not masked. A query-string parameter whose name is a redacted field is 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. Example:

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "RedactedFields": ["nationalId", "accountNumber"],
    "RedactedHeaders": ["x-internal-secret"]
  }
}

Redaction is a safety layer, not a reason to intentionally send secrets. Avoid capturing sensitive data whenever possible.

Performance options

Performance options help tune the SDK for high-volume services.

Option	Default	Description
`MaxQueueSize`	`10000`	Maximum in-memory queue size, per telemetry type. Telemetry beyond it is dropped and counted as lost.
`EnableMetricsPreAggregation`	`false`	Aggregates metrics before sending.
`MetricsAggregationInterval`	`1 minute`	Metric aggregation window.

Example:

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "MaxQueueSize": 10000,
    "EnableMetricsPreAggregation": true,
    "MetricsAggregationInterval": "00:01:00"
  }
}

Use HighThroughput profile for busy services where low overhead matters.

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "CaptureProfile": "HighThroughput"
  }
}

Debugging options

Debugging options help you troubleshoot SDK behavior.

Option	Default	Description
`EnableDebugLogging`	`false`	Emits SDK debug logs.
`EnableFoveusLoggerProvider`	`true`	Registers Foveus as an `ILogger` provider.
`EnableConsoleOutput`	Auto-detected	Shows SDK console output when appropriate.
`EnableSelfMonitoring`	`true`	Emits SDK health and performance metrics.

Example:

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "EnableDebugLogging": true,
    "EnableConsoleOutput": true
  }
}

Use debug logging temporarily. Turn it off when you are done troubleshooting.

Outcome semantics options

Outcome semantics help Foveus understand whether an execution succeeded, failed, or returned a business-level failure.

Option	Description
`ProviderDetection`	Infers external provider names from outbound requests. Not read from configuration.
`OperationDetection`	Infers operation names from outbound calls. Not read from configuration.
`OutcomeSemantics`	Local rules for interpreting provider outcomes, read from the `Foveus:OutcomeSemantics` configuration section.

Use outcome semantics when HTTP status alone is not enough. For example, a provider may return HTTP 200 with a response body that means the operation failed. Outcome semantics can help Foveus classify that execution correctly.

Recommended setups

Local development

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

Normal production service

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

High-volume service

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "ServiceName": "orders-api",
    "Environment": "production",
    "CaptureProfile": "HighThroughput",
    "ContextSamplingRate": 0.001,
    "CaptureRequestBodies": false,
    "CaptureResponseBodies": false,
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}

Sensitive API

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "ServiceName": "orders-api",
    "Environment": "production",
    "CaptureProfile": "Balanced",
    "CaptureResponseBodies": false,
    "ContextSamplingRate": 0.01,
    "RedactedFields": ["nationalId", "accountNumber"]
  }
}

Configuring options

Set options in the Foveus configuration section, not in code:

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "orders-api",
    "CaptureProfile": "Balanced",
    "CaptureRequestBodies": true,
    "CaptureResponseBodies": false,
    "ContextSamplingRate": 0.01
  }
}

builder.Services.AddFoveus(builder.Configuration);

Any configuration source works, including environment variables such as Foveus__ApiKey and your secret manager.

Troubleshooting

I changed an option but behavior did not change

Check that:

the Foveus section is correctly named
the app is loading the expected configuration file
environment variables are not overriding your values
the service was restarted after config changes
the option name matches the SDK property name
the option is read from configuration by your SDK version (see the note at the top of this page)
the startup log does not contain Foveus is disabled:

Response body context is missing

Check that:

CaptureResponseBodies is enabled
the response body size is within MaxBodyCaptureSizeBytes
the response content type is supported
the path is not excluded
sampling did not skip the context snapshot
redaction did not remove the value

Too much telemetry is being sent

Use one or more of:

CaptureProfile: "HighThroughput"
lower ContextSamplingRate
ExcludedPathPrefixes
CaptureRequestBodies: false
CaptureResponseBodies: false

Next steps

Configure the SDK: SDK configuration
Review redaction: Redaction
Review performance overhead: Performance overhead
Learn about Execution Context Search: Execution Context Search

Start here

Get started

Core concepts

Guides

SDK

Security and data

API reference

Foveus options

Core options

API key

ServiceName

Environment

Mode

Capture profiles

Transport options

Data capture options

Request body capture

Response body capture

Context sampling

Path filtering

Privacy options

Performance options

Debugging options

Outcome semantics options

Recommended setups

Local development

Normal production service

High-volume service

Sensitive API

Configuring options

Troubleshooting

I changed an option but behavior did not change

Response body context is missing

Too much telemetry is being sent

Next steps