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

# Performance overhead

The Foveus SDK is designed to capture useful execution evidence without slowing down your service.

Telemetry capture still has a cost. The SDK manages that cost with batching, sampling, body-size limits, path exclusions, queue limits, retries, and capture profiles.

Use this page to understand the tradeoffs and tune Foveus for your service.

## What creates overhead

The main sources of SDK overhead are:

* capturing request and response context
* reading request or response bodies
* serializing telemetry
* redacting sensitive fields
* writing to the local telemetry queue
* batching and sending telemetry to Foveus
* retrying failed sends
* correlating logs with executions

For most services, the default `Balanced` profile is a good starting point.

## Default behavior

A minimal setup is enough for local development or private beta validation.

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

With this setup, Foveus uses defaults for service name, environment, mode, batching, capture, and safety controls.

For production, use configuration so you can tune capture behavior without changing code.

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

## Capture profiles

Use `CaptureProfile` to choose a capture strategy.

| Profile          | Use for               | Behavior                                                                                    |
| ---------------- | --------------------- | ------------------------------------------------------------------------------------------- |
| `Balanced`       | Most services         | Captures useful execution evidence with bounded context, redaction, batching, and sampling. |
| `Debug`          | Local troubleshooting | Captures more context and emits more SDK diagnostics.                                       |
| `HighThroughput` | Busy services         | Reduces capture detail and favors lower overhead.                                           |

Example:

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

## Balanced profile

Use `Balanced` for most production services.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "CaptureProfile": "Balanced",
    "CaptureRequestBodies": true,
    "CaptureResponseBodies": true,
    "ContextSamplingRate": 0.01,
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}
```

This keeps response context available for debugging provider responses, business outcomes, and user complaints, while keeping capture bounded by sampling, redaction, body-size limits, and retention.

## Debug profile

Use `Debug` when you are troubleshooting locally or investigating a specific service behavior.

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

Debug mode can capture more context than you usually want in production.

Use it temporarily.

## High-throughput profile

Use `HighThroughput` for services where lower overhead matters more than detailed context.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "CaptureProfile": "HighThroughput",
    "ContextSamplingRate": 0.001,
    "CaptureRequestBodies": false,
    "CaptureResponseBodies": false,
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}
```

This setup reduces body capture and lowers successful context sampling.

You still get execution metadata, timing, outcomes, and failures, but less request and response context.

## Sampling

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

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "ContextSamplingRate": 0.01
  }
}
```

A value of `0.01` means 1%.

Sampling is useful because successful traffic can be high-volume. You can capture enough successful context for debugging patterns without storing every successful payload.

Failures should still preserve enough evidence to investigate, depending on your SDK and capture settings.

## Request and response body capture

Request and response body capture are useful for debugging.

They also create overhead because the SDK needs to read, sanitize, truncate, and serialize context.

For most production services, keep body capture enabled only with safety controls:

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "CaptureRequestBodies": true,
    "CaptureResponseBodies": true,
    "ContextSamplingRate": 0.01,
    "MaxBodyCaptureSizeBytes": 65536,
    "RedactedFields": ["nationalId", "accountNumber"],
    "ExcludedPathPrefixes": ["/health", "/metrics"]
  }
}
```

Use response body capture when you need to inspect what your service or a third-party provider returned.

Disable body capture for highly sensitive or very high-volume services:

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "CaptureRequestBodies": false,
    "CaptureResponseBodies": false
  }
}
```

## Body size limits

Use `MaxBodyCaptureSizeBytes` to prevent large payloads from creating excessive overhead.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "MaxBodyCaptureSizeBytes": 65536
  }
}
```

Large request or response bodies should be truncated or skipped depending on SDK behavior.

Use path exclusions for endpoints that return large payloads.

## Path exclusions

Exclude noisy or low-value endpoints.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "ExcludedPathPrefixes": ["/health", "/metrics", "/ready", "/live"]
  }
}
```

Common exclusions:

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

For sensitive services, exclude authentication or credential-related paths.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "ExcludedPathPrefixes": ["/auth", "/health", "/metrics"]
  }
}
```

## Batching

The SDK batches telemetry before sending it to Foveus.

Batching reduces network overhead.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "BatchSize": 100,
    "BatchInterval": "00:00:05"
  }
}
```

Use a larger batch size for throughput.

Use a shorter batch interval when you need faster visibility.

## Queue limits

The SDK uses an in-memory queue before telemetry is sent.

Use `MaxQueueSize` to prevent memory pressure during spikes.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "MaxQueueSize": 10000
  }
}
```

If the queue fills, the SDK should protect your application before preserving every telemetry item.

Foveus should never become the reason your service fails.

## Retries and timeouts

The SDK retries failed sends with backoff.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "HttpTimeout": "00:00:30",
    "MaxRetryAttempts": 3,
    "RetryBaseDelay": "00:00:01"
  }
}
```

Use lower timeouts or fewer retries if your service has strict latency requirements.

Use higher values only when your network is unreliable and delayed telemetry is acceptable.

## Metrics pre-aggregation

For high-volume services, metrics pre-aggregation can reduce telemetry volume.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "EnableMetricsPreAggregation": true,
    "MetricsAggregationInterval": "00:01:00"
  }
}
```

This is useful when detailed individual metric events are less important than aggregate behavior.

## Recommended setups

### Normal production API

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "ServiceName": "orders-api",
    "Environment": "production",
    "Mode": "live",
    "CaptureProfile": "Balanced",
    "CaptureRequestBodies": true,
    "CaptureResponseBodies": true,
    "ContextSamplingRate": 0.01,
    "MaxBodyCaptureSizeBytes": 65536,
    "ExcludedPathPrefixes": ["/health", "/metrics"],
    "RedactedFields": ["nationalId", "accountNumber"]
  }
}
```

### High-volume API

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

### Provider-heavy service

Use this when you need to inspect third-party or downstream responses.

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

## Tuning checklist

Start with `Balanced`.

Then adjust:

1. Exclude noisy paths.
2. Add redacted fields.
3. Lower `ContextSamplingRate` for high-volume services.
4. Reduce body capture for sensitive or very large endpoints.
5. Increase batching for throughput.
6. Enable `HighThroughput` for very busy services.

## Troubleshooting

### Foveus appears to send too much telemetry

Use:

* `ExcludedPathPrefixes`
* `ExcludedExactPaths`
* lower `ContextSamplingRate`
* `CaptureProfile: "HighThroughput"`
* lower body capture settings

### Context search is missing response values

Check that:

* `CaptureResponseBodies` is enabled
* the response value is scalar
* the response body is within `MaxBodyCaptureSizeBytes`
* the path is not excluded
* redaction did not mask the value
* sampling did not skip the context snapshot

### SDK logs are too noisy

Disable debug logging.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "EnableDebugLogging": false
  }
}
```

### Your service is high traffic

Use `HighThroughput`, exclude noisy paths, reduce sampling, and keep body capture limited to the endpoints where it is useful.

## Next steps

* Review all options: [FoveusOptions](/sdk/foveus-options)
* Configure redaction: [Redaction](/sdk/redaction)
* Learn about context search: [Execution Context Search](/concepts/execution-context-search)
* Review data retention: [Data safety and retention](/security/data-safety-and-retention)