# CanaryPolicy

> 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.canarypolicy/
> Summary: CanaryPolicy: Defines automatic rollback and gradual traffic-increase rules for an experiment canary variant.

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

Defines automatic rollback and gradual traffic-increase rules for an experiment canary variant.

```csharp
public sealed record CanaryPolicy : IEquatable<CanaryPolicy>
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.canarypolicy/">CanaryPolicy</a></dd><dt>Implements</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.iequatable-1">IEquatable&lt;CanaryPolicy&gt;</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

This policy can only be defined for **two-variant** experiments.
[CanaryPolicy.CanaryVariant](/api/tracon.canarypolicy/#Tracon_CanaryPolicy_CanaryVariant) is the canary and the one remaining variant is the
control. With more than two variants, proportional control-weight redistribution
could not guarantee session stability. This
constraint keeps the canary range fixed at `[0, canaryWeight)` and makes
the control range contiguous.

Comparison is **relative**. The canary rolls back when its error
rate is [CanaryPolicy.MaxErrorRateDelta](/api/tracon.canarypolicy/#Tracon_CanaryPolicy_MaxErrorRateDelta) higher than the control rate. An
absolute threshold, such as "stop at a 5% error rate", would unfairly stop a
canary for an agent whose control is also unhealthy.

## Constructors

### <a id="Tracon_CanaryPolicy__ctor"></a> CanaryPolicy\(\)

```csharp
public CanaryPolicy()
```

## Properties

### <a id="Tracon_CanaryPolicy_CanaryVariant"></a> CanaryVariant

Gets the canary variant name. It must exist in the experiment `Variants` list.

```csharp
public required string CanaryVariant { get; init; }
```

#### Property Value

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

### <a id="Tracon_CanaryPolicy_MaxErrorRateDelta"></a> MaxErrorRateDelta

Gets the maximum absolute error-rate difference from the control, from 0.0
through 1.0. The canary rolls back when its rate is higher. No error-rate
check runs when this value is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

```csharp
public double? MaxErrorRateDelta { get; init; }
```

#### Property Value

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

### <a id="Tracon_CanaryPolicy_MinSampleSize"></a> MinSampleSize

Gets the minimum completed run count that both the canary and control
variants must reach before a decision is made.

```csharp
public int MinSampleSize { get; init; }
```

#### Property Value

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

#### Remarks

This is the same rule as
`OnlineEvaluationOptions.MinSampleSize`. It has the same
default of `20` and the same a threshold reacts to noise
with a small sample. Gradual increases use the same value to advance to
the next step; a second threshold property is not added.

### <a id="Tracon_CanaryPolicy_MinScore"></a> MinScore

Gets the minimum average canary score from 0 through 100. The canary rolls
back below this threshold. No score check runs when this value is
[null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

```csharp
public int? MinScore { get; init; }
```

#### Property Value

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

### <a id="Tracon_CanaryPolicy_RampInterval"></a> RampInterval

Gets the minimum time between steps.

```csharp
public TimeSpan RampInterval { get; init; }
```

#### Property Value

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

### <a id="Tracon_CanaryPolicy_RampSteps"></a> RampSteps

Gets the canary-weight steps that increase over time, for example
`[5, 25, 50, 100]`. An empty list disables gradual increases. The
canary weight stays at the value set through `SaveAsync` and only
rollback is evaluated.

```csharp
public IReadOnlyList<int> RampSteps { get; init; }
```

#### Property Value

 [IReadOnlyList](https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist\-1)<[int](https://learn.microsoft.com/dotnet/api/system.int32)\>

## Methods

### <a id="Tracon_CanaryPolicy_Equals_System_Object_"></a> Equals\(object?\)

```csharp
public override bool Equals(object? obj)
```

#### Parameters

`obj` [object](https://learn.microsoft.com/dotnet/api/system.object)?

#### Returns

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

### <a id="Tracon_CanaryPolicy_Equals_Tracon_CanaryPolicy_"></a> Equals\(CanaryPolicy?\)

```csharp
public bool Equals(CanaryPolicy? other)
```

#### Parameters

`other` [CanaryPolicy](/api/tracon.canarypolicy/)?

#### Returns

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

### <a id="Tracon_CanaryPolicy_GetHashCode"></a> GetHashCode\(\)

```csharp
public override int GetHashCode()
```

#### Returns

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

### <a id="Tracon_CanaryPolicy_ToString"></a> ToString\(\)

```csharp
public override string ToString()
```

#### Returns

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

## Operators

### <a id="Tracon_CanaryPolicy_op_Equality_Tracon_CanaryPolicy_Tracon_CanaryPolicy_"></a> operator ==\(CanaryPolicy?, CanaryPolicy?\)

```csharp
public static bool operator ==(CanaryPolicy? left, CanaryPolicy? right)
```

#### Parameters

`left` [CanaryPolicy](/api/tracon.canarypolicy/)?

`right` [CanaryPolicy](/api/tracon.canarypolicy/)?

#### Returns

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

### <a id="Tracon_CanaryPolicy_op_Inequality_Tracon_CanaryPolicy_Tracon_CanaryPolicy_"></a> operator \!=\(CanaryPolicy?, CanaryPolicy?\)

```csharp
public static bool operator !=(CanaryPolicy? left, CanaryPolicy? right)
```

#### Parameters

`left` [CanaryPolicy](/api/tracon.canarypolicy/)?

`right` [CanaryPolicy](/api/tracon.canarypolicy/)?

#### Returns

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