Skip to main content
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.
Some behaviour on this page requires Foveus.SDK 1.1.0-beta.18 or later: reading MaxBodyCaptureSizeBytes, HttpTimeout, MaxRetryAttempts and RetryBaseDelay from configuration (earlier versions ignore them and use the defaults), flushing queued telemetry on graceful shutdown (earlier versions discard it), and reporting telemetry the SDK dropped.

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.
With this setup, Foveus uses defaults for service name, environment, batching, capture, and safety controls. The key decides the mode. For production, use configuration so you can tune capture behavior without changing code.

Capture profiles

Use CaptureProfile to choose a capture strategy. Example:

Balanced profile

Use Balanced for most production services. These are its settings:
Balanced captures request bodies but not response bodies. To inspect provider responses, business outcomes, or what a user received, set CaptureResponseBodies to true explicitly; see Request and response body capture. Capture stays bounded by sampling, redaction and body-size limits.

Debug profile

Use Debug when you are troubleshooting locally or investigating a specific service behavior.
The Debug profile captures context and request and response bodies for every request, so it can capture more data than you usually want in production. IP anonymization stays on. Use it temporarily.

High-throughput profile

Use HighThroughput for services where lower overhead matters more than detailed context.
HighThroughput turns off body capture, turns on metrics pre-aggregation, sends batches of 500 every 2 seconds, raises the queue size to 50,000 and samples 0.1% of successful requests. This example also sets some of those values explicitly and excludes health and metrics paths. 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.
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. Failed requests always capture context, whatever the sampling rate.

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. If you enable body capture in production, use it with safety controls:
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:

Body size limits

Use MaxBodyCaptureSizeBytes to prevent large payloads from creating excessive overhead.
Bodies larger than the limit are truncated. Redaction runs before truncation. The default limit is 65,536 bytes (64 KB). Use path exclusions for endpoints that return large payloads.

Path exclusions

Exclude noisy or low-value endpoints.
Common exclusions:
For sensitive services, exclude authentication or credential-related paths.

Batching

The SDK batches telemetry before sending it to Foveus. Batching reduces network overhead.
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.
The queue holds up to MaxQueueSize items for each telemetry type (logs, metrics, context, errors). If it fills, the SDK protects your application first: telemetry beyond the queue’s capacity is dropped, and the loss is counted. See When telemetry is delayed or lost.

Retries and timeouts

The SDK retries failed sends with backoff. Sending happens in the background, so retries do not slow down your requests.
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.

When telemetry is delayed or lost

The SDK sends telemetry every 5 seconds by default. Each telemetry type (logs, metrics, context and errors) is sent independently; a busy type can send up to 10 batches per interval, and batches over about 900 KB are split. If Foveus is unreachable, rate limiting, or unavailable:
  • Telemetry stays in the bounded in-memory queue (MaxQueueSize, 10,000 items per type by default) and is retried.
  • After repeated failures, the SDK pauses sending for 5 minutes, then sends the backlog.
  • Your application is not slowed down.
  • Telemetry beyond the queue’s capacity, and any batch Foveus rejects outright, is lost and counted.
On graceful shutdown, the SDK flushes queued telemetry before the process exits. Earlier SDK versions (see the note at the top of this page) discard queued telemetry on shutdown. Foveus limits ingestion to 600 requests per minute per API key, for each telemetry type. At default settings, a single SDK instance was measured at no more than 12 requests per minute per type. Instances that share a key count against the same limit. Foveus records telemetry loss: requests rejected by the rate limit (all SDK versions), items the SDK dropped (reported on its next accepted request, by the SDK version noted at the top of this page), retries and pauses, and items Foveus received but could not store. When telemetry for the last hour is affected, the dashboard shows a “Telemetry incomplete”, “Telemetry may be incomplete” or “Telemetry delayed” banner, and GET /api/telemetry-health returns the same status per service. This lets you tell missing data apart from no activity.

Metrics pre-aggregation

For high-volume services, metrics pre-aggregation can reduce telemetry volume.
This is useful when detailed individual metric events are less important than aggregate behavior.

Normal production API

High-volume API

Provider-heavy service

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

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

Data is missing for a period

Check the dashboard for a “Telemetry incomplete” or “Telemetry delayed” banner. If it is shown, telemetry was lost, rate limited or is still being retried, rather than your service being idle.

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.

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