locust

README

go-locust

Description

go-locust is a library to control a locust load generation and get statistics written in golang. This is client allows to start,stop a locust load test and ramp up load. This uses locust endpoints to cummunicate with locust.

Currently, go-locust requires Go version 1.13 or greater and Locust 0.14 or higher. I will try my best to test with older versions of Go and Locust, but due time constraints, I haven't tested with older versions.

This does not process client stats and presents information as it is.

Usage

check example folder

package main

import (
	"log"
	lc "github.com/amila-ku/go-locust"
)

const (
	 hostURL = "http://localhost:8089"
	 users   = 5
	 hatchRate = 1
)

func main(){
	client, err := lc.New(hostURL)
	if err != nil {
		log.Fatal(err)
	}
	_, err = client.GenerateLoad(users, hatchRate)
	if err != nil {
		log.Fatal(err)
	}

}

• hostUrl : locust endpoiint to connect to, ex : http://locust.loadenv.io:8089

• users : Number of users to simulate

• hatchRate : How many users to be added per second

complete example:

package main 

import (
    lc "github.com/amila-ku/go-locust"
)

const (
	 hostURL = "http://localhost:8089"
	 users   = 5
	 hatchRate = 1
)

func main(){
	client, err := lc.New(hostURL)
	if err != nil {
		log.Fatal(err)
	}

	// start load generation
	_, err = client.GenerateLoad(users, hatchRate)
	if err != nil {
		log.Fatal(err)
	}

    	// stop load generation
	_, err = client.stopLoad()
	if err != nil {
		log.Fatal(err)
	}

    	// get loadtest status
	_, err = client.getStatus()
	if err != nil {
		log.Fatal(err)
	}
}

Authentication

Library go-locust will not directly handle authentication since locust does not require authentication. If you have implemented authetication mechanism handle it accordingly. As an example if Oauth2 is used when creating http client configure http.Client to handle authentication for you. Check https://github.com/golang/oauth2 for implementation

Run Locust

install locust

pip3 install locust

and configure loadtest file as described here https://docs.locust.io/en/stable/quickstart.html

locust -f locust_files/my_locust_file.py

Contributing

If you are using the client and willing to add new functionality to it, you are welcome.

Also check out locust-operator which makes running locust in a distributed setup makes easy.

License

Open source licensed under the MIT license (see LICENSE file for details).

Documentation

Overview

Package locust implements a locust client using native Go data structures Locust API https://docs.locust.io/en/stable/api.html# Locust endpoints https://github.com/locustio/locust/blob/master/locust/web.py

Index

• type Client
  • func New(endpoint string) (*Client, error)
  • func (c *Client) GenerateLoad(users int, hatchrate float64) (*SwarmResponse, error)
  • func (c *Client) Stats() (*StatsResponse, error)
  • func (c *Client) StopLoad() (*SwarmResponse, error)
  • func (c *Client) Swarm(rps float64, duration string) (*SwarmResponse, error)
• type Error
• type Stat
• type StatsResponse
• type SwarmResponse

Types

type Client

type Client struct {
	BaseURL *url.URL
	// contains filtered or unexported fields
}

Client defines a structure for a locust client. Client contains URL of the locust endpoint and a httpclient

func New

func New(endpoint string) (*Client, error)

New initiantes a new client to control locust, url of the locust endpoint is required as a paramenter

func (*Client) GenerateLoad

func (c *Client) GenerateLoad(users int, hatchrate float64) (*SwarmResponse, error)

GenerateLoad starts locust swarming or modifes if the load generation has already started, hatch rate and number of users to simulate are inputs.

func (*Client) Stats

func (c *Client) Stats() (*StatsResponse, error)

Stats gets the execution metrics from locust this provides error ratio, current users hatchd, state and many other defined in StatsResponse structure

func (*Client) StopLoad

func (c *Client) StopLoad() (*SwarmResponse, error)

StopLoad stops an existing locust execution

func (*Client) Swarm

func (c *Client) Swarm(rps float64, duration string) (*SwarmResponse, error)

Swarm handles load test when given maximum requests rate and ramp up time.

type Error

type Error struct {
	Error       string `json:"error"`
	Method      string `json:"method"`
	Name        string `json:"name"`
	Occurrences int    `json:"occurrences"`
}

Error defines structure of error records in locust stats from locust stats endpoint, this is part of StatsResponse

type Stat

type Stat struct {
	AvgContentLength   float64 `json:"avg_content_length"`
	AvgResponseTime    float64 `json:"avg_response_time"`
	CurrentRps         float64 `json:"current_rps"`
	MaxResponseTime    float64 `json:"max_response_time"`
	MedianResponseTime float64 `json:"median_response_time"`
	Method             string  `json:"method"`
	MinResponseTime    float64 `json:"min_response_time"`
	Name               string  `json:"name"`
	NumFailures        int     `json:"num_failures"`
	NumRequests        int     `json:"num_requests"`
}

Stat defines locust stats structure from locust stats endpoint, this is part of StatsResponse

type StatsResponse

type StatsResponse struct {
	CurrentResponseTimePercentile50 float64 `json:"current_response_time_percentile_50"`
	CurrentResponseTimePercentile95 float64 `json:"current_response_time_percentile_95"`
	Errors                          []Error `json:"errors"`
	FailRatio                       float64 `json:"fail_ratio"`
	State                           string  `json:"state"`
	Statistics                      []Stat  `json:"stats"`
	TotalRps                        float64 `json:"total_rps"`
	UserCount                       int     `json:"user_count"`
}

StatsResponse defines the structure for the response from locust stats endpoint.

type SwarmResponse

type SwarmResponse struct {
	Message string `json:"message"`
	Success bool   `json:"success"`
}

SwarmResponse defines the structure of a response for locust swarm endpoint Locust returns a json with status of the action and a message. start and stop locust swarming both returns a message with same structure.