README.md
1# httpstat
2
3
4
5httpstat visualizes `curl(1)` statistics in a way of beauty and clarity.
6
7It is a **single file��** Python script that has **no dependency��** and is compatible with **Python 3��**.
8
9
10## Installation
11
12There are three ways to get `httpstat`:
13
14- Download the script directly: `wget https://raw.githubusercontent.com/reorx/httpstat/master/httpstat.py`
15
16- Through pip: `pip install httpstat`
17
18- Through homebrew (macOS only): `brew install httpstat`
19
20> For Windows users, @davecheney's [Go version](https://github.com/davecheney/httpstat) is suggested. → [download link](https://github.com/davecheney/httpstat/releases)
21
22## Usage
23
24Simply:
25
26```bash
27python httpstat.py httpbin.org/get
28```
29
30If installed through pip or brew, you can use `httpstat` as a command:
31
32```bash
33httpstat httpbin.org/get
34```
35
36### cURL Options
37
38Because `httpstat` is a wrapper of cURL, you can pass any cURL supported option after the url (except for `-w`, `-D`, `-o`, `-s`, `-S` which are already used by `httpstat`):
39
40```bash
41httpstat httpbin.org/post -X POST --data-urlencode "a=b" -v
42```
43
44### Environment Variables
45
46`httpstat` has a bunch of environment variables to control its behavior.
47Here are some usage demos, you can also run `httpstat --help` to see full explanation.
48
49- <strong><code>HTTPSTAT_SHOW_BODY</code></strong>
50
51 Set to `true` to show response body in the output, note that body length
52 is limited to 1023 bytes, will be truncated if exceeds. Default is `false`.
53
54- <strong><code>HTTPSTAT_SHOW_IP</code></strong>
55
56 By default httpstat shows remote and local IP/port address.
57 Set to `false` to disable this feature. Default is `true`.
58
59- <strong><code>HTTPSTAT_SHOW_SPEED</code></strong>
60
61 Set to `true` to show download and upload speed. Default is `false`.
62
63 ```bash
64 HTTPSTAT_SHOW_SPEED=true httpstat http://cachefly.cachefly.net/10mb.test
65
66 ...
67 speed_download: 3193.3 KiB/s, speed_upload: 0.0 KiB/s
68 ```
69
70- <strong><code>HTTPSTAT_SAVE_BODY</code></strong>
71
72 By default httpstat stores body in a tmp file,
73 set to `false` to disable this feature. Default is `true`
74
75- <strong><code>HTTPSTAT_CURL_BIN</code></strong>
76
77 Indicate the cURL bin path to use. Default is `curl` from current shell $PATH.
78
79 This exampe uses brew installed cURL to make HTTP2 request:
80
81 ```bash
82 HTTPSTAT_CURL_BIN=/usr/local/Cellar/curl/7.50.3/bin/curl httpstat https://http2.akamai.com/ --http2
83
84 HTTP/2 200
85 ...
86 ```
87
88 > cURL must be compiled with nghttp2 to enable http2 feature
89 > ([#12](https://github.com/reorx/httpstat/issues/12)).
90
91- <strong><code>HTTPSTAT_METRICS_ONLY</code></strong>
92
93 If set to `true`, httpstat will only output metrics in json format,
94 this is useful if you want to parse the data instead of reading it.
95
96- <strong><code>HTTPSTAT_DEBUG</code></strong>
97
98 Set to `true` to see debugging logs. Default is `false`
99
100
101For convenience, you can export these environments in your `.zshrc` or `.bashrc`,
102example:
103
104```bash
105export HTTPSTAT_SHOW_IP=false
106export HTTPSTAT_SHOW_SPEED=true
107export HTTPSTAT_SAVE_BODY=false
108```
109
110## Related Projects
111
112Here are some implementations in various languages:
113
114
115- Go: [davecheney/httpstat](https://github.com/davecheney/httpstat)
116
117 This is the Go alternative of httpstat, it's written in pure Go and relies no external programs. Choose it if you like solid binary executions (actually I do).
118
119- Go (library): [tcnksm/go-httpstat](https://github.com/tcnksm/go-httpstat)
120
121 Other than being a cli tool, this project is used as library to help debugging latency of HTTP requests in Go code, very thoughtful and useful, see more in this [article](https://medium.com/@deeeet/trancing-http-request-latency-in-golang-65b2463f548c#.mm1u8kfnu)
122
123- Bash: [b4b4r07/httpstat](https://github.com/b4b4r07/httpstat)
124
125 This is what exactly I want to do at the very beginning, but gave up due to not confident in my bash skill, good job!
126
127- Node: [yosuke-furukawa/httpstat](https://github.com/yosuke-furukawa/httpstat)
128
129 [b4b4r07](https://twitter.com/b4b4r07) mentioned this in his [article](https://tellme.tokyo/post/2016/09/25/213810), could be used as a HTTP client also.
130
131- PHP: [talhasch/php-httpstat](https://github.com/talhasch/php-httpstat)
132
133 The PHP implementation by @talhasch
134
135Some code blocks in `httpstat` are copied from other projects of mine, have a look:
136
137- [reorx/python-terminal-color](https://github.com/reorx/python-terminal-color) Drop-in single file library for printing terminal color.
138
139- [reorx/getenv](https://github.com/reorx/getenv) Environment variable definition with type.
140
