> ## Documentation Index
> Fetch the complete documentation index at: https://docs.foveus.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

```csharp theme={null}
builder.Services.AddFoveus(builder.Configuration);
```

Then add a `Foveus` section to your configuration.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}
```

Use this for endpoints such as:

```text theme={null}
/health
/metrics
/ready
/live
```

Use `IncludedPathPrefixes` when you want allow-list behavior.

```json theme={null}
{
  "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:

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "RedactedFields": ["nationalId", "accountNumber"],
    "RedactedHeaders": ["x-internal-secret"]
  }
}
```

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

## 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:

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "MaxQueueSize": 10000,
    "EnableMetricsPreAggregation": true,
    "MetricsAggregationInterval": "00:01:00"
  }
}
```

Use `HighThroughput` profile for busy services where low overhead matters.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "CaptureProfile": "Debug"
  }
}
```

### Normal production service

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

### High-volume service

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```csharp theme={null}
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](/sdk/configuration)
* Review redaction: [Redaction](/sdk/redaction)
* Review performance overhead: [Performance overhead](/sdk/performance-overhead)
* Learn about Execution Context Search: [Execution Context Search](/concepts/execution-context-search)