# TraconObservabilityOptions

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.traconobservabilityoptions/
> Summary: TraconObservabilityOptions: Defines telemetry collection and persistence options.

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.Core.dll</code></div>

Defines telemetry collection and persistence options.

```csharp
public sealed class TraconObservabilityOptions
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.traconobservabilityoptions/">TraconObservabilityOptions</a></dd><dt>Inherited Members</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object.gettype">object.GetType()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.tostring">object.ToString()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object)">object.Equals(object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object)">object.Equals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.referenceequals">object.ReferenceEquals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.gethashcode">object.GetHashCode()</a></dd></dl>

## Remarks

Tracon **does not take over the pipeline**: the consumer's
OTLP exporter continues to run. These options only control what Tracon
writes to its *own* span store.

## Constructors

### <a id="Tracon_TraconObservabilityOptions__ctor"></a> TraconObservabilityOptions\(\)

```csharp
public TraconObservabilityOptions()
```

## Properties

### <a id="Tracon_TraconObservabilityOptions_AlwaysPersistFailures"></a> AlwaysPersistFailures

Gets or sets whether failed run spans are persisted regardless of sampling ratio.

```csharp
public bool AlwaysPersistFailures { get; set; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

### <a id="Tracon_TraconObservabilityOptions_EnableJobQueueDepthGauge"></a> EnableJobQueueDepthGauge

Gets or sets whether the `tracon.job.queue.depth` observable
gauge publishes measurements.

```csharp
public bool EnableJobQueueDepthGauge { get; set; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

#### Remarks

**Disabled by default** under the no-surprises rule, for the same
reason as [TraconObservabilityOptions.EnableQuotaUsageGauge](/api/tracon.traconobservabilityoptions/#Tracon_TraconObservabilityOptions_EnableQuotaUsageGauge): the gauge reads the database.
The `tracon.job.executions` counter and the
`tracon.job.duration` histogram are not affected by this setting —
they cost no extra query and are always written.

When enabled, the depth is refreshed in the background the same way as
the quota gauges: at startup, then every
[TraconObservabilityOptions.JobQueueDepthRefreshInterval](/api/tracon.traconobservabilityoptions/#Tracon_TraconObservabilityOptions_JobQueueDepthRefreshInterval). A scrape never waits for the
database, and the first scrape after startup can be empty. The setting is
read at startup: turning the gauge on takes effect at the next start.

### <a id="Tracon_TraconObservabilityOptions_EnableQuotaUsageGauge"></a> EnableQuotaUsageGauge

Gets or sets whether the `tracon.quota.usage` and
`tracon.quota.limit` observable gauges are enabled.

```csharp
public bool EnableQuotaUsageGauge { get; set; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

#### Remarks

**Disabled by default** under the no-surprises rule because the gauge reads the
database. Unlike the cost counter, this consumes additional resources and
must be explicitly requested.

When enabled, a background service reads the samples at startup and then
every [TraconObservabilityOptions.QuotaUsageRefreshInterval](/api/tracon.traconobservabilityoptions/#Tracon_TraconObservabilityOptions_QuotaUsageRefreshInterval); a metrics collection only
reads the last result and never waits for the database. The first
collection after startup can therefore be empty. The setting is read at
startup: turning the gauge on takes effect at the next start.

### <a id="Tracon_TraconObservabilityOptions_Enabled"></a> Enabled

Gets or sets whether span and metric creation is enabled. When disabled,
no `Activity` starts and no measurement is recorded.

```csharp
public bool Enabled { get; set; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

### <a id="Tracon_TraconObservabilityOptions_IncludeAgentVersionTag"></a> IncludeAgentVersionTag

Gets or sets whether the `tracon.agent.version` tag is added to
spans and the `tracon.runs` and `tracon.run.duration` metrics.

```csharp
public bool IncludeAgentVersionTag { get; set; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

#### Remarks

Defaults to [true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool). A version number creates dozens of time
series per agent over time, which is acceptable cardinality. Deployments
that change versions very frequently can disable it.

### <a id="Tracon_TraconObservabilityOptions_IncludeTenantTag"></a> IncludeTenantTag

Gets or sets whether the `tracon.tenant.id` tag is added to the run, cost, judge, response-cache,
audit-write-failure, run-recording-failure and job metrics.

```csharp
public bool IncludeTenantTag { get; set; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

#### Remarks

**Disabled by default.** A tag per tenant multiplies every series of those metrics by the
number of tenants, and a metric backend bills and slows down by series. Turn it on when the number of
tenants is small and bounded and a dashboard or an alert has to split a metric by tenant.

The setting leaves two things alone, because neither multiplies series: spans always carry
`tracon.tenant.id`, and so do the `tracon.quota.usage` and `tracon.quota.limit` gauges
(a quota is a per-tenant fact; a gauge without the tenant says nothing). The metrics read the value from
the options at every measurement.

### <a id="Tracon_TraconObservabilityOptions_JobQueueDepthRefreshInterval"></a> JobQueueDepthRefreshInterval

Gets or sets how often the queue-depth gauge's background refresh reads
the database. A reported depth can be up to one interval old.

```csharp
public TimeSpan JobQueueDepthRefreshInterval { get; set; }
```

#### Property Value

 [TimeSpan](https://learn.microsoft.com/dotnet/api/system.timespan)

#### Remarks

Must be from one millisecond to about 49.7 days while [TraconObservabilityOptions.EnableJobQueueDepthGauge](/api/tracon.traconobservabilityoptions/#Tracon_TraconObservabilityOptions_EnableJobQueueDepthGauge)
is on; startup validation rejects any other value.
The value is read when the host starts; a later change takes effect at
the next start.

### <a id="Tracon_TraconObservabilityOptions_MaxJobLaneCardinality"></a> MaxJobLaneCardinality

Gets or sets how many distinct job lanes may each get a metric series of
their own before further lanes are folded into a single `other` series.

```csharp
public int MaxJobLaneCardinality { get; set; }
```

#### Property Value

 [int](https://learn.microsoft.com/dotnet/api/system.int32)

#### Remarks

A lane name is chosen by the consumer ([JobLanes](/api/tracon.joblanes/)) and its
count is unbounded, so it is the one tag value Tracon does not
control. This limit is a guard, not a design constraint: an installation
with more than 64 meaningful lanes is an operator error rather than a
use case. Lanes keep the name they were first seen under for the life of
the process; the set never shrinks.

### <a id="Tracon_TraconObservabilityOptions_MaxSpansPerRun"></a> MaxSpansPerRun

Gets or sets the largest span count held in memory for one run. Excess
spans are dropped and a warning is logged.

```csharp
public int MaxSpansPerRun { get; set; }
```

#### Property Value

 [int](https://learn.microsoft.com/dotnet/api/system.int32)

#### Remarks

The sampling decision is made when a run *finishes*, when success
or failure is known. Spans remain in memory until then. This limit bounds
memory use by the concurrent run count.

### <a id="Tracon_TraconObservabilityOptions_PersistSpans"></a> PersistSpans

Gets or sets whether spans are written to [ITraceStore](/api/tracon.itracestore/). When
disabled, spans are still created and sent to the consumer exporter, but
are not written to Tracon's own store.

```csharp
public bool PersistSpans { get; set; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

### <a id="Tracon_TraconObservabilityOptions_QuotaUsageRefreshInterval"></a> QuotaUsageRefreshInterval

Gets or sets how often the quota gauges' background refresh reads the
database. A reported value can be up to one interval old.

```csharp
public TimeSpan QuotaUsageRefreshInterval { get; set; }
```

#### Property Value

 [TimeSpan](https://learn.microsoft.com/dotnet/api/system.timespan)

#### Remarks

Must be from one millisecond to about 49.7 days while [TraconObservabilityOptions.EnableQuotaUsageGauge](/api/tracon.traconobservabilityoptions/#Tracon_TraconObservabilityOptions_EnableQuotaUsageGauge)
is on; startup validation rejects any other value.
The value is read when the host starts; a later change takes effect at
the next start.

### <a id="Tracon_TraconObservabilityOptions_RecordSensitiveData"></a> RecordSensitiveData

Gets or sets whether request and response text is written to spans.
**Disabled by default** because this content can contain personal data.

```csharp
public bool RecordSensitiveData { get; set; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

### <a id="Tracon_TraconObservabilityOptions_SuccessSampleRatio"></a> SuccessSampleRatio

Gets or sets the fraction from 0 to 1 of successful run spans to persist.
Defaults to 0.1, or one tenth.

```csharp
public double SuccessSampleRatio { get; set; }
```

#### Property Value

 [double](https://learn.microsoft.com/dotnet/api/system.double)

#### Remarks

Persisting every span bottlenecks the database at high volume. Failed runs
are valuable for debugging and are separately protected by
[TraconObservabilityOptions.AlwaysPersistFailures](/api/tracon.traconobservabilityoptions/#Tracon_TraconObservabilityOptions_AlwaysPersistFailures).