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, 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 <span class="code-class-custom">FAILURE_FLAGS_ENABLED</span> environent variable when you run the application where you add the SDK.

For Node.js applications, start by adding <span class="code-class-custom">@gremlin/failure-flags</span> 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 <span class="code-class-custom">invokeFailureFlag()</span>. Give the flag a name using the <span class="code-class-custom">name: 'myfailureflag' </span>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 <span class="code-class-custom">labels</span> property. For example, this flag has the name <span class="code-class-custom">http-ingress</span>. It also includes the current HTTP request method and URL path in the <span class="code-class-custom">labels</span> 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 <span class="code-class-custom">FAILURE_FLAGS_ENABLED</span> environent variable when you run the application where you add the SDK.

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

SH

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 <span class="code-class-custom">FAILURE_FLAGS_ENABLED</span> 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.0'
}

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", "POST")));

...

Go

You can find the source on GitHub.

You'll need to enable the SDK by setting the <span class="code-class-custom">FAILURE_FLAGS_ENABLED</span> 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

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

Next, instrument the part of your application where you want to perform experiments by adding <span class="code-class-custom">Invoke()</span>. Give the flag a name using the <span class="code-class-custom">Name</span> 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 <span class="code-class-custom">Labels</span> property. For example, this flag has the name <span class="code-class-custom">http-ingress</span>. It also includes the current HTTP request method and URL path in the <span class="code-class-custom">Labels</span> property:

GO

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,
        }})
...


No items found.
Previous
Next
Previous
This is some text inside of a div block.
Compatibility
Installing the Gremlin Agent
Authenticating the Gremlin Agent
Configuring the Gremlin Agent
Managing the Gremlin Agent
User Management
Integrations
Health Checks
Notifications
Command Line Interface
Updating Gremlin
Quick Start Guide
Services and Dependencies
Detected Risks
Reliability Tests
Reliability Score
Targets
Experiments
Scenarios
GameDays
Overview
Deploying Failure Flags on AWS Lambda
Deploying Failure Flags on AWS ECS
Deploying Failure Flags on Kubernetes
Classes, methods, & attributes
API Keys
Examples
Container security
General
Linux
Windows
Chao
Helm
Glossary
Alfi
Additional Configuration for Helm
Amazon CloudWatch Health Check
AppDynamics Health Check
Application Level Fault Injection (ALFI)
Blackhole Experiment
CPU Experiment
Certificate Expiry
Custom Health Check
Custom Load Generator
DNS Experiment
Datadog Health Check
Disk Experiment
Dynatrace Health Check
Grafana Cloud Health Check
Grafana Cloud K6
IO Experiment
Install Gremlin on Kubernetes manually
Install Gremlin on OpenShift 4
Installing Gremlin on AWS - Configuring your VPC
Installing Gremlin on Kubernetes with Helm
Installing Gremlin on Windows
Installing Gremlin on a virtual machine
Installing the Failure Flags SDK
Jira
Latency Experiment
Memory Experiment
Network Tags
New Relic Health Check
Overview
Overview
Overview
Overview
Overview
Packet Loss Attack
PagerDuty Health Check
Preview: Gremlin in Kubernetes Restricted Networks
Private Network Integration Agent
Process Collection
Process Killer Experiment
Prometheus Health Check
Role Based Access Control
Running Failure Flags experiments
Scheduling Scenarios
Shared Scenarios
Shutdown Experiment
Slack
Teams
Time Travel Experiment
Troubleshooting Gremlin on OpenShift
User Authentication via SAML and Okta
Users
Webhooks
Integration Agent for Linux
Test Suites
Restricting Testing Times
Reports
Enabling DNS collection