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

# Configuration

Configure the Foveus .NET SDK to control how your service sends telemetry.

For most services, you only need to pass your API key.

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

Then add the middleware:

```csharp theme={null}
app.UseFoveus();
```

With this setup, Foveus uses safe defaults:

| Option        | Default                 |
| ------------- | ----------------------- |
| `ServiceName` | Project assembly name   |
| `Environment` | Current app environment |
| `Mode`        | `test`                  |

Override these values only when you need more control.

## Configuration methods

You can configure Foveus in three common ways:

| Method                    | Use when                                                                        |
| ------------------------- | ------------------------------------------------------------------------------- |
| Minimal setup             | You want to connect quickly with an API key.                                    |
| Configuration-based setup | You want to use `appsettings.json`, environment variables, or a secret manager. |
| Options-based setup       | You want to configure values directly in code.                                  |

## Minimal setup

Use minimal setup for local development, sandbox testing, or quick validation.

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

Then add the middleware:

```csharp theme={null}
app.UseFoveus();
```

<Warning>
  Do not hardcode API keys in production code. Use this only for local testing or quick validation.
</Warning>

## Configuration-based setup

For most applications, configure Foveus from `appsettings.json`, environment variables, or your secret manager.

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

Add a `Foveus` section to your configuration.

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

Foveus still uses the default service name, environment, and mode unless you override them.

You can override defaults when needed:

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "orders-api",
    "Environment": "staging"
  }
}
```

For live telemetry, use a live key and set `Mode` to `live`.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "ServiceName": "orders-api",
    "Environment": "production",
    "Mode": "live"
  }
}
```

## Options-based setup

Use options-based setup when you want to configure the SDK directly in code.

```csharp theme={null}
builder.Services.AddFoveus(options =>
{
    options.ApiKey = builder.Configuration["Foveus:ApiKey"];
});
```

Override defaults when needed:

```csharp theme={null}
builder.Services.AddFoveus(options =>
{
    options.ApiKey = builder.Configuration["Foveus:ApiKey"];
    options.ServiceName = "orders-api";
    options.Environment = "staging";
});
```

For live telemetry:

```csharp theme={null}
builder.Services.AddFoveus(options =>
{
    options.ApiKey = builder.Configuration["Foveus:ApiKey"];
    options.ServiceName = "orders-api";
    options.Environment = "production";
    options.Mode = "live";
});
```

## Core options

| Option        | Required? | Default                 | Description                                                                                                      |
| ------------- | --------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `ApiKey`      | Yes       | None                    | Your Foveus API key. Test keys are created automatically during onboarding. Live keys are created from Settings. |
| `ServiceName` | No        | Project assembly name   | The service name shown in Foveus. Override this when your assembly name is not the name your team uses.          |
| `Environment` | No        | Current app environment | The deployment environment, such as `Development`, `staging`, or `production`.                                   |
| `Mode`        | No        | `test`                  | The Foveus data mode. Set this to `live` only when using a live key for production telemetry.                    |

## Service name

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

Foveus works with your existing service naming convention. Override `ServiceName` only when the default is not what you want to see in the dashboard.

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

Examples:

```text theme={null}
Development
test
staging
production
```

## Mode

`Mode` controls the Foveus telemetry boundary.

Foveus defaults to Test mode.

You only need to set `Mode` when sending live telemetry.

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

Use a live key with Live mode.

Do not use live keys in local development.

## Middleware

For ASP.NET Core APIs, add the Foveus middleware.

```csharp theme={null}
app.UseFoveus();
```

The middleware captures HTTP executions.

Place it after middleware that sets request context, authentication, or correlation IDs if your service depends on those values.

## Advanced options

Most SDK options can also be configured from `appsettings.json` under the `Foveus` section.

Use this when you want to tune capture behavior, performance, redaction, batching, or path filtering without constructing options manually in code.

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

Then load the configuration:

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

<Note>
  You do not need to construct `FoveusOptions` directly for most services. Use `appsettings.json` or environment variables when you want configuration outside code.
</Note>

For the full list of SDK options, see [FoveusOptions](/sdk/foveus-options).

## Capture profiles

`CaptureProfile` lets you quickly tune how much telemetry Foveus captures.

Common profiles include:

| Profile          | Use for                                                                           |
| ---------------- | --------------------------------------------------------------------------------- |
| `Balanced`       | Normal production usage.                                                          |
| `Debug`          | Local development or deep troubleshooting.                                        |
| `HighThroughput` | Busy services where low overhead is more important than detailed context capture. |

Example:

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

Use `Debug` only when you need deeper local troubleshooting. It can capture more context than you usually want in production.

## Capture behavior

The SDK can capture telemetry such as:

* HTTP executions
* request metadata
* response metadata
* request query values
* request body context
* response body context
* logs, if logging integration is configured
* outcome and failure evidence

The exact data captured depends on SDK settings, framework support, capture profile, and safety controls.

## Request and response bodies

You can control whether Foveus captures request and response body context.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "CaptureRequestBodies": true,
    "CaptureResponseBodies": false
  }
}
```

Request body capture is useful for debugging API behavior.

Response body capture can be useful for business outcome analysis, but responses often contain sensitive data. Review your redaction settings before enabling it broadly.

## Sampling

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

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ContextSamplingRate": 0.01
  }
}
```

A value of `0.01` means 1%.

Use a higher sampling rate while debugging. Use a lower rate for high-volume production services.

## Path filtering

Use path filters to reduce noise or exclude endpoints you do not want to capture.

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

This is useful for endpoints such as:

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

## Redaction

Foveus applies safety controls before storing or indexing context.

You can add domain-specific fields to the redaction list.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "RedactedFields": ["nationalId", "accountNumber"]
  }
}
```

Sensitive fields such as passwords, tokens, authorization headers, cookies, secrets, and card values should not be stored or indexed.

Still, avoid sending sensitive data when possible.

See [Redaction](/sdk/redaction) for details.

## Production setup

For production, use:

* a live API key
* `Mode: "live"`
* a service name your team recognizes
* a production environment label
* a secret manager for API keys
* conservative capture and redaction settings

Example:

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

## Troubleshooting

### No executions appear

Check that:

* `ApiKey` is set
* your service can reach Foveus
* `app.UseFoveus()` is registered
* you are viewing the right mode in the dashboard
* your time range includes the request
* your service name matches your search

### Service name looks wrong

If the service name appears as your project assembly name and you want a different name, set `ServiceName`.

```json theme={null}
{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "orders-api"
  }
}
```

### Telemetry appears in Test mode

Foveus defaults to Test mode.

If you are sending production telemetry, set `Mode` to `live`.

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

### Context search does not find a field

Check that:

* the field was captured in request, response, query, or custom context
* the value is scalar
* the value was ingested after context indexing was enabled
* the key is not blocked by safety policy
* the field is within capture and indexing limits

## Next steps

* Install the .NET SDK: [Install the .NET SDK](/get-started/install-dotnet-sdk)
* Learn about services and environments: [Services and environments](/concepts/services-and-environments)
* Search by context: [Execution Context Search](/concepts/execution-context-search)
* Review FoveusOptions: [FoveusOptions](/sdk/foveus-options)
* Review redaction: [Redaction](/sdk/redaction)