Search documentation
Dashboard
Failure Flags

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:

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

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

javascript
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:

go
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:

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