SAYMON Hosts – SAYMON Server Setup

This post is written for SAYMON Server administrators, devops and developers. If you are not – it is highly recommended to find one and show this text to them.

SAYMON Hosts mobile application downloads a dictionary from SAYMON Server to filter, rename and show metrics. So if the dict is not found you see “Translation for current locale not found on server” message instead of the hosts’ list.

Do not forget to use your own <server_address>, <login> and <password> values in the examples below!

Check if the dictionary exists

Run one of the following commands in a terminal and check if there is “name”:”hosts_app_en” string in the reply.

Check dict by nameGet names for all dictsGet all dicts

This one gets all dictionaries and searches name of the dict for SAYMON Hosts app:

curl https://<server_address>/node/api/dictionaries \
  -u '<login>:<password>' \
  | grep -o '"name":"hosts_app_en"'

This one gets all dictionaries and shows their names:

curl https://<server_address>/node/api/dictionaries \
  -u '<login>:<password>' \
  | grep -o '"name":"[^"]*"'

This one gets all dictionaries and their contents:

curl https://<server_address>/node/api/dictionaries \
  -u '<login>:<password>'

If there is the dict with “hosts_app_en” name in the reply you are ready to go. In other case please read below.

Create dictionary

Here is the format of the dict for SAYMON Hosts app:

{
  "name": "hosts_app_en",
  "content": {
    "<metric_name_on_the_server>": "<metric_name_to_display_in_the_app>, <units>",
    ...,
    "<metric_name_on_the_server>": "<metric_name_to_display_in_the_app>, <units>"
  }
}

<metric_name_on_the_server>

This is the name of the metric how it is stored on the server. You can grab one in the data table or the header of any graph in SAYMON UI. Here are several examples:

percentageUsage.combined
MEM.percentUsed
hostName

SAYMON Hosts looks for metrics only in objects of “Host” class and their sub-objects (aka “children”).

<metric_name_to_display_in_the_app>

This is how the metric is displayed in SAYMON Hosts app. Here are counterparts for the metrics above:

CPU Usage
RAM Usage
Hostname

<units>

Units for the metrics to show in the app. This is not mandatory, but if use must be separated from <metric_name_to_display_in_the_app> with space and comma like this:

CPU Usage, %
RAM Usage, %

Let’s combine the all mentioned above:

{
  "name": "hosts_app_en",
  "content": {
    "percentageUsage.combined": "CPU Usage, %",
    "MEM.percentUsed":"RAM Usage, %",
    "hostName":"Hostname"
  }
}

And finally here is the command to add the dictionary to the server:

RequestReply
curl https://<server_address>/node/api/dictionaries \
  -u '<login>:<password>' \
  -X POST \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "name": "hosts_app_en",
  "content": {
    "percentageUsage.combined": "CPU Usage, %",
    "MEM.percentUsed":"RAM Usage, %",
    "hostName":"Hostname"
  }
}
EOF
{
  "name":"hosts_app_en",
  "content":"{
    \"percentageUsage.combined\":\"CPU Usage, %\",
    \"MEM.percentUsed\":\"RAM Usage, %\",
    \"hostName\":\"Hostname\"
  }",
  "id":"60422ef02a67cd3eea3c0fe8"
}

Update dictionary

If you want to add new metric to or change something in existing dict you need to get its id like this:

RequestReply
curl https://<server_address>/node/api/dictionaries \
  -u '<login>:<password>' \
  | grep -o '{"name":"hosts_app_en".*id.*}'
{
  "name":"hosts_app_en",
  "content":"{
    \"percentageUsage.combined\":\"CPU Usage, %\",
    \"MEM.percentUsed\":\"RAM Usage, %\",
    \"hostName\":\"Hostname\"
  }",
  "id":"60422ef02a67cd3eea3c0fe8"
}

In the reply you will get dict’s id like:

"id":"60422ef02a67cd3eea3c0fe8"

Now edit the desired fields in the dict, add its id to the URL and run the following command:

RequestReply
curl https://<server_address>/node/api/dictionaries/60422ef02a67cd3eea3c0fe8 \
  -u '<login>:<password>' \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "name": "hosts_app_en",
  "content": {
    "percentageUsage.combined": "CPU Usage, %",
    "MEM.percentUsed":"RAM Usage, %",
    "MEM.bytesTotal":"RAM Volume, bytes",
    "/.percentUsed":"Disk Usage, %",
    "/.bytesTotal":"Disk Volume, bytes",
    "eth0.address":"ETH_0 address",
    "networkInterfaces.IPv4":"IPv4 address",
    "hostName":"Hostname",
    "tasksNumber":"Number of Agent Tasks"
  }
}
EOF
{
  "id":"60422ef02a67cd3eea3c0fe8",
  "name":"hosts_app_ru",
  "content":"{
    \"percentageUsage.combined\":\"CPU Usage, %\",
    \"MEM.percentUsed\":\"RAM Usage, %\",
    \"MEM.bytesTotal\":\"RAM Volume, bytes\",
    \"/.percentUsed\":\"Disk Usage, %\",
    \"/.bytesTotal\":\"Disk Volume, bytes\",
    \"eth0.address\":\"ETH_0 address\",
    \"networkInterfaces.IPv4\":\"IPv4 address\",
    \"hostName\":\"Hostname\",
    \"tasksNumber\":\"Number of Agent Tasks\"
  }"
}

Finished!