User and Programmer Guide for the FI- STAR Monitoring Service SE

Transcription

1 User and Programmer Guide for the FI- STAR Monitoring Service SE FI-STAR Beta Release Copyright Yahya Al-Hazmi, Technische Universität Berlin This document gives a short guide on how to use the FI-STAR Monitoring Service SE. In this document, we assume that the Monitoring Service SE is up and running and is also monitoring some hosts (e.g. physical and virtual machines). This document provides a guide for two types of users. On the one hand it provides a guide for a user or developer on how he could interact with this SE to retrieve his monitoring data on-demand. And on the other hand, provides also a guide for administrators not only to retrieve data but also on how they could manage, control different configurations, metrics, users, hosts, etc. The FI-STAR Monitoring Service SE provides monitoring information about parameters at the system as well as at the service layers to multiple stakeholders. Example parameters for system monitoring includes CPU usage, RAM consumption and network latency and throughput, while examples for service-related monitoring parameters include service availability, response time, load, throughput, etc. The Monitoring Service SE provides monitoring information via dashboard and GUI based interface to its stakeholders. It offers also a JSON-RPC API, and currently partial functions through a RESTful API. Guide for Users and Developers In order to use any of the Monitoring Service SE interfaces, you need user credentials (username and password). This is given by the admins. Web Frontend: Once you have the credentials, through the GUI based Web Frontend, you can access to the monitoring data, to which you have permissions, directly through any browser by browsing: or This depends on the installation that has been done. The former is used, if the Zabbix PHP files are moved to the /var/www/ directory, while the later if not. There you could have a read-only or even more permissions not only to get but also to create, update, delete metrics (a parameter can be measured through a metric), triggers, actions, or even hosts. In the following, we assume that the user has only a read-only permission. JSON-RPC API: The JSON-RPC API allows you to call any function such as Get, Create, Delete and Update hosts, metrics, triggers, actions, templates, and many other objects. All what you need is to send a POST request to

2 Or as follow, if the Zabbix PHP files are not moved to the /var/www/ directory: with input data in JSON format in the request body and interpret the answer formatted the same way. The command line tool curl can be used to transfer HTTP Post requests. You need to install this tool in your machine. To install curl, if you use Ubuntu for instance: apt-get install curl Then you can start retrieving monitoring data through the JSON-RPC API as follow: curl -i -X POST -H 'Content-Type: application/json' -d ' {<JSON- RPC_call>}' Or as follow, if the Zabbix PHP files are not moved to the /var/www/ directory: curl -i -X POST -H 'Content-Type: application/json' -d ' {<JSON- RPC_call>}' You need to replace the <JSON-RPC_call>,with a proper operation call from those listed in Table 1 and of course replace the <monitoring_server_ip> with the IP of the Monitoring Service SE. In each request you need to include your authentication token that you have got before. You can grant an authentication token for yourself. This is done by posting a request that includes the first operation listed in Table 1 as follow: curl -i -X POST -H 'Content-Type:application/json' -d'{"jsonrpc": "2.0","method":"user.authenticate","user":"Admin","passwor d":"zabbix"},"auth": null,"id":1}' You get the following response: HTTP/ OK Date: Fri, 09 May :05:05 GMT Server: Apache/ (Ubuntu) X-Powered-By: PHP/ ubuntu3.6 Content-Length: 68 Content-Type: application/json "result":"b8a4ad4e55959d97d7b6a38cbdaf5be3","id":0} You use the token that you have got as result in further requests. For example if you need to get the host ID, you post the following request: curl -i -X POST -H 'Content-Type:application/json' -d '"method":"host.get","output":"shorten"}, "auth":"b8a4ad4e55959d97d7b6a38cbdaf5be3","id":1}'

3 You get the following response: HTTP/ OK Date: Fri, 09 May :12:41 GMT Server: Apache/ (Ubuntu) X-Powered-By: PHP/ ubuntu3.6 Content-Length: 65 Content-Type: application/json "result":[{"hostid":"10093"},{"hostid":"10094"},{"h ostid":"10095"},{"hostid":"10100"}],"id":1} If you need to have in the response more details about the existing/monitored hosts, for instance the host IDs linked with their corresponding host names, you need to set the parameter "output" in the JSON call into "extend" instead of "shorten" as follow: curl -i -X POST -H 'Content-Type:application/json' -d '"method":"host.get","output":"extend"}," auth":"b8a4ad4e55959d97d7b6a38cbdaf5be3","id":1}' Table 1- Monitoring Metrics and Operations in JSON-RPC API Metric and Operation Name JSON-RPC_call getuserauthenticationtoken "method":"user.authenticate", "user":"<login>", "password":"<password>"}, "id":1 } gethostid "method":"host.get", "output":"extend"}, gethostboottime "search":{"key_":"system.boottime"}}, gethostuptime "search":{"key_":"system.uptime"}}, gethostlocaltime {"jsonrpc": "2.0", "search":{"key_":"system.localtime"}}, getcpuidletime "search":{"key_":"system. cpu.util[,<idle>, avg1]"}}, getcpuiowaittime "search":{"key_":"system. cpu.util[,<iowait>, avg1]"}},

