Executions

An execution is one run of work in your application. For an API service, an execution is usually one HTTP request. For a worker job, an execution is one BeginExecution scope: one loop iteration, job pass or batch that you mark in code. For a MassTransit consumer, an execution is one consumed message, when Foveus instrumentation is configured. Foveus does not detect scheduler, cron or Hangfire jobs as executions. Foveus uses executions to show what happened, when it happened, how long it took, and what evidence was captured.

Why executions matter

Logs tell you what was written. Metrics tell you what changed. Traces show request flow. Executions show the actual unit of work you need to inspect. An execution can include:

service name
endpoint or operation
request context
response context
duration
status
logs
failure details
linked issue, if Foveus grouped it into one

Execution examples

An HTTP API request:

GET /orders/ord_12345

Foveus records these as executions today:

Execution	How it is captured
Inbound ASP.NET Core request	`app.UseFoveus()`
Outbound `HttpClient` call	Automatic for clients created through `IHttpClientFactory`; a child of the calling execution
Consumed MassTransit message	When `cfg.AddFoveusInstrumentation(context)` is configured; a child of the publishing request when that is instrumented
Worker job or loop iteration	A `BeginExecution` scope
Logged exception outside any execution	Recorded as its own single-event execution

Each execution has a trigger type: http for requests and outbound calls, job for BeginExecution scopes, and sdk for others, such as a logged exception outside any execution.

Foveus does not create execution boundaries automatically for arbitrary worker loops; use BeginExecution. Database calls, cache operations, Hangfire, Quartz and cron jobs are not captured.

What Foveus captures

The exact data depends on your SDK configuration and service type. A typical HTTP execution can include:

Field	Description
`service`	The service that produced the execution.
`environment`	The deployment label from `Environment`, such as `staging` or `production`. Defaults to `test` or `live`, from the key.
`mode`	`test` or `live`, decided by the API key prefix.
`endpoint`	The HTTP path or operation name.
`method`	The HTTP method, such as `GET` or `POST`.
`duration`	How long the execution took.
`status`	`success`, `degraded` or `failed`.
`context`	Safe request, response, query, or custom context fields.
`logs`	Logs correlated to the execution, if configured.
`issue`	The issue linked to the execution, if Foveus grouped it.

Execution detail returns at most 500 steps. Larger execution trees are flagged as truncated. For worker services, Foveus captures logs, logged exceptions, outbound HTTP telemetry, metrics and trace propagation, plus one execution per BeginExecution scope and one per consumed MassTransit message when instrumentation is configured.

Service name

Foveus uses the service name to group executions by logical service. If you do not set ServiceName, Foveus uses your project assembly name. You can override it in configuration:

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

builder.Services.AddFoveus(builder.Configuration);

Use a service name your team recognizes.

orders-api
payments-api
identity-api
billing-worker

Foveus works with your existing service naming convention. If your organization uses environment-specific service names, you can keep using them.

Environment

Use Environment as a free-text label for where your service is running. When you do not set it, it is test or live, taken from the API key. It is not the ASP.NET Core environment. Examples:

development
test
staging
production

This helps you separate the same service across deployments.

service:orders-api environment:production

Mode

Foveus has two modes:

Mode	Key prefix	Use for
`test`	`fov_test_`	Sandbox, development, QA, and onboarding
`live`	`fov_live_`	Production telemetry

The API key decides the mode. There is no separate mode setting. To send live telemetry, use a live key:

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

Status

An execution has one of these statuses:

Status	Meaning
`success`	The execution completed successfully.
`degraded`	The execution returned a 4xx response, or a job was cancelled.
`failed`	The execution returned a 5xx response, threw or logged an exception, or was marked failed.

Context

Execution context is structured data captured from the request, response, query string, or custom context. By default, context is captured for every failed request and for 1% of successful requests (ContextSamplingRate is 0.01). Response bodies are not captured unless you enable CaptureResponseBodies. For example:

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

You can search indexed context fields:

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

Search nested fields with dotted paths:

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

Strings should use quotes. Numbers and booleans do not need quotes.

Execution Context Search uses indexed execution context. It does not scan arbitrary raw request bodies.

Linked logs

If logging is configured, Foveus can show logs related to an execution. This helps you inspect the log lines that occurred during the same unit of work instead of searching through unrelated log streams. For worker services, logs are linked to an execution only when they are written inside a BeginExecution scope or while an instrumented MassTransit consumer handles a message.

Worker telemetry

Foveus can be used in .NET Worker Service and BackgroundService apps. Worker services use:

builder.Services.AddFoveus(builder.Configuration);

They do not use:

app.UseFoveus();

because workers do not have an ASP.NET HTTP middleware pipeline. Worker support includes:

ILogger logs
logged exceptions
outbound HTTP telemetry through IHttpClientFactory
trace and execution header propagation on outbound HTTP
one execution per unit of work, when you mark it with BeginExecution
SDK shutdown flushing
source classification as worker
MassTransit consumers, when cfg.AddFoveusInstrumentation(context) is configured

BeginExecution and shutdown flushing require Foveus.SDK 1.1.0-beta.18 or later. Foveus does not create execution boundaries automatically for arbitrary worker loops, and it does not capture scheduler, cron or Hangfire job identity. See Worker services.

Linked issues

Foveus can group failed executions into issues. An issue is an observed recurring failure pattern, grouped by failure signature. It describes what was observed; it is not a confirmed root cause. For example, several failed executions on the same endpoint may become one issue.

HTTP 500 in orders-api

Open the issue to see:

failure pattern
representative execution
linked executions
recent activity
lifecycle
comments and activity history

Search executions

The Executions page is query-first because execution data can be high-volume. Common searches:

service:orders-api

service:orders-api method:POST endpoint:/orders

service:orders-api status:failed

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

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

For best performance and precision, start with a service filter when searching by context.

When to use executions

Use executions when you need to:

investigate a support complaint
find a request by customer ID or request ID
inspect request and response context
inspect the evidence for a failed request
move from an issue to the exact failed execution
correlate logs with a unit of work

For worker services, wrap each unit of work in BeginExecution to inspect its logs, exceptions and outbound HTTP calls as one execution. See Worker services.

What to do next

View your first execution: View your first execution
Search by context: Execution Context Search
Learn about issues: Issues
Set up worker services: Worker services
Investigate a user complaint: Investigate a user complaint

Start here

Get started

Core concepts

Guides

SDK

Security and data

API reference

Why executions matter

Execution examples

What Foveus captures

Service name

Environment

Mode

Status

Context

Linked logs

Worker telemetry

Linked issues

Search executions

When to use executions

What to do next