Installing the Failure Flags SDK

This document will walk you through adding the Failure Flags SDK to your application. Failure Flags is currently available for Node.js, Python, Java, and Go.

Node.js

Find the SDK on NPM. You can find the source on GitHub.

You'll need to enable the SDK by setting the FAILURE_FLAGS_ENABLED environent variable when you run the application where you add the SDK.

For Node.js applications, start by adding @gremlin/failure-flags to your dependencies:

1npm i --save @gremlin/failure-flags

Next, instrument the part of your application where you want to perform experiments by adding invokeFailureFlag(). Give the flag a name using the name: 'myfailureflag' property. This method checks to see if there's an active experiment running that matches the name of the failure flag (and any additional labels you provide), and if so, runs the experiment. Otherwise, it remains inactive and your application code executes normally. We recommend adding a failure flag immediately before or after a call to one of your network dependencies, such as a database.

1const failureflags = require(`@gremlin/failure-flags`);
2...
3await failureflags.invokeFailureFlag({
4  name: 'flagname', // the name of your failure flag
5  labels: {})       // additional attributes about this invocation
6...

You can provide additional tags for matching a Failure Flag using the labels property. For example, this flag has the name http-ingress. It also includes the current HTTP request method and URL path in the labels property.

1const gremlin = require('@gremlin/failure-flags')
2
3module.exports.handler = async (event) => {
4  start = Date.now()
5
6  // If there is an experiment defined for this failure-flag, that is also
7  // targeting the HTTP method and or path then this will express the
8  // effects it describes.
9  await gremlin.invokeFailureFlag({
10    name: 'http-ingress',
11    labels: {
12      method: event.requestContext.http.method,
13      path: event.requestContext.http.path,
14    },
15  })
16}

Python

Find the SDK on PyPI. You can find the source on GitHub.

You'll need to enable the SDK by setting the FAILURE_FLAGS_ENABLED environent variable when you run the application where you add the SDK.

You can get started by adding failureflags to your package dependencies:

1pip install failureflags

Then instrument the part of your application where you want to inject faults.

1from failureflags import FailureFlag
2
3...
4
5FailureFlag(name: 'flagname', labels: {}).invoke()
6
7...

Java

Find the Java Failure Flags SDK artifacts (jars, sources, and javadocs) through our Maven repository: https://maven.gremlin.com. You can find the source on GitHub.

You'll need to enable the SDK by setting the FAILURE_FLAGS_ENABLED environent variable when you run the application where you add the SDK.

You can get started by adding failureflags to your package dependencies. In your application's build.gradle, add the following implementation dependency:

1dependencies {
2  implementation 'com.gremlin:failure-flags-java:1.0'
3}

Under repositories add this maven repository:

1maven {
2  url 'https://maven.gremlin.com/'
3}

Then bring in the library and instrument the part of your application where you want to inject faults.

1import com.gremlin.failureflags.*
2...
3
4FailureFlags gremlin = new GremlinFailureFlags();
5        
6gremlin.invoke(new FailureFlag("flagname", Maps.of("key", "value")));
7
8...

Go

You can find the source on GitHub.

You'll need to enable the SDK by setting the FAILURE_FLAGS_ENABLED environent variable when you run the application where you add the SDK.

For Go/Golang applications, start by adding the following to your package dependencies:

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

Next, instrument the part of your application where you want to perform experiments by adding Invoke(). Give the flag a name using the Name property. This method checks to see if there's an active experiment running that matches the name of the failure flag (and any additional labels you provide), and if so, runs the experiment. Otherwise, it remains inactive and your application code executes normally. We recommend adding a failure flag immediately before or after a call to one of your network dependencies, such as a database.

You can provide additional tags for matching a Failure Flag using the Labels property. For example, this flag has the name http-ingress. It also includes the current HTTP request method and URL path in the Labels property:

1import (
2    gremlin "github.com/gremlin/failure-flags-go"
3)
4
5...
6
7// Add a fault injection point. Active experiments from Gremlin that match this Failure Flag will execute here.
8gremlin.Invoke(gremlin.FailureFlag{
9    Name: `http-ingress`,       // The name of your failure flag
10    Labels: map[string]string{  // Additional metadata experiments can use for targeting
11            `method`: request.HTTPMethod,
12            `path`: request.Path,
13        }})
14...