server

This repository holds the code for the main Benchttp server which offers a RESTful API.

It is deployed independently from the other parts making our system.

API

Push report of a run

POST /v1/reports

Parameters

Name	Type	In	Description
report	bytes (gob encoding)	body	The raw report data generated by the runner

Response

Status: 201 Created

Get the report of a particular run

GET /v1/reports/{id}

Parameters

Name	Type	In	Description
id	string	path	The requested report ID

Response

Status: 200 OK

JSON response

{
  "benchmark": {
    "records": [
      {
        "time": 152970821,
        "code": 200,
        "bytes": 46,
        "error": "",
        "events": [
          {
            "name": "GotFirstResponseByte",
            "time": 2457696
          }
          // ...
        ]
      }
      // ...
    ],
    "length": 10,
    "success": 10,
    "fail": 0,
    "duration": 324953628
  },
  "metadata": {
    "config": {
      "request": {
        "method": "GET",
        "url": {
          "scheme": "http",
          "opaque": "",
          "user": null,
          "host": "echo.jsontest.com",
          "path": "/title/ipsum/content/blah",
          "rawPath": "",
          "forceQuery": false,
          "rawQuery": "",
          "fragment": "",
          "rawFragment": ""
        },
        "header": {},
        "body": {
          "type": "",
          "content": ""
        }
      },
      "runner": {
        "requests": 10,
        "concurrency": 10,
        "interval": 50000000,
        "requestTimeout": 2000000000,
        "globalTimeout": 30000000000
      }
    },
    "finishedAt": "2022-02-27T19:54:19.019717Z"
  }
}

List all the available statistics of previously reported run

GET /v1/stats

Parameters

None. The list is always limited to the user's runs.

Response

Status: 200 OK

JSON response

[
  {
    "id": "lwkaFmtuCoeKSFhbndTC",
    "finishedAt": "2022-02-27T19:54:19.019717Z"
  },
  {
    "id": "XbqWESZWGC9iaXSWPDmu",
    "finishedAt": "2022-03-03T18:00:19.019717Z"
  }
]

Get the statistics of a particular run

GET /v1/stats/{id}

Parameters

Name	Type	In	Description
id	string	path	The ID of the report whose stats are requested

Response

Status: 200 OK

JSON response

{
  "descriptor": {
    "id": "lwkaFmtuCoeKSFhbndTC",
    "finishedAt": "2022-02-27T19:54:19.019717Z"
  },
  "time": {
    "min": 152005288,
    "max": 383330299,
    "mean": 266585242,
    "median": 266713182,
    "standardDeviation": 51772085,
    "deciles": [
      152005288, 262461226, 263282513, 265239215, 265682968, 267743397,
      268441975, 268631834, 269033707
    ]
  },
  "code": {
    "code1xx": 0,
    "code2xx": 1000,
    "code3xx": 0,
    "code4xx": 0,
    "code5xx": 0
  }
}

Deployment

The infrastructure code defining the deployment of server is located inside benchttp/infra.

Development

Lint

Run the linter:

We use golangci-lint in our CI.

make lint
# alias to:
# golangci-lint run

Test

Run all tests:

make tests
# alias to:
# go test -v -timeout 30s ./...

Run a specific test passing t to specify a test and p to specify a package (parameters are independent):

make test t=TestThing p=internal/thing
# alias to:
# go test -v -timeout 30s -run TestThing ./internal/thing