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.

Core options

Option	Default	Description
`ApiKey`	None	Your Foveus API key. Required.
`ServiceName`	Project assembly name	The service name shown in Foveus.
`Environment`	Current app environment	The deployment environment, such as `Development`, `staging`, or `production`.
`Mode`	`test`	The Foveus telemetry mode. Set to `live` when using a live key.
`ApiEndpoint`	Selected automatically	The Foveus backend endpoint. Override for local backend, staging, or private deployments.
`ServiceVersion`	Assembly version	The application version. Useful for investigating regressions after deployment.
`Source`	Auto-detected	The source type, such as `web`, `worker`, or `console`.

API key

ApiKey is required.

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

Test keys are created automatically during onboarding. Live keys are created manually from Settings.

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 describes where your service is running. If you do not set it, Foveus uses the current app environment.

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

Mode

Mode controls the Foveus data boundary. Foveus defaults to Test mode. Set Mode only when sending live telemetry.

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

Use a live key with Live mode. 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	Moderate batching, low context sampling, request body capture on, response body capture off.
`Debug`	Local development or deep troubleshooting	Captures more context, enables response bodies, debug logs, and console output.
`HighThroughput`	Busy production services	Larger queues and batches, low context sampling, body capture disabled, metrics pre-aggregation on.

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.

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`	Depends on response capture	Allows sanitized response previews when response capture is enabled.
`CaptureExceptionContext`	`true`	Captures exception details and related context.
`MaxBodyCaptureSizeBytes`	`65536`	Maximum body size captured.
`ContextSamplingRate`	`0.01`	Fraction of successful context snapshots captured.
`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.

{
  "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`	Common sensitive headers	Headers to mask. Defaults include authorization, cookie, token, and API key headers.
`RedactedFields`	Common sensitive fields	JSON field names to mask. Defaults include password, token, email, phone, and address-like fields.
`AnonymizeIpAddresses`	`true`	Masks or anonymizes IP addresses.

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 telemetry queue size.
`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.
`OperationDetection`	Infers operation names from outbound calls.
`OutcomeSemantics`	Local rules for interpreting provider outcomes.

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

High-volume service

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

Sensitive API

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

Options-based configuration

You can also configure Foveus directly in code.

builder.Services.AddFoveus(options =>
{
    options.ApiKey = builder.Configuration["Foveus:ApiKey"];
    options.ServiceName = "orders-api";
    options.CaptureProfile = "Balanced";
    options.CaptureRequestBodies = true;
    options.CaptureResponseBodies = false;
    options.ContextSamplingRate = 0.01;
});

Use this when configuration values are computed in code. For most services, prefer appsettings.json or environment variables.

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

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

​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

​Options-based configuration

​Troubleshooting

​I changed an option but behavior did not change

​Response body context is missing

​Too much telemetry is being sent

​Next steps

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

Options-based configuration

Troubleshooting

I changed an option but behavior did not change

Response body context is missing

Too much telemetry is being sent

Next steps