4 getcpunicetime getcpusystemtime getcpuusertime getcachedmemory getfreememory getsharedmemory gettotalmemory getbuffermemory getfreeswapmemory getingoingtrafficoninterface X getoutgoingtrafficoninterface X "search":{"key_":"system. cpu.util[,<nice>, avg1]"}}, "search":{"key_":"system. cpu.util[,<system>, avg1]"}}, "search":{"key_":"system. cpu.util[,<user>, avg1]"}}, "search":{"key_":"vm.memory.size[cached]"}}, "search":{"key_":"vm.memory.size[free]"}}, "search":{"key_":"vm.memory.size[shared]"}}, "search":{"key_":"vm.memory.size[total]"}}, "search":{"key_":"vm.memory.size[buffers]"}}, "search":{"key_":"system.swap.size[,free]"}}, "search":{"key_":"net.if.out[eth0,bytes]"}}, "search":{"key_":"net.if.in[eth0,bytes]"}},

5 getnetworklatency getpacketloss getserviceavailability getserviceload getserviceaccesslog getgraphs "search":{"key_":"icmppingsec[,,,,,]"}}, "search":{"key_":"icmppingloss[,]"}}, "search":{"key_":"net.tcp.service[ssh,,]"}}, Equivalent to the load utilization metric per VM, in case a service (SE) and only one is deployed within one VM. Supported in form of a probe that can be then configured by the user/admin to store whatever log files available through using the provided probe called add-log-metrics.py. "method":"graph.get", "output":"extend"}, User-defined-metrics Users have the ability to add their own defined metrics (also called custom metrics) by using piece of software. For adding your own metrics, you need to do the following: 1. Login into the VM where metric(s) need to be created. 2. Then execute the Shell script with sudo rights add-user-defined-metricszabbix which is located at /usr/local/bin/. You will be asked to enter the metric details as shown in the following figure. This script will then configure the local zabbix agent and the server automatically. The server is configured using another script configureserver.py that is located at /usr/local/lib/. The key and command properties and their order are mandatory. The last three properties are optional and their order is not important. The default values of the last three optional properties are used, if they are not set to any value.

6 RESTful API: The RESTful API allows you currently only to Get monitoring information about exiting metrics. This can be done by posting a request to by identifying the calledmethod. You will then get a response including the results. Table 2 shows metrics (already supported and those To Be Done) with their corresponding function calls in RESTful APIs. As it is the case in JOSN-RPC API, before requesting information data you need first to get an authentication token using your credentials. This can be done using curl or GET, described above, as follow: GET where the username=admin and password=zabbix are the default settings, the local host is used as server_ip, but if Zabbix server is set to any IP, please use that one. You get the following response: {"result":"4dcdcda6fec4cf45298d55fe60"} You use the token that you have got as result in further requests. For example if you need to get the host ID, you post the following request: GET You get the following response: {"hostlist":[{"hostid":"10093","hostname":"monitor"}]} Table 2 - Monitoring Metrics and Operations in RESTful API Metric & Operation Name getuserauthenticationtoken gethostid getcpuidletime getcpuiowaittime getcpunicetime getcpusystemtime getcpuusertime getcachedmemory getfreememory getsharedmemory gettotalmemory getbuffermemory RESTful_call rd=<password> > nticationresult>&metrictype=idle nticationresult>&metrictype=iowait nticationresult>&metrictype=nice nticationresult>&metrictype=system nticationresult>&metrictype=user thenticationresult>&metrictype=cachedmemory thenticationresult>&metrictype=freememory thenticationresult>&metrictype=sharedmemory thenticationresult>&metrictype=totalmemory thenticationresult>&metrictype=bufferedmemory

7 getfreeswapmemory thenticationresult>&metrictype=freeswap getingoingtrafficoninterface X e.g. interface eth0, getoutgoingtrafficoninterface X getnetworklatency getpacketloss getserviceavailability getgraphs henticationresult>&metrictype=eth0in e.g. interface eth0, uthenticationresult>&metrictype=eth0out uthenticationresult>&metrictype=lateny uthenticationresult>&metrictype=packetloss uthenticationresult>&metrictype=availability thenticationresult] In order to show/visualize graphs without using the Web frontend, you can browse any graph using its ID as follow: Guide for Admins This SE depends on Zabbix 1 Monitoring System that supports by default JSON-RPC and has a web frontend. In addition to the guides provided above for users and developers, admins have more capabilities than normal users. As an admin you can use the web frontend to interact with the monitoring SE. you have: Dashboard and data visualisations (graphs, screens, etc.) Powerful administration and configuration Admins can also grant users access to their data through the web frontend with different permissions o OR, use the JSON-RPC API for the same purposes and with the same capabilities Beside the GET operation provided by the interfaces above admins have the ability to create, update, delete, and check the existence of hosts, metrics, graphs, triggers, actions, and more. For more details, please see the Zabbix documentation at: ( Besides, the admin have the same capabilities through the JSON-RPC APIs. As an admin you can create, update, delete, and check the existence of hosts, metrics, graphs, triggers, actions, and more as listed in Table 3. For more details, please see the Zabbix documentation. Table 3 - Admins Operations in JSON-RPC API Operation getuserauthenticationtoken get<name> create<name> update<name> delete<name> exists<name> Comments Getting a token after providing username & password. With the token you can start using further operations Retrieving information about a host, metric, graph, trigger, or action Create a new host, metric, graph, trigger, or action Update an existing host, metric, graph, trigger, or action Delete an existing host, metric, graph, trigger, or action Check the existence of a host, metric, graph, trigger, or action 1