Installing the Failure Flags SDK

This document will walk you through adding the Failure Flags SDK to your application. This lets you add fault injection points to your application code for greater customization over your experiments, but requires making and deploying code changes.

‍

Failure Flags is available for these languages:

• Node.js
• Python
• Java
• Go
• C# / .NET

‍

How the Failure Flags SDK works

The Failure Flags SDK lets you create points ("Flags") in your application where you can inject faults. Flags are added by calling the SDK's invoke() method. When this method is called during your application's execution, the SDK checks with the sidecar container to see if there's an active experiment running that matches the name (and any additional labels you provide) of the Failure Flag. If so, it applies the experiment's effects. If not, it remains inactive and your application continues to execute normally.

We recommend adding Failure Flags to critical parts of your application, such as:

• Immediately before or after a call to a network dependency, such as a database.
• Before or during critical operations.
• During your application’s startup and/or shutdown process.

‍

Failure Flags attributes

The Failure Flags SDKs have two primary attributes: name and labels.

‍

Failure Flag name

name is the name that Gremlin uses to identify the Failure Flag, e.g. the name that appears. in the Gremlin web app. This attribute is required.

‍

Failure Flag labels

labels is an optional list of key-value pairs where you can provide tags for targeting. These work similar to network tags in the Gremlin agent. You can use variables from your application as values for more thorough targeting.

For example, if your application processes HTTP requests, you could run an experiment that only impacts POST requests. To do this, add a label with method as the key, and the current request’s HTTP method (GET, POST, PUT, etc.) as the value. When you create a new Failure Flags experiment, you can then use the method label to selectively run the experiment on POST requests.

‍

Enabling the Failure Flags SDK

By default, the SDK will not run when deployed. You'll need to enable it by setting the following environment variable:

‍

Node.js

The Node.js Failure Flags SDK is available on NPM, and the source is available on GitHub.

First, add @gremlin/failure-flags to your dependencies:

npm install --save @gremlin/failure-flags

‍

Next, instrument the part of your application where you want to perform experiments by adding invokeFailureFlag() as shown below. For example, this code creates a new Failure Flag named “http-ingress” with two labels: method with the current request’s HTTP method, and path with the current URL path:

const gremlin = require('@gremlin/failure-flags')

module.exports.handler = async (event) => {
  // If there is an experiment defined for this failure-flag, that is also
  // targeting the HTTP method and or path then this will express the
  // effects it describes.
  await gremlin.invokeFailureFlag({
    name: 'http-ingress',
    labels: {
      method: event.requestContext.http.method,
      path: event.requestContext.http.path,
    },
  })
}

‍

Python

The Python Failure Flags SDK is available on PyPi, and the source is on GitHub.

First, add failureflags to your package dependencies:

pip install failureflags

‍

Next, instrument the part of your code where you want to perform experiments by adding FailureFlag().invoke(). Include the name and labels attributes in the method call. For example

from failureflags import FailureFlag
...
FailureFlag(name: 'MyPthonFlag', labels: {
  method: 'GET',
  path: '/api/v1'
}).invoke()
...

‍

Java

The Java Failure Flags SDK artifacts (jars, sources, and javadocs) are available in our Maven repository, and the source is on GitHub.

First, add failureflags to your package dependencies. For example, in your build.gradle file, add the following implementation dependency:

dependencies {
  implementation 'com.gremlin:failure-flags-java:1.2'
}

‍

Under repositories, add:

maven {
  url 'https://maven.gremlin.com/'
}

‍

Next, instrument the part of your code where you want to perform experiments by adding FailureFlags().invoke(). For example:

import com.gremlin.failureflags.*
...
FailureFlags gremlin = new GremlinFailureFlags();
        
gremlin.invoke(new FailureFlag(
    "http-ingress", 
    Map.of(
        "method", someVariable,
        "path", someOtherVariable)));
...

‍

Go

The Go Failure Flags SDK artifacts source is available on GitHub.

First, add github.com/gremlin/failure-flags-go your package dependencies:

go get github.com/gremlin/failure-flags-go

‍

Next, import the SDK and instrument the part of your code where you want to perform experiments. For example:

import (
    gremlin "github.com/gremlin/failure-flags-go"
)
...
// Add a fault injection point. Active experiments from Gremlin that match this Failure Flag will execute here.
gremlin.Invoke(gremlin.FailureFlag{
    Name: 'http-ingress',       // The name of your failure flag
    Labels: map[string]string{  // Additional metadata experiments can use for targeting
            'method': request.HTTPMethod,
            'path': request.Path,
        }})
...

‍

.NET

The .NET SDK is available on NuGet, and the source code is available on GitHub.

First, add the Gremlin.FailureFlags SDK to your project dependencies by running this command in the directory containing your .csproj file:

dotnet add package Gremlin.FailureFlags

‍

Next, instrument the part of your code where you want to perform experiments. For example:

using System.Collections.Generic;
using FailureFlags;
...
var gremlin = new GremlinFailureFlags();

gremlin.Invoke(new FailureFlag()
{
    Name = "http-ingress",
    Labels = new Dictionary<string, string>()
    {
        { "method", "GET" },
        { "path", "/api/v1/health" }
    }
});
...

‍