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 and Go SDKs are coming soon).

Node.js

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 ifExperimentActive(). 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.ifExperimentActive({
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.ifExperimentActive({
10    name: 'http-ingress',
11    labels: {
12      method: event.requestContext.http.method,
13      path: event.requestContext.http.path,
14    },
15  })
16}

Go

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...