SpikeArrest reference

Spike arrest policy

• About this policy
• Example: Declaring the spike arrest policy
• Example: Applying the spike arrest policy to a path
• NPM modules
• Configuration options
• Policy attributes
• Use with helper functions
• Usage notes
• What's the difference between spike arrest and quota?
• For more information

About this policy

The Spike Arrest policy protects against traffic spikes. It throttles the number of requests processed by an API proxy and sent to a backend, protecting against performance lags and downtime.

Example: Declaring the spike arrest policy

In this example, the "memory" spike arrest module is declared and configured for an a127 project.

Note that in this example, the name of the spike arrest policy instance is myspikearrest. You'll reference this name when you apply the spike arrest to a path.

  a127-services:
    myspikearrest:
      provider: volos-spikearrest-memory
      options:
        timeUnit: "minute"
        bufferSize: 10
        allow: 10

Example: Applying the spike arrest policy to a path

In this example, the spike arrest policy is applied to the /hello path, and a helper function is configured. The helper source file is ./api/helpers/spikearrest.js. And, the setKey function will be called each time this policy is executed.

The name of the service instance in this example is myspikearrest, and that name must match the name that was used when the spike arrest service was declared.

  paths:     
    /hello:
        x-swagger-router-controller: hello_world
        x-a127-apply:
          myspikearrest:
            key:
                helper: spikearrest
                function: setKey
            weight: 2
            allow: 12

NPM modules

You must install the volos-spikearrest-memory NPM module to use this feature. This module stores spike arrest counts in local memory. Note that this module is installed automatically when you create a new a127 project.

You can read more about this open-source module in the apigee-127/volos repository on GitHub.

Configuration options

Set these configuration options when you declare the policy in the a127-services part of your project's swagger.yaml file:

  a127-services:
    <spikearrest-name>:
      provider: volos-spikearrest-memory
      options:
        timeUnit: <seconds|minutes>
        bufferSize: <integer>
        allow: <integer>

• spikearrest-name - (string) The name of this spike arrest policy instance. You use this declared name when you apply the policy to a path. Required.

• npm-module-name - (string) The name of the spike arrest NPM module. Currently, the only option is volos-spikearrest-memory. See NPM modules. Required.

• timeUnit: (string) How often the spike arrest execution window resets - may be in seconds or minutes. Default: second

• allow: (integer) The maximum number of requests to allow during the timeUnit. Default: 1

• bufferSize: (integer) If bufferSize > 0, the spike arrest policy will attempt to smooth requests by returning only when the next appropriate execution window is available. bufferSize is how many requests to "queue" before returning (immediately). Default: 0

Policy attributes

Set these attributes when you apply the policy to a path:

  x-a127-apply:
    <spikearrest-name>:
      key: <string>
      weight: <integer>
      allow: <integer>

• spikearrest-name - (string) The name of the spike arrest policy instance to apply. This name must correspond to the name of a spike arrest policy declared in a127-services. Required.

• key - (string) Identifies a spike arrest instance or "bucket". This is a string that may be set to any value. Each key locates a single spike arrest instance, which is separate from other instances. Default: _default

• weight - (integer) Not commonly used. Specifies the weighting defined for each message. Message weight is used to modify the impact of a single request on the calculation of the Spike Arrest limit. Message weight can be set by variables based on HTTP headers, query parameters, or message body content. For example, if the Spike Arrest Rate is 10 per minute, and an app submits requests with weight 2, then only 5 messages per minute are permitted from that app. Default: 1

• allow: (integer) The maximum number of requests to allow during the timeUnit. Overrides the allow value set in the policy configuration. Default: 1

Use with helper functions

You can use helper functions to set spike arrest policy attributes programmatically, such as the spike arrest key. For example, you could set the key based on a value obtained from the request, such as a query parameter or header. See Understanding helper functions.

Usage notes

• In general, you should use Spike Arrest to set a limit that throttles traffic to what your backend services can handle.

• No counter is maintained for spike arrests, only a time that the last message was successfully passed through the Spike Arrest policy.

What's the difference between spike arrest and quota?

It’s important to choose the right tool for the job at hand. Quota policies configure the number of request messages that a client app is allowed to submit to an API over the course of an hour, day, week, or month. The quota policy enforces consumption limits on client apps by maintaining a distributed counter that tallies incoming requests.

Use a quota policy to enforce business contracts or SLAs with developers and partners, rather than for operational traffic management. For example, a quota might be used to limit traffic for a free service, while allowing full access for paying customers. See also [Quota policy](See also Spike arrest policy.)

Use spike arrest to protect against sudden spikes in API traffic. Typically, spike arrest is used to head off possible DDoS or other malicious attacks.

For more information

*How does spike arrest work.

• Adding a spike arrest policy
• Blog: Protect your Apigee-127 API with spike arrest
• weather-advanced sample on GitHub
• spikearrest-example on GitHub