Skip to content

Latest commit

 

History

History
97 lines (80 loc) · 4.64 KB

README_qos.md

File metadata and controls

97 lines (80 loc) · 4.64 KB
Raw

gateleen-qos

Introduces a Quality of Service network traffic. An example on how to integrate this feature in a communication server can be found in the class org.swisspush.gateleen.AbstractTest.

The QoS feature is controlled by a ruleset which you have to PUT according to this example.

PUT gateleen/server/admin/v1/qos

{
  "config":{
    "percentile":75,
    "quorum":40,
    "period":5,
    "minSampleCount" : 1000,
    "minSentinelCount" : 5
  },
  "sentinels":{
    "sentinelA":{
      "percentile":50
    },
    "sentinelB":{},
    "sentinelC":{},
    "sentinelD":{}
  },
  "rules":{
    "/test/myapi1/v1/.*":{
      "reject":1.2,
      "warn":0.5
    },
    "/test/myapi2/v1/.*":{
      "reject":0.3
    }
  }
}

The config section defines the global settings of the QoS.

Setting Description
percentile Indicates which percentile value from the metrics will be used (eg. 50, 75, 95, 98, 999 or 99)
quorum Percentage of the the sentinels which have to be over the calculated threshold to trigger the given rule.
period The period (in seconds) after which a new calculation is triggered. If a rule is set to reject requests, it will reject requests until the next period.
minSampleCount The min. count of the samples a sentinel has to provide to be regarded for the QoS calculation.
minSentinelCount The min count of sentinels which have to be available to perform a QoS calculation. A sentinel is only available if it corresponds to the minSampleCount rule.

The sentinels section defines which metrics (defined in the routing rules) will be used as sentinels. To determine the load, the lowest measured percentile value will be preserved for each sentinel and put in relation to the current percentile value. This calculated ratio is later used to check if a rule needs some actions or not. You can override the taken percentile value for a specific sentinel by setting the attribute percentile as shown in the example above. To define the minimal lowest percentile value for a single sentinel, you can add the attribute minLowestPercentileValueMs. When updating the QoS settings, the current lowest percentile value will be raised to minLowestPercentileValueMs when lower than minLowestPercentileValueMs.

The rules section defines the rules for the QoS. Each rule is based on a pattern like the routing rules. The possible attributes are:

Attribute Description
reject The ratio (eg. 1.3 means that <quorum> % of all sentinels must have an even or greater current ratio) which defines when a rule rejects the given request.
warn The ratio which defines when a rule writes a warning in the log without rejecting the given request

Information: You can combine warn and reject.

Attention: Be aware that a metric is only available (in JMX) after a HTTP request (PUT/GET/...) was performed. Therefore it’s correct if the log shows something like MBean X for sentinel Y is not ready yet ... The QoS feature considers only available metrics (from the sentinels) for its calculation.

Schema validation

Updating the QoS configuration resource requires a validation against a schema to be positive. Check the schema gateleen_qos_schema_config

Log QoS ruleset changes

To log the payload of changes to the Qos ruleset, the RequestLogger can be used.

Make sure to instantiate the RequestLoggingConsumer by calling

RequestLoggingConsumer requestLoggingConsumer = new RequestLoggingConsumer(vertx, loggingResourceManager);

To enable the logging of the Qos ruleset, make sure the url to the ruleset is enabled in the logging resource.

Example:

{
  "headers": [],
  "payload": {
    "filters": [
      {
        "url": "/playground/server/admin/v1/.*",
        "method": "PUT"
      }
    ]
  }
}

Also you have to enable the logging on the QoSHandler by calling

qosHandler.enableResourceLogging(true);