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

# Quickstart

Connect a .NET service to Foveus and view your first execution.

In this guide, you’ll:

1. Copy your test API key from onboarding
2. Install the Foveus .NET SDK
3. Configure your service
4. Trigger a request or worker log
5. View telemetry in Foveus

## Before you start

You need:

* A Foveus account
* Access to your Foveus onboarding screen
* A .NET API or worker service
* Access to your app configuration

Your workspace is created automatically when you sign up.

Test mode is used by default, so you do not need to set `Mode` while validating your setup.

<Tip>
  Use Test mode while setting up Foveus. Set `Mode` to `live` only when you are ready to send production telemetry with a live key.
</Tip>

## 1. Copy your test API key

After signing in, Foveus guides you through onboarding.

The first onboarding step shows your test API key.

Your key should look similar to:

```text theme={null}
fov_test_...
```

Copy the key from the onboarding screen.

Keep your API key private. Do not commit it to source control.

<Note>
  During private beta, test keys are created automatically during onboarding. Live keys are created manually from Settings when you are ready to send production telemetry.
</Note>

## 2. Install the .NET SDK

Install the Foveus .NET SDK in your service.

```bash theme={null}
dotnet add package Foveus.SDK
```

<Note>
  If your package name or package source is different during private beta, use the values shown in your onboarding screen or provided by the Foveus team.
</Note>

## 3. Configure Foveus

Choose the setup style that matches your service.

## Minimal setup

Use this when you want to connect quickly with your test API key.

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

With this setup, Foveus automatically uses:

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

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

## Configure from appsettings.json

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

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

You can override the service name or environment when needed:

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

You do not need to set `Mode` to `test`. Test mode is the default.

## Configure with options

Use options when you want to configure Foveus directly in code.

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

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

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

## ASP.NET Core APIs

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

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

The middleware captures HTTP executions.

A typical setup looks like this:

```csharp theme={null}
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddFoveus(builder.Configuration);

var app = builder.Build();

app.UseFoveus();

app.MapGet("/orders", () =>
{
    return Results.Ok(new
    {
        orderStatus = new
        {
            value = 1,
            label = "Confirmed"
        }
    });
});

app.Run();
```

## Worker services

For `.NET Worker Service` or `BackgroundService` apps, use `AddFoveus(...)`, but do not call `app.UseFoveus()`.

Workers do not have an ASP.NET HTTP middleware pipeline.

```csharp theme={null}
var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddFoveus(builder.Configuration);

builder.Services.AddHostedService<Worker>();

var host = builder.Build();

await host.RunAsync();
```

Worker support currently covers logs, logged exceptions, outbound HTTP telemetry, metrics, and trace propagation. Full automatic per-job execution capture for arbitrary worker loops is still evolving.

## 4. Store your API key safely

Use environment variables or your platform’s secret manager.

For local development, you can use .NET user secrets:

```bash theme={null}
dotnet user-secrets set "Foveus:ApiKey" "fov_test_..."
```

For production, use your hosting provider’s secret manager.

<Warning>
  Never commit live API keys to source control.
</Warning>

## 5. Trigger telemetry

For an ASP.NET Core API, start your service and call one of your endpoints.

```bash theme={null}
curl http://localhost:5000/orders
```

Foveus captures the execution and sends it to your workspace.

Depending on your SDK configuration, Foveus can capture:

* request context
* response context
* execution timing
* logs
* outcome and failure evidence

For a worker service, write a log or trigger an outbound operation.

```csharp theme={null}
_logger.LogInformation("Billing worker processed invoice {InvoiceId}", invoiceId);
```

## 6. View your first execution

Open the Foveus dashboard and go to **Executions**.

Search by service:

```text theme={null}
service:orders-api
```

If you did not set `ServiceName`, search using your project assembly name.

Open an execution to inspect:

* request and response context
* execution timeline
* logs
* duration
* outcome
* failure details, if available

<Note>
  For worker services, logs and outbound telemetry may appear before full job-level execution boundaries are available.
</Note>

## 7. Search by execution context

If your service captures business context, you can search for executions using indexed context fields.

For example, if your request or response contains a customer ID:

```json theme={null}
{
  "customerId": "cus_12345"
}
```

You can search for it:

```text theme={null}
service:orders-api context:customerId="cus_12345"
```

You can also search nested response fields with dotted paths.

```json theme={null}
{
  "orderStatus": {
    "value": 1,
    "label": "Confirmed"
  }
}
```

Search the nested field:

```text theme={null}
service:orders-api context:orderStatus.value=1
```

Or search by label:

```text theme={null}
service:orders-api context:orderStatus.label="Confirmed"
```

Foveus searches indexed execution context. It does not scan arbitrary raw request or response bodies.

## Test and Live mode

Foveus has two modes:

| Mode   | Use for                                  |
| ------ | ---------------------------------------- |
| `test` | Sandbox, development, QA, and onboarding |
| `live` | Production telemetry                     |

Foveus uses Test mode by default.

Use Live mode only when your service is ready to send production telemetry with a live key.

## Service names and environments

Foveus works with the service names your team already uses.

If you are starting fresh, a stable service name plus an explicit environment can make analysis easier.

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

This is a recommendation, not a requirement.

## What to do next

* Learn how executions work: [Executions](/concepts/executions)
* Learn how issues are grouped: [Issues](/concepts/issues)
* Search by business context: [Execution Context Search](/concepts/execution-context-search)
* Configure the SDK: [SDK configuration](/sdk/configuration)
* Review data safety and retention: [Data safety and retention](/security/data-safety-and-retention)