This is an HTTP server that controls Yandex.Tank execution. It allows the client to:
by running yandex-tank-api-server [options...] in console
General information on Yandex.Tank installation and usage can be found in its documentation. This section covers the difference between console Tank and API-managed Tank configuration and provides more details on the sequence of the test stages.
API-managed Tank is configured via configuration files only. They have the same syntax and options as the console Tank configs.
The configuration parameters are applied in the following order:
/etc/yandex-tank//etc/yandex-tank-api/defaults/etc/yandex-tank-api/overrideWhen the client launches a new test, a new session is created and a separate Tank worker process is spawned. After this, the test stages are executed in the following order:
lock
Attempt to acquire the tank lock. This stage fails if another test started via console is running.
init
Logging is set up and tank configuration files are read at this stage.
configure
The configure() method is called for each module. Most of the dynamic configuration is done here.
prepare
The prepare_test() method is called for each module. Heavy and time-consuming tasks (such as stpd-file generation and monitoring agent setup) are done here.
start
The start_test() method is called for each module. This should take as little time as possible. Load generation begins at this moment.
poll
Once per second the is_test_finished() method is called for each module. This stage ends when any of the modules requests to stop the test.
end
The end_test() method is called for each module. This should take as little time as possible.
postprocess
The post_process() method is called for each module. Heavy and time-consuming tasks are performed here.
unlock
The tank lock is released and the Tank worker exits.
finished
This is a virtual stage. Reaching this stage means that the Tank worker has already terminated.
The last session status is temporarily stored after tank exit. The test artifacts are stored forever and should be deleted by external means when not needed.
When the session is started, the client can specify the test stage before which the test will be paused (the breakpoint) . After completing the stages preceding the breakpoint, the Tank will wait until the breakpoint is moved further. You cannot move the breakpoint back.
The breakpoint can be set before any stage. One of the most frequent use cases is to set the breakpoint before the start stage to synchronize several tanks. Another is setting the breakpoint before the unlock stage to download the artifacts without interference to other tests. Third is setting the breakpoint before the init stage to upload additional files. Beware that setting the breakpoint between the init and the poll stages can lead to very exotic behaviour.
All API requests are asynchronous: we do not wait the tank process to perform requested action. HTTP code 200 is returned when no error occured while processing the request. However, this does not necessarily mean that the requested action will be successfully performed. The client should check the session status to detect Tank failures.
All handles, except for /artifact, return JSON. On errors this is a JSON object with a key 'reason'.
POST /validate
Request body: Yandex.Tank config in .yaml format (the same as for console Tank)
Checks if config provided is valid within local defaults
Reply on success:
{
"config": "<yaml string>", // your config
"errors": [] // empty if valid
}Error codes and corresponding reasons in the reply:
POST /run?[test=...]&[break=...]
Request body: Yandex.Tank config in .yaml format (the same as for console Tank)
Creates a new session with an unique session ID and launches a new Tank worker.
Parameters:
Reply on success:
{
"session": "20150625210015_0000000001", //ID of the launched session
"test": "20150625210015_0000000001" //Deprecated, do not use
}Error codes and corresponding reasons in the reply:
GET /run?session=...&[break=...]
Sets a new break point for the running session.
Parameters:
Return codes and corresponding reasons:
GET /stop?session=...
Terminates the current test.
Parameters:
Return codes and corresponding reasons:
GET /status?session=...
Returns the status of the specified session. Parameters:
Status examples:
{
"status": "running",
"stage_completed": true,
"break": "start",
"current_stage": "prepare",
"test": "9f43f3104c2549b98bf74b817dc71cef",
"failures": []
}{
"status": "failed",
"retcode": 1,
"stage_completed": true,
"break": "finished",
"current_stage": "finished",
"test": "9f43f3104c2549b98bf74b817dc71cef",
"failures": [
{
"reason": "Interrupted",
"stage": "prepare"
}
]
}Error code and the corresponding reason:
GET /status?
Returns a JSON object where keys are known session IDs and values are the corresponding statuses.
GET /artifact?session=...
Returns a JSON array of artifact filenames.
Parameters:
Error codes and the corresponding reasons:
GET /artifact?session=...&filename=...
Sends the specified artifact file to the client.
Parameters:
Error codes and the corresponding reasons:
POST /upload?session=...&filename=...
Stores the request body on the server in the tank working directory for the session under the specified filename. The session should be running.
Parameters:
Error codes and the corresponding reasons:
Some custom plugins might need to know if they are wokring in the console Tank or under API.
API worker process uses a subclass of a standard TankCore as a tank core. Thus, a plugin can detect execution under API by simply checking that
str(self.core.__class__)=='yandex_tank_api.worker.TankCore'