FeatureGates 1.0.0-preview.2

FeatureGates for .NET

Release observable features by using FeatureGates, pre-instrumented abstractions that replace if statements.

The aim of FeatureGates is to enable reusable dashboards, tooling and automation by standardizing the way metrics and traces are emitted. These metrics and traces can then be collected and shipped via OpenTelemetry or by other means.

FeatureGates are vendor-agnostic and under the hood uses .NET metrics and .NET distributed tracing.

Install the package from NuGet.org by running;

dotnet add package FeatureGates --version <version>

Usage and Features

Instead of surrounding your feature with an if statement like the code below;

string myFeatureFlag = "MyCoolNewFeature";
bool IsEnabled() => myFeatureManager.Evaluate(myFeatureFlag);

if (IsEnabled())
{
    // My code when IsEnabled() returns 'true'.
}
else
{
    // Optional: My code when IsEnabled() returns 'false'.
}

Create a feature gate and invoke it like the following;

string myFeatureFlag = "MyCoolNewFeature";
bool IsEnabled() => myFeatureManager.Evaluate(myFeatureFlag);

var featureGate = FeatureGate
    .WithKey(myFeatureFlag)
    .ControlledBy(IsEnabled)
    .WhenOpened(() =>
    {
        // My code when IsEnabled() returns 'true'.
    })
    .WhenClosed(() =>
    {
        // Optional: My code when IsEnabled() returns 'false'.
    });

featureGate.Invoke();

Feature gate executions are recorded every time a feature gate is invoked. A feature gate may be invoked multiple times.

Construction

The easiest way to create a feature gate is to call the static method FeatureGate.WithKey("MyFeatureGateKey") which will return a FeatureGateBuilder. The FeatureGateBuilder will allow you to chain methods to help you correctly create the type of feature gate you need.

Alternatively you can instantiate the type of feature gate you need by calling its constructor. There are only four types;

• FeatureGate
• FeatureGateAsync
• FeatureGate<TResult>
• FeatureGateAsync<TResult>

Once created feature gates are immutable. Calling methods that mutate a feature gate will return a new instance of that feature gate with that mutation.

Feature Gate Key

The feature gate key is a unique string identifier that you define for each of your feature gates. Using the same name as the feature flag that controls your feature gate is recommended. If your feature flag controls more than one feature gate, adding an identifying suffix to the feature gate key for each feature gate is recommended.

Warning - Failure to give each of your feature gates in your application a unique feature gate key will result in inaccurate metrics being collected for those feature gates.

Instrument Types

By default, feature gates are configured to record executions using a counter. If you want to capture timings for your feature, you can change the instrument type of your feature gate during its construction to a histogram. Histograms should be used cautiously as they use more memory than counters.

Metrics

Warning - Metric names currently unstable.

Depending on the instrument type configured for a feature gate, feature gates will output one of the following metrics.

Metric Attributes

Warning - Metric attributes currently unstable.

The metrics that feature gates output can be aggregated or filtered on the following dimensions.

Metric Collection

In order to collect metrics from your feature gates, you will need to subscribe to the Meter named FeatureGates. If using the OpenTelemetry .NET SDK, you can do this by calling AddMeter("FeatureGates") while building your MeterProvider. For example;

using MeterProvider meterProvider = Sdk.CreateMeterProviderBuilder()
    // Other configuration
    .AddMeter("FeatureGates")
    // Other configuration
    .Build();

It is also possible to subscribe to the metrics from your feature gates by using a MeterListener.

To learn more on how to collect metrics, please checkout the metrics collection tutorial at the .NET documentation website.

Traces

Feature gates also output spans that represent feature gate executions to be included in traces. These spans will have the operation name feature.gate.execution so that you can easily identify them in a trace.

A span is also known as an Activity in .NET.

Span Attributes

Warning - Span attributes are currently unstable.

Spans emitted by feature gates will have the following attributes.

Span Events

Warning - Span event attributes are currently unstable.

When an uncaught exception occurs during a feature gate execution, a span event will be added to the span with the details of the exception. The span event will have the following details.

Span Collection

In order to collect spans from your feature gates, you will need to subscribe to the ActivitySource named FeatureGates. If using the OpenTelemetry .NET SDK, you can do this by calling AddSource("FeatureGates") while building your TracerProvider. For example;

using TracerProvider tracerProvider = Sdk.CreateTracerProviderBuilder()
    // Other configuration
    .AddSource("FeatureGates")
    // Other configuration
    .Build();

It is also possible to subscribe to spans from your feature gates by using an ActivityListener.

To learn more on how to collect spans, please checkout the trace collection tutorial at the .NET documentation website.