Triggers

Triggers enable you to perform actions on Application Instances, based on conditions configurable for certain game hosting related metrics in your account.

Info

Triggers are currently only available for Game Servers deployed with our Game Hosting platform.

Trigger components

A trigger consists of 3 components that define which instances it should apply to, which metric to act on and which action to perform if the rule is triggered.

Figure 1: Trigger rule components

Pre-conditions

You can optionally -but recommended- narrow down the scope of a trigger by applying a precondition (filter) on the basis of (one of) the following instance properties:

• DC Location
• Deployment Environment
• Fleet
• Application
• Application Build

Rules

A Trigger rule defines on which metric the trigger should act and with which parameters.

Memory rule

The Memory rule allows you to add a trigger based on memory usage of an Application Instance.

CPU rule

The CPU rule allows you to add a trigger based on CPU usage of an Application Instance.

Time rule

The Time rule allows you to add a trigger based on the uptime of an Application Instance.

Conditions and time window

For each type of rule you can enter a value and a condition; whether the value should be smaller than, larger than, or equal to the value, and within which time window these measurements must be sequentially true.

Measurements are performed once every minute. If you have a time window of 5 minutes, it means that the condition must be true during the entire window (5 minutes) in order for the trigger to fire.

Actions

When a Trigger fires, you have the option to perform an action on the instance in question.

• Stop the instance
• Restart the instance
• Destroy the instance

All 3 actions include stopping an instance. As such, you can always pass parameters to indicate which stop method to use and in case of a graceful stop method, indicate the grace period in seconds.

API example

Create a new Trigger with a Memory rule, whereby an instance will be gracefully restarted if its memory usage is above 250 MB for a duration of 5 minutes.

Full API reference

HTTP request

POST /v3/trigger

Request body

{
  "name": "Restart based on > 250MB memory usage",
  "description": "Restart a game server if memory usage is more than 250MB for a period of 5 minutes",
  "conditions": [
    {
      "conditionId": 1, // Filter on DC Location - /v3/trigger/type/conditions
      "conditionValues": [
        "6" // Use location "i3D.net Rotterdam" - /v3/cloud/dcLocation
      ]
    }
  ],
  "rules": [
    {
      "ruleAction": 1, // Memory based rule - /v3/trigger/type/ruleActions
      "ruleDataType": 1, // Act on an application instance - /v3/trigger/type/ruleDataTypes
      "rule": {
          "operator": 3, // Greater than - /v3/trigger/type/operators
          "triggerWindow": 300, // Memory usage will be measured over a window of 5 minutes
          "threshold": 250 // The threshold value - 250 MB i this case
      }
    }
  ],
  "actions": [
    {
      "action": 2, // Restart the instance - /v3/trigger/type/actions
      "actionParameters": {
        "methodId": 9, // Gracefully stop via an Arcus instruction - /v3/application/stopMethod
        "timeout": 300 // Maximum grace period of 5 minutes
      }
    }
  ]
}

Response body

[
    {
        "id": "7140874690347088743",
        "name": "Restart based on > 250MB memory usage",
        "description": "Restart a game server if memory usage is more than 250MB for a period of 5 minutes",
        "conditions": [
            {
                "conditionId": 1,
                "conditionValues": [
                    "6"
                ]
            }
        ],
        "rules": [
            {
                "ruleAction": 1,
                "ruleDataType": 1,
                "rule": {
                    "operator": 3,
                    "triggerWindow": 300,
                    "threshold": 250
                }
            }
        ],
        "actions": [
            {
                "action": 2,
                "actionParameters": {
                    "methodId": 9,
                    "timeout": 300
                }
            }
        ],
        "createdAt": 1611660690,
        "changedAt": 0,
        "active": 1
    }
]