Mercurial > hg > speedtest

comparison README.md @ 0:26e919a36f86 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
speedtest containerized dispatching software
author Jeff Hammel <k0scist@gmail.com>
date Thu, 09 Feb 2017 09:47:04 -0800
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:26e919a36f86
1 # Speedtest
2
3 ## The Pattern
4
5 `speedtest`
6 will use this pattern for outer loop testing:
7
8 - a [Docker](http://docker.io/) container is created from a
9 `speedtest` script,
10 and a docker
11 [CMD]
12 (https://docs.docker.com/v1.8/reference/builder/#cmd)
13 that will run
14 the appropriate test and post a JSON blob to an
15 [Elasticsearch](https://www.elastic.co/) node
16
17 - the Docker container is dispatched to a container service
18 such that it may be run at
19 cloud scale and from a variety of regions
20
21 - the test [CMD]
22 (http://docs.docker.com/engine/reference/builder/#cmd)
23 of the container contains steps that will generate
24 JSON data and post this to an Elasticsearch node. This
25 Elasticsearch data may then be analyzed and utilized for reporting
26 of system status.
27
28 This pattern is of general utility for blackbox testing and monitoring
29 of a web system under test. Monitoring may be performed in a continuous
30 and ongoing basis, the Elasticsearch data combed for performance information.
31
32
33 ## Installation
34
35 `speedtest` follows fairly standard
36 [python packaging]
37 (https://python-packaging-user-guide.readthedocs.org/en/latest/)
38 practices. We do need other software, like
39 [docker](http://docker.io), to help us along.
40
41 Let's get started!
42
43
44 ## What Speedtest Gives You
45
46 `speedtest` attempts to provide a suite of tools for making worldwide
47 dockerized speedtests a reality. Many of these are provide in terms
48 of [setuptools](https://pythonhosted.org/setuptools/)
49 [entry points]
50 (https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins),
51 including
52 [console scripts]
53 (https://pythonhosted.org/setuptools/setuptools.html#automatic-script-creation).
54
55 Several console scripts are also installed with `speedtest`.
56 All provided console scripts utilize
57 [argparse](https://docs.python.org/2/library/argparse.html)
58 for their command line interface. Detailed usage information for a
59 script may be obtained by using the `--help` command line switch.
60 For example: `speedtest --help` .
61
62
63 ## About Speedtest
64
65 `speedtest` is a collection of scripts and utilities to make real the
66 pattern of docker container dispatch for data
67 gathering via JSON output to Elasticsearch.
68
69 While `Dockerfile`s are a good abstraction layer for building
70 [linux containers]
71 (https://en.wikipedia.org/wiki/LXC),
72 often the run steps must be automated and parameterized.
73
74 ## speedtest with local results
75
76 Usage information is available with the `--help` flag:
77
78 speedtest --help
79
80 Arbitrary metadata may be added with the `--variables` flag. While the results processing and information available should be refined, right now we are erring on the side of too much, which is at least fairly flexible.
81
82 To run a speedtest versus the URL http://k0s.org/playground/1M.bin adding the variable `foo` with value of `bar` with local JSON results measuring every 100k, do:
83
84 speedtest --variables foo=bar --format json --chunk $((100*1024)) http://k0s.org/playground/1M.bin
85
86
87 ## Containers
88
89 ### Containerized Download Speed Testing
90
91 `speedtest.py`
92
93 (and, equivalently, the `speedtest` [console script]
94 (http://python-packaging.readthedocs.org/en/latest/command-line-scripts.html#the-console-scripts-entry-point))
95 measures download speed over time given a URL:
96
97 # speedtest http://k0s.org/playground/1M.bin
98 ...
99 {"duration": 1.7867929935455322, "cumulative": 586848, "speed": 209367, "size": 1048576}
100
101
102 ### Containerized Dispatching
103
104 - pull the Docker image from a container registry
105 - run the Docker image
106
107 ### Container Registry
108
109 In order to make use of containerized dispatch, you may want a
110 [docker registry](https://docs.docker.com/registry/):
111
112 - https://docs.docker.com/registry/deploying/
113 - https://www.docker.com/docker-trusted-registry
114 - https://github.com/docker/distribution
115 - https://www.docker.com/aws
116
117 [Docker hub](https://hub.docker.com/)
118 has an official [Docker](https://www.docker.com)
119 repository for a
120 [Docker registry]
121 (https://hub.docker.com/_/registry/). How meta is that? You can get
122 started just by running:
123
124 docker run registry:2
125
126
127 ## Elasticsearch
128
129 _"Elasticsearch is a search server based on Lucene. It provides a
130 distributed, multitenant-capable full-text search engine with a HTTP
131 web interface and schema-free JSON documents. Elasticsearch is
132 developed in Java and is released as open source under the terms of
133 the Apache License."_,
134 [Wikipedia](https://en.wikipedia.org/wiki/Elasticsearch)
135
136 The schema-free data store together with the easy RESTful interface
137 make [Elasticsearch]
138 (https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html)
139 a great place for `speedtest` to put its results.
140
141 There is a docker container for Elasticsearch available:
142 https://hub.docker.com/_/elasticsearch/
143
144 The results of `speedtest` may be posted to Elasticsearch:
145
146 # curl -XPOST localhost:9200/speedtest/results?pretty -d "$(speedtest http://k0s.org/playground/1M.bin | tail -n 1)"
147 {
148 "_index" : "speedtest",
149 "_type" : "results",
150 "_id" : "AVGNmWMTVkaacKUEikLl",
151 "_version" : 1,
152 "_shards" : {
153 "total" : 2,
154 "successful" : 1,
155 "failed" : 0
156 },
157 "created" : true
158 }
159
160 However, for lots of data we probably want to use the
161 [bulk API]
162 (https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html)
163
164 # speedtest 'http://k0s.org/playground/1M.bin' --fmt elasticsearch --chunk $((1024*1024)) -o 'http://1.2.3.4:32793/speedtest/results/_bulk'
165 {"took":1,"errors":false,"items":[{"create":{"_index":"speedtest","_type":"results","_id":"AVVU7PIeZtDhCquHQrZV","_version":1,"status":201}}]}
166
167 Note that the index and type *must* be specified in the output URL for this to work.
168 See https://www.elastic.co/blog/index-vs-type for clarification of why this is a
169 good thing.
170
171
172 JSON blobs are uploaded to an Elasticsearch instance.
173
174
175 ## Links
176
177 , ,
178 |`-._ _.-'|
179 \ `-' /
180 `-._ _.-'
181 `#'
182 ~~~~~~~~~~~~~
183
184 [Docker](http://docker.com/):
185
186 - https://docs.docker.com/machine/get-started/
187 - https://github.com/victorlin/crane
188 - https://docker-py.readthedocs.org/en/latest/
189
190
191 Elasticsearch:
192 - [The Definitive Guide](https://www.elastic.co/guide/en/elasticsearch/guide/index.html)
193 - https://www.elastic.co/guide/en/elasticsearch/reference/current/_modifying_your_data.html
194 - https://hub.docker.com/_/elasticsearch/
195 - [Python Elasticsearch Client]
196 (http://elasticsearch-py.readthedocs.org/en/master/index.html)
197 - https://bitquabit.com/post/having-fun-python-and-elasticsearch-part-1/
198
199
200 [Jeff Hammel](https://hub.docker.com/u/jehammel/)