Failure Flags > Installing the Failure Flags SDK

Installing the Failure Flags SDK

No items found.

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.

Note

It is safe to add a Failure Flags SDK to and leave in your application. All the Failure Flags components (all the SDKs, and agents) will fail-safe if the agent is misconfigured, can't communicate with your application, or can't communicate with the Gremlin API. In other words, there will never be adverse impact to your application unless all configuration is in place, and you're actively running an experiment.

‍

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 environment variable when you run the application where you add the SDK.

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

JAVASCRIPT


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

JAVASCRIPT


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

‍

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


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

module.exports.handler = async (event) => {
  start = Date.now()

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

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:


pip install failureflags

‍

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

PYTHON


from failureflags import FailureFlag

...

FailureFlag(name: 'flagname', labels: {}).invoke()

...

‍

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:

GRADLE


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

‍

Under repositories add this maven repository:

GRADLE


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

‍

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

JAVA


import com.gremlin.failureflags.*
...

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

...

‍

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:


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


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. You can add it to your project dependencies by running this command in the directory containing your .csproj file:

.NET


dotnet add package Gremlin.FailureFlags

‍

Next, import the SDK into your application and instrument the part of your code where you want to inject faults. For example, this code creates a new Failure Flag named http-ingress:

.NET


using System.Collections.Generic;
using FailureFlags;

...
var gremlin = new GremlinFailureFlags();

gremlin.Invoke(new FailureFlag()
{
    Name = "http-ingress"
});
...

‍

You can provide additional tags for matching a Failure Flag using the labels property. For example, the following flag includes a method label containing an HTTP method and a path label containing a URL. You can use variables in place of these.

.NET


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" }
    }
});
...

‍

Finally, enable the Failure Flags SDK at runtime by setting the FAILURE_FLAGS_ENABLED environment variable to true when you run your application.

Deploying Failure Flags on Kubernetes

Running Failure Flags experiments