User-defined metrics can be pushed to GSLB.me on a per-target basis.

A flexible evaluation language is then used to compare, evaluate and aggregate such raw variables/indicators, in order to determine whether the given target is available or not.

Pushing metrics

After defining all metrics names, descriptions and types using GSLB.me GUI, metrics readings must be pushed from external servers or applications to GSLB.me. This can be easily achieved through HTTP POST requests.

Metrics must be pushed to GSLB.me:

  • Waiting at least 30 seconds (180 seconds for free users) between two consecutive updates for each metric
  • At least once every 300 seconds (5 minutes). Pushed metrics are automatically purged by GSLB.me after 300 seconds.
  • An unlimited number of metrics can be pushed (1 metrics at a time for free users)

Requests and responses formats are as follows.

Request

POST /metrics?geohost=geohost.name.tld&target=a.b.c.d&variable=variable_name&value=1234 HTTP/1.0
Host: check.gslb.me
Authorization: Basic base64_credentials

Where:

  • geohost is the name of the geohost you are pushing the metrics for (ie.: geohost.mydomain.com)
  • a.b.c.d is the IP address of the geohost target you are pushing the metrics for (ie. 1.2.3.4)
  • variable_name is the name of a metrics variable that was configured using GSLB.me web interface (ie. cpu_load)
  • 1234 is the value you want to set for the variable

Using curl (all in one line):

curl -i -u testuser@gslb.me:testpassword -X 
  POST "https://check.gslb.me/metrics?geohost=geohost.name.tld&target=a.b.c.d&variable=variable_name&value=1234"

Response

  • If successful:
HTTP/1.1 200 OK 
Server: nginx
Date: Fri, 11 Mar 2016 14:30:40 GMT
Content-Type: application/json
Content-Length: 20
Connection: keep-alive
Strict-Transport-Security: max-age=31536000; includeSubdomains

{ "outcome": "OK" }
  • In case two consecutive updates for the same metrics+target+geohost are pushed in less than 60 seconds (minimum update interval) for paid users, or less than 180 seconds for free users:
HTTP/1.1 403 Forbidden
Server: nginx
Date: Fri, 11 Mar 2016 00:06:42 GMT
Content-Type: application/json
Content-Length: 55
Connection: keep-alive
{ "outcome": "Minimum update interval is 60 seconds" }
  • If the specified variable does not exist:
HTTP/1.1 404 Not Found
Server: nginx
Date: Fri, 11 Mar 2016 00:07:07 GMT
Content-Type: application/json
Content-Length: 34
Connection: keep-alive
{ "outcome": "Invalid variable" }
  •  If the specified variable value is invalid (this may indicate the the variable value and the configured variable type mismatch):
HTTP/1.1 406 Not Acceptable
Server: nginx
Date: Fri, 11 Mar 2016 00:07:18 GMT
Content-Type: application/json
Content-Length: 31
Connection: keep-alive
{ "outcome": "Invalid value" }
  •  If a free user tries to push more than one metrics per target at the same time
HTTP/1.1 406 Not Acceptable
Server: nginx
Date: Fri, 11 Mar 2016 00:07:20 GMT
Content-Type: application/json
Content-Length: 31
Connection: keep-alive
{ "outcome": "Free metrics support one variable at a time per target" }
  •  If the specified target does not exist:
HTTP/1.1 404 Not Found
Server: nginx
Date: Fri, 11 Mar 2016 00:07:32 GMT
Content-Type: application/json
Content-Length: 32
Connection: keep-alive
{ "outcome": "Invalid target" }
  •  If the specified geohost does not exist:
HTTP/1.1 404 Not Found
Server: nginx
Date: Fri, 11 Mar 2016 00:07:46 GMT
Content-Type: application/json
Content-Length: 33
Connection: keep-alive
{ "outcome": "Invalid geohost" }

 

Evaluation expressions syntax

Evaluation expressions format must be:

output=[expr]

where:

  • output is the mandatory variable that is populated with the result of [expr]. Output is expected to be set either to zero or not zero:

    • if expr evaluation returns a zero value, output is set to zero, and this means that the return value is “down”, “unavailable”
    • if expr evaluation returns a non-zero value output is set to the value itself, and this means that the return value is “up”, “available”
  • expr is a customizable set of conditions that defines the rules that will be evaluated

expr can be:

  • [metrics name]
  • [number]
  • [expr][operator][expr]
  • [function([expr],…,[expr])]

operator can be:

  • + (addition)
  • – (subtraction)
  • * (multiplication)
  • / (division)
  • ^ (exponent)
  • < (less than)
  • > (greater than)
  • ? (equality)
  • & (bitwise AND)
  • | (bitwise inclusive OR)
  • ! (bitwise exclusive OR)

function is the name of one of the currently supported functions:

  • abs(expr) – returns the absolute value of expr
  • and(expr,expr) – returns the logical AND of the two expr
  • avg(expr,…,expr) – returns the arithmetic mean of the specified expr
  • case(expr1,result1,…,exprN,resultN) – implements an “if-elseif” statement. If expr1 is true, the result is result1, otherwise the next expr is evaluated until a true one is found and the corresponding resultN is returned
  • if(expr1,expr2,expr3) – if expr1 is true then expr2, else expr3
  • log(expr) – returns the base “e” logarithm of expr
  • max(expr1,…,exprN) – returns the value of the expr that returned the maximum value
  • min(expr1,…,exprN) – returns the value of the expr that returned the minimum value
  • or(expr,expr) – returns the logical OR of the two expr
  • random(expr) – returns a random floating point number between 0 and expr
  • rounddown(expr) – rounds down the value of expr
  • roundup(expr) – rounds up the value of expr
  • sqrt(expr) – returns the square root of expr
  • strcmp(expr,expr) – returns 1 if the two expr results are identical when compared as case sensitive strings
  • strcmpi(expr,expr) – returns 1 if the two expr results are identical when compared as case insensitive strings
  • strlen(expr) – returns the number of characters that form the value of expr
  • sum(expr,…,expr) – returns the sum of the values of all expr
  • val(expr) – returns the value of expr – this is semantically identical to “expr“

Sample usage

Metrics evaluation expressions can be fully customized and can be as complex as needed, here’s some usage examples:

output=cpu_load<50 returns an “up” state if cpu_load is less than 50
output=and(cpu_load<50,free_mem>1024) returns an “up” state if cpu_load is less than 50 AND free_mem is greater than 1024
output=(memory_per_user*users_number)<(total_memory*0.8) returns an “up” state if the amount of memory used by the application (memory_per_user * users_number) does not exceed 80% of the total available memory (total_memory)
output=case(db_queries<50,1,and(db_queries>49,unix_load<4),1,1,0) if the number of database queries is less than 50 (db_queries<50) returns “1” (“up”), otherwise checks to see if the number of database queries is greater than 49 AND the unix load is less than 4. If this is true, returns “1” (“up”), otherwise returns “0” (“down”). The last part of the expression here is “,1,0)” the “1” parameter is an expression that is evaluated as always true (ie. non-zero), hence the last parameter “0” is returned as a fallback for the whole “case” function