fault-injection

Injects delays or fixed responses for testing.

Category TransformationAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin fault-injectionPriority 11000

What it does

fault-injection makes a route misbehave on purpose, so that you can see how clients cope. Under Abort, a request is answered with HTTP status instead of reaching the backend. Under Delay, it is held for Duration and then goes on.

Each fault has a Percentage, the share of requests that meet it, and Vars, the conditions a request must pass to meet it. With neither, every request meets the fault. An abort is an answer the gateway gives itself, as How G8 handles a request describes.

When to use it

• Checking that a mobile app shows a helpful message, and not a blank screen, when the orders API answers 503.
• Measuring how a client behaves when one request in ten is slow, before a real backend gets slow.
• A drill limited to testers: the fault meets only requests that carry a header the testers send.
• Checking that a partner's client waits before it retries, when the abort answer carries a header that asks it to.

Not for answering for a backend that really fails — see api-breaker (Breaks the circuit to an unhealthy upstream and returns a fixed response).

Set it up

Delay one request in ten by two seconds to test how clients cope

Fill Delay as in the JSON below.

fault-injection · as the console saves it

{
  "delay": {
    "duration": 2,
    "percentage": 10
  }
}

Things to know

• Percentage — Left out, every request the conditions pass meets the fault.
• Percentage — A percentage of 0 is refused when you save. To pause a fault, take the plugin off the route.
• Vars — The console’s form draws one level of conditions; a value that nests deeper is kept as it is and edited in Raw JSON.
• Vars — Each entry is a group of conditions, even where it holds one. A flat list of conditions is refused when you save.
• Vars — An empty list of conditions is refused when you save.
• Body — A $name or ${name} is replaced by that request variable, and a name the request does not carry by nothing: $uri sends the request path. A backslash before the dollar stops the replacement but stays in the value.
• Headers — A $name or ${name} is replaced by that request variable, and a name the request does not carry by nothing: $uri sends the request path. A backslash before the dollar stops the replacement but stays in the value.
• Headers — A name carrying a colon is stored and sent percent-encoded: X-A:B arrives as X-A%3AB.
• A fault-injection with neither an abort nor a delay is refused when you save.
• AdviceRun a drill on a route of its own, or limit it with conditions to the clients that take part, so that other clients do not meet the fault.

Settings

The fields as the console shows them, section by section.

Abortabortobject

HTTP statusabort.http_statusintegerRequired

The status the request is answered with instead of reaching the upstream.

at least 200

Bodyabort.bodystring

The body sent with that status, such as Paused for a drill. Left out, the gateway's standard error page for the status is sent.

Headersabort.headersobject

Headers sent with the abort answer, such as Retry-After = 30. A name carrying a colon is stored and sent percent-encoded: X-A:B arrives as X-A%3AB. An object whose keys are a name without a colon, each with a string or number as its value.

at least 1 key

Percentageabort.percentageinteger

The share of matching requests that get the fault.

1 to 100

Varsabort.varsarray

Only requests matching one of these groups get the fault. Every condition inside a group must hold. A flat list of conditions is refused: an entry is always a group, even where it holds one condition.

1 to 20 items · lists of conditions on request variables: see Conditions on request variables

Delaydelayobject

Durationdelay.durationnumberRequired

How long the request is held before it goes on to the upstream.

at least 0 · in seconds

Percentagedelay.percentageinteger

The share of matching requests that are delayed.

1 to 100

Varsdelay.varsarray

Only requests matching one of these groups are delayed. Every condition inside a group must hold. A flat list of conditions is refused: an entry is always a group, even where it holds one condition.

1 to 20 items · lists of conditions on request variables: see Conditions on request variables

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.