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 flag5 labels: {}) // additional attributes about this invocation6...
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')23module.exports.handler = async (event) => {4 start = Date.now()56 // If there is an experiment defined for this failure-flag, that is also7 // targeting the HTTP method and or path then this will express the8 // 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)45...67// 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 flag10 Labels: map[string]string{ // Additional metadata experiments can use for targeting11 `method`: request.HTTPMethod,12 `path`: request.Path,13 }})14...