# Speedtest

## The Pattern

`speedtest`
will use this pattern for outer loop testing:

- a [Docker](http://docker.io/) container is created from a
  `speedtest` script,
  and a docker
  [CMD]
  (https://docs.docker.com/v1.8/reference/builder/#cmd)
  that will run
  the appropriate test and post a JSON blob to an
  [Elasticsearch](https://www.elastic.co/) node

- the Docker container is dispatched to a container service
  such that it may be run at
  cloud scale and from a variety of regions

- the test [CMD]
  (http://docs.docker.com/engine/reference/builder/#cmd)
  of the container contains steps that will generate
  JSON data and post this to an Elasticsearch node.  This
  Elasticsearch data may then be analyzed and utilized for reporting
  of system status.

This pattern is of general utility for blackbox testing and monitoring
of a web system under test. Monitoring may be performed in a continuous
and ongoing basis, the Elasticsearch data combed for performance information.


## Installation

`speedtest` follows fairly standard
[python packaging]
(https://python-packaging-user-guide.readthedocs.org/en/latest/)
practices.  We do need other software, like
[docker](http://docker.io), to help us along.

Let's get started!


## What Speedtest Gives You

`speedtest` attempts to provide a suite of tools for making worldwide
dockerized speedtests a reality.  Many of these are provide in terms
of [setuptools](https://pythonhosted.org/setuptools/)
[entry points]
(https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins),
including
[console scripts]
(https://pythonhosted.org/setuptools/setuptools.html#automatic-script-creation).

Several console scripts are also installed with `speedtest`.
All provided console scripts utilize
[argparse](https://docs.python.org/2/library/argparse.html)
for their command line interface.  Detailed usage information for a
script may be obtained by using the `--help` command line switch.
For example: `speedtest --help` .


## About Speedtest

`speedtest` is a collection of scripts and utilities to make real the
pattern of docker container dispatch for data
gathering via JSON output to Elasticsearch.

While `Dockerfile`s are a good abstraction layer for building
[linux containers]
(https://en.wikipedia.org/wiki/LXC),
often the run steps must be automated and parameterized.

##  speedtest with local results

Usage information is available with the `--help` flag:

    speedtest --help

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.

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:

    speedtest --variables foo=bar --format json --chunk $((100*1024)) http://k0s.org/playground/1M.bin


## Containers

### Containerized Download Speed Testing

`speedtest.py`

(and, equivalently, the `speedtest` [console script]
(http://python-packaging.readthedocs.org/en/latest/command-line-scripts.html#the-console-scripts-entry-point))
measures download speed over time given a URL:

    # speedtest http://k0s.org/playground/1M.bin
    ...
    {"duration": 1.7867929935455322, "cumulative": 586848, "speed": 209367, "size": 1048576}


### Containerized Dispatching

- pull the Docker image from a container registry
- run the Docker image

### Container Registry

In order to make use of containerized dispatch, you may want a
[docker registry](https://docs.docker.com/registry/):

- https://docs.docker.com/registry/deploying/
- https://www.docker.com/docker-trusted-registry
- https://github.com/docker/distribution
- https://www.docker.com/aws

[Docker hub](https://hub.docker.com/)
has an official [Docker](https://www.docker.com)
repository for a
[Docker registry]
(https://hub.docker.com/_/registry/).  How meta is that?  You can get
started just by running:

    docker run registry:2


## Elasticsearch

_"Elasticsearch is a search server based on Lucene. It provides a
distributed, multitenant-capable full-text search engine with a HTTP
web interface and schema-free JSON documents. Elasticsearch is
developed in Java and is released as open source under the terms of
the Apache License."_,
[Wikipedia](https://en.wikipedia.org/wiki/Elasticsearch)

The schema-free data store together with the easy RESTful interface
make [Elasticsearch]
(https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html)
a great place for `speedtest` to put its results.

There is a docker container for Elasticsearch available:
https://hub.docker.com/_/elasticsearch/

The results of `speedtest` may be posted to Elasticsearch:

    # curl -XPOST localhost:9200/speedtest/results?pretty -d "$(speedtest http://k0s.org/playground/1M.bin | tail -n 1)"
    {
      "_index" : "speedtest",
      "_type" : "results",
      "_id" : "AVGNmWMTVkaacKUEikLl",
      "_version" : 1,
      "_shards" : {
        "total" : 2,
        "successful" : 1,
        "failed" : 0
      },
      "created" : true
    }

However, for lots of data we probably want to use the
[bulk API]
(https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html)

    # speedtest 'http://k0s.org/playground/1M.bin' --fmt elasticsearch --chunk $((1024*1024)) -o 'http://1.2.3.4:32793/speedtest/results/_bulk'
    {"took":1,"errors":false,"items":[{"create":{"_index":"speedtest","_type":"results","_id":"AVVU7PIeZtDhCquHQrZV","_version":1,"status":201}}]}

Note that the index and type *must* be specified in the output URL for this to work.
See https://www.elastic.co/blog/index-vs-type for clarification of why this is a
good thing.


JSON blobs are uploaded to an Elasticsearch instance.


## Links

     ,           ,
     |`-._   _.-'|
     \    `-'    /
      `-._   _.-'
          `#'
     ~~~~~~~~~~~~~

[Docker](http://docker.com/):

- https://docs.docker.com/machine/get-started/
- https://github.com/victorlin/crane
- https://docker-py.readthedocs.org/en/latest/


Elasticsearch:
- [The Definitive Guide](https://www.elastic.co/guide/en/elasticsearch/guide/index.html)
- https://www.elastic.co/guide/en/elasticsearch/reference/current/_modifying_your_data.html
- https://hub.docker.com/_/elasticsearch/
- [Python Elasticsearch Client]
  (http://elasticsearch-py.readthedocs.org/en/master/index.html)
- https://bitquabit.com/post/having-fun-python-and-elasticsearch-part-1/


[Jeff Hammel](https://hub.docker.com/u/jehammel/)