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.

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.

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:

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

Balanced profile

Use Balanced for most production services.

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

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

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

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

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

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "CaptureRequestBodies": false,
    "CaptureResponseBodies": false
  }
}

Body size limits

Use MaxBodyCaptureSizeBytes to prevent large payloads from creating excessive overhead.

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

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "ExcludedPathPrefixes": ["/health", "/metrics", "/ready", "/live"]
  }
}

Common exclusions:

/health
/metrics
/ready
/live

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

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "Mode": "live",
    "ExcludedPathPrefixes": ["/auth", "/health", "/metrics"]
  }
}

Batching

The SDK batches telemetry before sending it to Foveus. Batching reduces network overhead.

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

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

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

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

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

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

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

Exclude noisy paths.
Add redacted fields.
Lower ContextSamplingRate for high-volume services.
Reduce body capture for sensitive or very large endpoints.
Increase batching for throughput.
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.

{
  "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
Configure redaction: Redaction
Learn about context search: Execution Context Search
Review data retention: Data safety and retention

​What creates overhead

​Default behavior

​Capture profiles

​Balanced profile

​Debug profile

​High-throughput profile

​Sampling

​Request and response body capture

​Body size limits

​Path exclusions

​Batching

​Queue limits

​Retries and timeouts

​Metrics pre-aggregation

​Recommended setups

​Normal production API

​High-volume API

​Provider-heavy service

​Tuning checklist

​Troubleshooting

​Foveus appears to send too much telemetry

​Context search is missing response values

​SDK logs are too noisy

​Your service is high traffic

​Next steps