Simulating Latency
Overview
API Simulator allows for configuring latency as a delay added to any network latency and request processing time.
Simulated Latency is time "artificially" added to the total response time that an API consumer would experience. 
API Simulator offers several ways to model delay in response time. When simulating an existing API, use the one that is closer to the behavior of the real API.
API Simulator does not block the processing thread to simulate latency. Instead, it uses a nonblocking technique, which allows it to process large volumes of requests with very few threads and low CPU utilization. That makes it a perfect fit for more realistic simulations of API dependencies during performance testing using various value distributions for the simulated latency.
Notice that LogNormal and Normal Distributions (see below) have not been added to the Embedded API Simulator. Embedded API Simulator supports fixed and random delay for simulating latency, which should cover the Embedded API Simulator’s test cases. Latency with delay from LogNormal and Normal Distribution work great when using API Simulator in performance testing and that is not the typical use of the Embedded API Simulator.
When configuring latency/delay longer than 3 seconds, make sure to set netty.readTimeoutSeconds
in the simulator: http
section of simulationspecific Configuration File to a value that is bigger than the maximum configured latency.
Fixed Delay
# ...
response:
from: ...
latency:
# timeUnit is optional and defaults to 'milliseconds'
timeUnit: milliseconds
# Fixed delay with initial and subsequent times.
# Make them the same for a truly fixed delay.
fixed:
initial: 100
subsequent: 40
status: ...
...
The old toplevel element delay
is now deprecated and it will be removed in a future release. Please switch to using response.latency
.
Random Delay
# ...
response:
from: ...
latency:
timeUnit: milliseconds
# Random delay between the 'min' and 'max' values
random:
min: 50
max: 150
status: ...
...
Normal Distribution
The Normal Distribution  a.k.a. Gaussian or Laplace–Gauss  is sometimes informally called the "bell curve".
Any Normal Distribution has certain properties:

Its shape is symmetrical.

Its distribution has a bump in the middle, with tails going down and out to the left and right.

The mean and the median are the same and, due to the symmetry, they lie in the middle of the distribution.
The median is the 50^{th} percentile: the point in the values where 50% of them fall below that point, and 50% fall above it.
The standard deviation for a Normal Distribution measures the distance on the distribution from the mean to the inflection point (the place where the curve changes from an "upsidedownbowl" shape to a "rightsideupbowl" shape).
Using Normal Distribution, we can model simlets with latency values with some "outliers"  values that are few standard deviations away from the median. Notice that there can still be some outliers whereas values for a Random Delay lie strictly within the range [min
, max
], inclusive.
Here is how to define latency that uses normally distributed random values:
# ...
response:
from: ...
latency:
timeUnit: milliseconds
distribution:
normal:
median: 100.0
stdDev: 1.5
status: ...
...
LogNormal Distribution
A variable X
is lognormally distributed if Y = ln(X)
is normally distributed, where ln
denotes the natural logarithm.
The LogNormal distribution is only defined for nonnegative values and is positively skewed.
A lognormally distributed random variable X
can be expressed by
X = e ^ (μ + σ * Z)
where:

μ ("mu") is the mean of logarithmic values.

σ (sigma) is the standard deviation of logarithmic values, σ > 0.

Z is a standard normal random variable.
The lognormal distribution is commonly parameterized with
μ = ln(median)
where median
is the 50^{th} percentile of the distribution. API Simulator uses this parameterization.
It is to note that larger standard deviation value produces longer tail.
Here is how to define latency that uses lognormally distributed random values:
# ...
response:
from: ...
latency:
timeUnit: milliseconds
distribution:
lognormal:
median: 100
stdDev: 0.4
status: ...
...
Time Unit
The timeUnit
can be any of the following caseinsensitive values: nanoseconds
, microseconds
, milliseconds
, and seconds
. It is optional and defaults to milliseconds
when not specified.
Technically, minutes
, hours
, and days
are also valid values but hopefully you’ll never be using anything more than few seconds ;)
We would love to hear your feedback  send us a quick email to [feedback at APISimulator.com]
Happy API Simulating!