Quickstart

Connect a .NET service to Foveus and view your first execution. In this guide, you’ll:

Copy your test API key from onboarding
Install the Foveus .NET SDK
Configure your service
Trigger a request or worker log
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. Your API key decides the mode. A fov_test_ key sends telemetry to Test mode and a fov_live_ key sends it to Live mode. There is no separate mode setting.

Use your test key while setting up Foveus. Switch to a live key only when you are ready to send production telemetry.

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:

fov_test_...

Copy the key from the onboarding screen. Keep your API key private. Do not commit it to source control.

During private beta, test keys are created automatically during onboarding. Live keys are not self-serve: the Foveus team issues them when you are ready to send production telemetry.

2. Install the .NET SDK

Install the Foveus .NET SDK in your service.

dotnet add package Foveus.SDK

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.

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.

builder.Services.AddFoveus("fov_test_...");

With this setup, Foveus automatically uses:

Option	Default
`ServiceName`	Project assembly name
`Environment`	`test` or `live`, taken from the API key

Because the key starts with fov_test_, telemetry goes to Test mode.

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

Configure from appsettings.json

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

builder.Services.AddFoveus(builder.Configuration);

Add a Foveus section to your configuration file:

{
  "Foveus": {
    "ApiKey": "fov_test_..."
  }
}

You can override the service name or environment when needed:

{
  "Foveus": {
    "ApiKey": "fov_test_...",
    "ServiceName": "orders-api",
    "Environment": "staging"
  }
}

Environment is a free-text label for the deployment, such as staging or production. When you do not set it, it is test or live, taken from the key. It is not the ASP.NET Core environment.

If the API key is missing, empty or malformed, Foveus disables itself and writes Foveus is disabled: <reason> to the console and to your application’s log. Your application keeps running without Foveus telemetry. Requires Foveus.SDK 1.1.0-beta.18 or later; earlier versions throw at startup.

Production configuration

For production telemetry, use a live key. A fov_live_ key sends telemetry to Live mode.

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "ServiceName": "orders-api",
    "Environment": "production"
  }
}

ASP.NET Core APIs

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

app.UseFoveus();

The middleware captures HTTP executions. UseFoveus() is available on .NET 6 and later. A typical setup looks like this:

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.

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddFoveus(builder.Configuration);

builder.Services.AddHostedService<Worker>();

var host = builder.Build();

await host.RunAsync();

Worker support covers logs, logged exceptions, outbound HTTP telemetry, metrics, and trace propagation. Workers have no automatic execution boundary: wrap each unit of work in BeginExecution to record it as one execution. See Worker services.

4. Store your API key safely

Use environment variables or your platform’s secret manager. For local development, you can use .NET user secrets:

dotnet user-secrets set "Foveus:ApiKey" "fov_test_..."

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

Never commit live API keys to source control.

5. Trigger telemetry

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

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.

_logger.LogInformation("Billing worker processed invoice {InvoiceId}", invoiceId);

6. View your first execution

Open the Foveus dashboard and go to Executions. Search by service:

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

For worker services, logs and outbound calls are grouped into an execution only inside a BeginExecution scope. Without one, logs have no execution and each outbound call is recorded as its own execution.

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:

{
  "customerId": "cus_12345"
}

You can search for it:

service:orders-api context:customerId="cus_12345"

By default, Foveus captures context for every failed request and for 1% of successful requests (ContextSamplingRate is 0.01), and response bodies are not captured (CaptureResponseBodies is false). See FoveusOptions to change this. You can also search nested response fields with dotted paths.

{
  "orderStatus": {
    "value": 1,
    "label": "Confirmed"
  }
}

Search the nested field:

service:orders-api context:orderStatus.value=1

Or search by label:

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

The API key decides the mode: a fov_test_ key sends to Test mode and a fov_live_ key sends to Live mode. Use the Test/Live toggle in the dashboard to view each. 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.

{
  "Foveus": {
    "ApiKey": "fov_live_...",
    "ServiceName": "orders-api",
    "Environment": "production"
  }
}

This is a recommendation, not a requirement.

What to do next

Learn how executions work: Executions
Learn how issues are grouped: Issues
Search by business context: Execution Context Search
Configure the SDK: SDK configuration
Review data safety and retention: Data safety and retention

Start here

Get started

Core concepts

Guides

SDK

Security and data

API reference

Before you start

1. Copy your test API key

2. Install the .NET SDK

3. Configure Foveus

Minimal setup

Configure from appsettings.json

Production configuration

ASP.NET Core APIs

Worker services

4. Store your API key safely

5. Trigger telemetry

6. View your first execution

7. Search by execution context

Test and Live mode

Service names and environments

What to do next