Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

README formatting and links correction #636

Merged
merged 7 commits into from Nov 1, 2022
Merged

README formatting and links correction #636

Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e4bf4d5
README formatting and links correction
Inoi-K Oct 26, 2022
9f1f9e3
2nd part
Inoi-K Oct 26, 2022
698e0fd
colons & dots
Inoi-K Oct 26, 2022
2da28fc
Update README.md
ldemailly Nov 1, 2022
e5f7dde
Update README.md
ldemailly Nov 1, 2022
6c5276b
Update README.md
ldemailly Nov 1, 2022
d0e7009
Apply suggestions from code review
ldemailly Nov 1, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
58 changes: 29 additions & 29 deletions README.md
View file
Open in desktop
Expand Up @@ -11,7 +11,7 @@

Fortio (Φορτίο) started as, and is, [Istio](https://istio.io/)'s load testing tool and later (2018) graduated to be its own project.

Fortio is also used by, among others, [Meshery](https://docs.meshery.io/extensibility/load-generators)
Fortio is also used by, among others, [Meshery](https://docs.meshery.io/extensibility/load-generators).

Fortio runs at a specified query per second (qps) and records an histogram of execution time
and calculates percentiles (e.g. p99 ie the response time such as 99% of the requests take less than that number (in seconds, SI unit)).
Expand All @@ -31,11 +31,11 @@ Fortio components can be used a library even for unrelated projects, for instanc
As well as the newly integrated [Dynamic Flags](dflag/) support (greatly inspired/imported initially from https://github.com/mwitkow/go-flagz but recently reimplemented using Go generics).
Even more recent is the new `jrpc` JSON Remote Procedure Calls library package ([docs](https://pkg.go.dev/fortio.org/fortio/jrpc)).

If you want to connect to fortio using https and fortio to provide real TLS certificates, or to multiplex grpc and regular http behind a single port, check out [Fortio Proxy](https://github.com/fortio/proxy#fortio-proxy)
If you want to connect to fortio using https and fortio to provide real TLS certificates, or to multiplex grpc and regular http behind a single port, check out [Fortio Proxy](https://github.com/fortio/proxy#fortio-proxy).

## Installation

We publish a multi architecture docker image (linux/amd64, linux/arm64, linux/ppc64le, linux/s390x) `fortio/fortio`
We publish a multi architecture docker image (linux/amd64, linux/arm64, linux/ppc64le, linux/s390x) `fortio/fortio`.

For instance:
```shell
Expand All @@ -49,7 +49,7 @@ You can install from source:
2. `go install fortio.org/fortio@latest`
3. you can now run `fortio` (from your gopath bin/ directory, usually `~/go/bin`)

The [releases](https://github.com/fortio/fortio/releases) page has binaries for many OS/architecture combinations (see assets).
The [releases](https://github.com/fortio/fortio/releases) page has binaries for many OS/architecture combinations (see assets):

```shell
curl -L https://github.com/fortio/fortio/releases/download/v1.38.2/fortio-linux_amd64-1.38.2.tgz \
Expand All @@ -74,9 +74,9 @@ fortio.exe server
```
(at the prompt, allow the windows firewall to let connections in)

Once `fortio server` is running, you can visit its web UI at [http://localhost:8080/fortio/](http://localhost:8080/fortio/)
Once `fortio server` is running, you can visit its web UI at [http://localhost:8080/fortio/](http://localhost:8080/fortio/).
ldemailly marked this conversation as resolved.
Show resolved Hide resolved

You can get a preview of the reporting/graphing UI at [https://demo.fortio.org/](https://demo.fortio.org/).
You can get a preview of the reporting/graphing UI at [https://demo.fortio.org](https://demo.fortio.org).
ldemailly marked this conversation as resolved.
Show resolved Hide resolved
<!--
and on [istio.io/docs/performance-and-scalability/synthetic-benchmarks/](https://istio.io/docs/performance-and-scalability/synthetic-benchmarks/)
-->
Expand Down Expand Up @@ -341,7 +341,7 @@ should be user:password
</pre>
</details>

See also the FAQ entry about [fortio flags for best results](https://github.com/fortio/fortio/wiki/FAQ#i-want-to-get-the-best-results-what-flags-should-i-pass)
See also the FAQ entry about [fortio flags for best results](https://github.com/fortio/fortio/wiki/FAQ#i-want-to-get-the-best-results-what-flags-should-i-pass).

## Server URLs and features

Expand Down Expand Up @@ -370,10 +370,10 @@ You can set a default value for all these by passing `-echo-server-default-param
* `/fortio/` A UI to
* Run/Trigger tests and graph the results.
* A UI to browse saved results and single graph or multi graph them (comparative graph of min,avg, median, p75, p99, p99.9 and max).
* Proxy/fetch other URLs
* Proxy/fetch other URLs.
* `/fortio/data/index.tsv` an tab separated value file conforming to Google cloud storage [URL list data transfer format](https://cloud.google.com/storage/transfer/create-url-list) so you can export/backup local results to the cloud.
* Download/sync peer to peer JSON results files from other Fortio servers (using their `index.tsv` URLs)
* Download/sync from an Amazon S3 or Google Cloud compatible bucket listings [XML URLs](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGET.html)
* Download/sync peer to peer JSON results files from other Fortio servers (using their `index.tsv` URLs).
* Download/sync from an Amazon S3 or Google Cloud compatible bucket listings [XML URLs](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGET.html).

* API to trigger and cancel runs from the running server (like the form ui but more directly and with `async=on` option)
* `/fortio/rest/run` starts a run; the arguments are either from the command line or from POSTed JSON; `jsonPath` can be provided to look for in a subset of the json object, for instance `jsonPath=metadata` allows to use the flagger webhook meta data for fortio run parameters (see [Remote Triggered load test section below](#remote-triggered-load-test-server-mode-rest-api)).
Expand Down Expand Up @@ -406,7 +406,7 @@ I fortio_main.go:293> All fortio X.Y.Z goM.m.p arm64 darwin servers started!

### Sample of the graphing UI

With the 2 histograms - total and errors overlayed
With the 2 histograms - total and errors overlayed:

![Graphical result](https://user-images.githubusercontent.com/3664595/165001248-33e180d5-fd6b-4389-b73e-79a21e76d5b0.png)

Expand Down Expand Up @@ -457,7 +457,7 @@ body:
```

### TCP
Start the echo-server alone and run a load (use `tcp://` prefix for the load test to be for tcp echo server)
Start the echo-server alone and run a load (use `tcp://` prefix for the load test to be for tcp echo server):
```Shell
$ fortio tcp-echo &
Fortio X.Y.Z tcp-echo TCP server listening on [::]:8078
Expand Down Expand Up @@ -486,7 +486,7 @@ All done 100000 calls (plus 0 warmup) 0.049 ms avg, 80495.0 qps
```

### UDP
Start the udp-echo server alone and run a load (use `tcp://` prefix for the load test to be for tcp echo server)
Start the udp-echo server alone and run a load (use `udp://` prefix for the load test to be for udp echo server):
ldemailly marked this conversation as resolved.
Show resolved Hide resolved
```
$ fortio udp-echo &
Fortio X.Y.Z udp-echo UDP server listening on [::]:8078
Expand Down Expand Up @@ -568,7 +568,7 @@ RTT histogram usec : count 3 avg 305.334 +/- 27.22 min 279.517 max 342.97 sum 91
* First, start Fortio server with the `-cert` and `-key` flags:

`/path/to/fortio/server.crt` and `/path/to/fortio/server.key` are paths to the TLS certificate and key that
you must provide.
you must provide:

```Shell
$ fortio server -cert /path/to/fortio/server.crt -key /path/to/fortio/server.key
Expand Down Expand Up @@ -655,10 +655,10 @@ All done 40 calls (plus 4 warmup) 60.588 ms avg, 7.9 qps
### Remote triggered load test (server mode rest API)

New since 1.18 the server has a `fortio/rest/run` endpoint similar to what the form UI submit in `fortio/` to start a run.
- plus `async` query arg or json value `"on"` will make the run asynchronous (returns just the runid of the run instead of waiting for the result)
- plus read all the run configuration from either query args or jsonPath POSTed info
- compatible with [flagger](https://github.com/fluxcd/flagger) and other webhooks
- New in 1.22: use `headers` json array to send headers (or multiple `&H=` query args)
- plus `async` query arg or json value `"on"` will make the run asynchronous (returns just the runid of the run instead of waiting for the result);
- plus read all the run configuration from either query args or jsonPath POSTed info;
- compatible with [flagger](https://github.com/fluxcd/flagger) and other webhooks;
- New in 1.22: use `headers` json array to send headers (or multiple `&H=` query args).

Examples:

Expand Down Expand Up @@ -710,7 +710,7 @@ X-On-Behalf-Of: [::1]:62629
foo
```

and you get in result.json
and you get in result.json:
```json
{
"RunType": "HTTP",
Expand Down Expand Up @@ -828,7 +828,7 @@ and you get in result.json
}
```

- There is also the `fortio/rest/stop` endpoint to stop a run by its id or all runs if not specified
- There is also the `fortio/rest/stop` endpoint to stop a run by its id or all runs if not specified.


### GRPC load test
Expand Down Expand Up @@ -977,7 +977,7 @@ $ fortio server -M "5554 http://localhost:8080 http://localhost:8080"
Fortio X.Y.Z Multi on 5554 server listening on [::]:5554
10:09:56 I http_forwarder.go:152> Multi-server on [::]:5554 running with &{Targets:[{Destination:http://localhost:8080 MirrorOrigin:true} {Destination:http://localhost:8080 MirrorOrigin:true}] Name:Multi on [::]:5554 client:0xc0001ccc00}
```
Call the debug endpoint on both
Call the debug endpoint on both:
```Shell
# in new window
$ fortio curl -payload "a test" http://localhost:5554/debug
Expand Down Expand Up @@ -1022,7 +1022,7 @@ a test
There are 2 flags to further control the behaviour of the multi server proxies:

- pass `-mirrorOriginFlag=false` to not mirror all headers and request type to targets.
- pass `-multi-serial-mode` to stream request response serially instead of fetching in parallel and writing combined data after completion
- pass `-multi-serial-mode` to stream request response serially instead of fetching in parallel and writing combined data after completion.

Also remember you can pass multiple `-M`.

Expand All @@ -1045,14 +1045,14 @@ Fortio X.Y.Z proxy for [::1]:8080 server listening on [::1]:8889

## Implementation details

Fortio is written in the [Go](https://golang.org) language and includes a scalable semi log histogram in [stats.go](stats/stats.go) and a periodic runner engine in [periodic.go](periodic/periodic.go) with specializations for [http](http/httprunner.go) and [grpc](fortiogrpc/grpcrunner.go).
The [http/](http/) package includes a very high performance specialized http 1.1 client.
Fortio is written in the [Go](https://golang.org) language and includes a scalable semi log histogram in [stats.go](stats/stats.go) and a periodic runner engine in [periodic.go](periodic/periodic.go) with specializations for [http](fhttp/httprunner.go) and [grpc](fgrpc/grpcrunner.go).
The [fhttp/](fhttp/) package includes a very high performance specialized http 1.1 client.
ldemailly marked this conversation as resolved.
Show resolved Hide resolved
You may find fortio's [logger](log/logger.go) useful as well.

You can run the histogram code standalone as a command line in [histogram/](histogram/), a basic echo http server in [echosrv/](echosrv/), or both the http echo and GRPC ping server through `fortio server`, the fortio command line interface lives in this top level directory [fortio_main.go](fortio_main.go)

There is also [fcurl/](fcurl/) which is the `fortio curl` part of the code (if you need a light http client without grpc or server side).
A matching tiny (2Mb compressed) docker image is [fortio/fortio.fcurl](https://hub.docker.com/r/fortio/fortio.fcurl/tags/)
A matching tiny (2Mb compressed) docker image is [fortio/fortio.fcurl](https://hub.docker.com/r/fortio/fortio.fcurl/tags/).

## More examples

Expand Down Expand Up @@ -1117,15 +1117,15 @@ Code 200 : 300000
Response Body Sizes : count 300000 avg 0 +/- 0 min 0 max 0 sum 0
</pre></details>

Or you can get the data in [JSON format](https://github.com/fortio/fortio/wiki/Sample-JSON-output) (using `-json result.json`)
Or you can get the data in [JSON format](https://github.com/fortio/fortio/wiki/Sample-JSON-output) (using `-json result.json`).

### Web/Graphical UI

Or graphically (through the [http://localhost:8080/fortio/](http://localhost:8080/fortio/) web UI):

Simple form/UI:

Sample requests with responses delayed by 250us and 0.5% of 503 and 1.5% of 429 simulated http errors.
Sample requests with responses delayed by 250us and 0.5% of 503 and 1.5% of 429 simulated http errors:

![Web UI form screenshot](https://user-images.githubusercontent.com/3664595/41430618-53d911d4-6fc5-11e8-8e35-d4f5fea4426a.png)

Expand All @@ -1139,7 +1139,7 @@ Code 429 : 56 (1.9 %)
Code 503 : 15 (0.5 %)
```

There are live examples on [demo.fortio.org](https://demo.fortio.org/)
There are live examples on [demo.fortio.org](https://demo.fortio.org/).
ldemailly marked this conversation as resolved.
Show resolved Hide resolved

## Contributing

Expand Down Expand Up @@ -1169,7 +1169,7 @@ New features and bug fixes should include a test.

## See also

Our wiki and the [Fortio FAQ](https://github.com/fortio/fortio/wiki/FAQ) (including for instance differences between `fortio` and `wrk` or `httpbin`)
Our wiki and the [Fortio FAQ](https://github.com/fortio/fortio/wiki/FAQ) (including for instance differences between `fortio` and `wrk` or `httpbin`).

## Disclaimer

Expand Down