{{ :blocks:logo-apl.png?nolink |}} ===== Moodle Load Monitor: web service ===== This page describes the web service exposed by ''tool_moodleload'': the functions, their parameters and their responses. It is aimed at integrators and at the MoodleLoad engine. ==== The service ==== ^ Property ^ Value ^ | Name | Moodle Load Monitor | | Short name | ''moodleload_monitor'' | | Protocol | REST | | Users | Restricted: only authorised users (the ''moodleload'' account created at installation) | | File upload | Allowed (''webservice/upload.php'') | | File download | Disabled | General call: POST /webservice/rest/server.php wstoken= wsfunction= moodlewsrestformat=json The token is that of the ''moodleload'' account (see [[:tool:moodleload:install|Installation and configuration]]). Never put it in a shared URL or in a document. ^ Function ^ Role ^ Type ^ Required capability ^ | ''tool_moodleload_get_metrics'' | Host metrics | Read | ''tool/moodleload:readmetrics'' | | ''tool_moodleload_authorize_load'' | Test authorisation handshake | Read | ''tool/moodleload:readmetrics'' | | ''app_moodleload_commit'' | Validate an uploaded test material file | Write | ''tool/moodleload:setuptests'' | | ''app_moodleload_restore_course'' | Restore a test course | Write | ''tool/moodleload:setuptests'' | | ''app_moodleload_bulk_create_install_users'' | Create or update test users | Write | ''tool/moodleload:setuptests'' | ==== tool_moodleload_get_metrics ==== Returns a snapshot of the resources of the server running Moodle. **Parameter** ^ Name ^ Type ^ Default ^ Description ^ | ''include_loopback'' | boolean | false | Includes the loopback interface (''lo'') in the network statistics. | **Response** ^ Field ^ Type ^ Description ^ | ''timestamp'' | integer | Unix timestamp of the snapshot. | | ''cpu_percent'' | decimal | CPU usage from 0 to 100. ''-1'' on the first call (the calculation needs two snapshots) or if ''/proc/stat'' is not available. | | ''memory.total'', ''memory.available'', ''memory.used'' | integer | Memory in bytes. ''-1'' if unavailable. | | ''memory.used_percent'' | decimal | Percentage of memory used. | | ''load_avg.avg1'', ''avg5'', ''avg15'' | decimal | Load average over 1, 5 and 15 minutes. ''-1'' if unavailable. | | ''processes.total'', ''running'', ''blocked'' | integer | Number of processes, runnable, blocked on I/O. ''-1'' if unavailable. | | ''network'' | list | One entry per network interface: ''interface'', ''rx_bytes'', ''rx_packets'', ''rx_errors'', ''rx_dropped'', ''tx_bytes'', ''tx_packets'', ''tx_errors'', ''tx_dropped'' (totals since startup) and ''delta_rx_bytes'', ''delta_tx_bytes'', ''delta_seconds'', ''rx_bps'', ''tx_bps'' (differences since the previous call, ''-1'' on the first call). Empty list if ''/proc/net/dev'' is unreadable. | | ''error'' | text | Not empty if a measurement could not be collected. | | ''hostname'' | text | Name of the host that produced the snapshot (useful on a server cluster). | Example of an abridged response: { "timestamp": 1727600000, "cpu_percent": 14.73, "memory": {"total": 16777216000, "available": 9663676416, "used": 7113539584, "used_percent": 42.40}, "load_avg": {"avg1": 0.85, "avg5": 1.02, "avg15": 0.97}, "processes": {"total": 312, "running": 2, "blocked": 0}, "network": [], "error": "", "hostname": "web01" } The CPU measurement is a difference between two snapshots kept in Moodle's universal cache (adjustable lifetime). Call the function twice at least 5 seconds apart to get a meaningful value. The function is also called by the tool's dashboard with the administrator's Moodle session (no token is written in the page). ==== tool_moodleload_authorize_load ==== Handshake that MoodleLoad performs before launching a load test on the site. The engine refuses to fire on a site that does not answer it. **Parameters** ^ Name ^ Type ^ Description ^ | ''nonce'' | alphanumeric | Random challenge generated by MoodleLoad, 16 to 64 characters. | | ''wwwroot'' | text | The root address of the site MoodleLoad is about to load. | **Response** ^ Field ^ Type ^ Description ^ | ''protocol'' | integer | Handshake protocol version (1). | | ''nonce'' | text | The challenge received, returned as is. | | ''wwwroot'' | text | The actual root address of this Moodle. | | ''timestamp'' | integer | Server time. | | ''allowload'' | integer | 1 if the administrator allows load tests. | | ''maxload'' | integer | Maximum number of simultaneous user sessions. 0: no limit. | | ''allowedhours'' | text | Allowed time ranges (server time). Empty: any hour. | | ''inallowedhours'' | integer | 1 if the current server time is within the allowed ranges. | | ''pluginversion'' | text | Plugin version. | | ''siteidentifier'' | text | Moodle site identifier. | | ''message'' | text | Message to the operator (test not allowed, outside time range). | | ''signature'' | text | HMAC-SHA256 signature of the signed fields, computed with the call's token. | The signature covers the following string, the fields being separated by ''|'' in this order: protocol, nonce, wwwroot, timestamp, allowload, maxload, allowedhours, inallowedhours. The engine recomputes it with the token it knows and compares: an unsigned response, or one from another site, is rejected. The test is refused if ''allowload'' is 0 or if ''inallowedhours'' is 0. ==== Preparing the test material ==== These three functions require the ''tool/moodleload:setuptests'' capability in the system context. The normal sequence is: - Upload the file (course backup or users CSV) to ''/webservice/upload.php'' with the token: the upload returns a draft area identifier (''itemid''). - Call ''app_moodleload_commit'' to validate the file. - Call ''app_moodleload_restore_course'' or ''app_moodleload_bulk_create_install_users'' with the identifier of the validated file. === app_moodleload_commit === Validates the single file of a draft area as the test material for a given purpose. A new file replaces the previous one for the same purpose. ^ Parameter ^ Type ^ Description ^ | ''draftitemid'' | integer | Identifier of the draft area of the uploaded file. The area must contain exactly one file. | | ''purpose'' | alphabetic | ''testcourse'' (course backup) or ''testusers'' (users CSV). | ^ Response ^ Description ^ | ''storedfileid'' | Identifier of the validated file, to pass to the following functions. | | ''purpose'' | The purpose of the file. | | ''filename'' | File name. | | ''filesize'' | Size in bytes. | === app_moodleload_restore_course === Restores a validated course backup. A course with the same short name is deleted before the restore, so that the test material is refreshed. ^ Parameter ^ Type ^ Description ^ | ''storedfileid'' | integer | Identifier of the file validated with the ''testcourse'' purpose. | | ''categoryid'' | integer, optional | Destination category. 0 or absent: the //Load Tests// category. | The caller must be able to create courses and restore into the targeted category. Response: ''courseid'', ''shortname'' and ''categoryid'' of the restored course. An unreadable backup causes an error. === app_moodleload_bulk_create_install_users === Creates or updates the users of a CSV file validated with the ''testusers'' purpose, then enrols them in the indicated courses. Accounts are identified by their login. ^ Parameter ^ Type ^ Description ^ | ''storedfileid'' | integer | Identifier of the file validated with the ''testusers'' purpose. | **File format**: the first line is the header. The separator is ''%%;%%'' or '','' (whichever appears most in the header). ^ Column ^ Mandatory ^ Description ^ | ''username'', ''firstname'', ''lastname'', ''email'' | yes | Account identity. | | ''password'', ''city'', ''country'' | no | Password, city, country. | | ''enrol1'' to ''enrol4'' | no | Enrolment method (installed and enabled on the site). | | ''enrolcourse1'' to ''enrolcourse4'' | no | Course short name. | | ''role1'' to ''role4'' | with ''enrol'' | Role short name. | | ''groupname1'' to ''groupname4'' | no | Course group, created if it does not exist. | When the course has no enabled instance of the requested method, a default instance is added. A user or enrolment in error is reported with its line and does not stop the other lines. ^ Response ^ Description ^ | ''created'' | Number of accounts created. | | ''updated'' | Number of accounts updated. | | ''enrolled'' | Number of enrolments made. | | ''errors'' | List of errors: ''line'' (file line number) and ''message''. | ==== Security ==== * The service is reserved for authorised users. The ''moodleload'' account holds the Manager role: the token must be protected like an administration credential. * Deleting a course with the same short name during a restore is intentional: do not use the short name of a real course for the test material. * The write functions have no place on a production site. ==== Frequent errors ==== ^ Message or symptom ^ Cause ^ | ''invalidtoken'' or access denied | Token expired (3 months), web services or REST not enabled, user not authorised on the service. | | Missing capability | The account does not have ''tool/moodleload:readmetrics'' or ''tool/moodleload:setuptests'' (Manager role). | | Single file required | The draft area passed to ''app_moodleload_commit'' does not contain exactly one file. | | Invalid purpose | ''purpose'' other than ''testcourse'' and ''testusers''. | | Nonce error | Challenge length outside 16 to 64 characters. | ---------- [[:tool:moodleload|Back to the component index]] - [[:Plugins|Back to plugins index]] - [[:start|Back to catalogue]]