Simulating Latency

Overview

API Simulator allows for configuring latency as a delay added to any network latency and request processing time.

definition

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 non-blocking 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 simulation-specific 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 top-level 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 50th 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 "upside-down-bowl" shape to a "right-side-up-bowl" shape).

Normal Distribution Example
Normal Distribution example: mean = median = 100, standard deviation = 1.5

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 log-normally distributed if Y = ln(X) is normally distributed, where ln denotes the natural logarithm.

The LogNormal distribution is only defined for non-negative values and is positively skewed.

A log-normally 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 50th percentile of the distribution. API Simulator uses this parameterization.

LogNormal Distribution Example
LogNormal Distribution example: mean = ln(median = 100), standard deviation = 0.4

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 case-insensitive 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!